后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读Adaptation自适应是 semantic-router 中在线模型选择学习online model-choice learning的核心模块它在一次请求完成路由决策匹配、基础选择器选出模型之后基于该模型在生产环境积累的真实表现证据模型适配度、过度使用、故障、延迟、缓存复用与有效成本从一个受限候选集里在线提出更优模型的建议。本文以官方文档为主体结合仓库源码逐层讲解 Adaptation 的定位、三种候选集decision/tier/global的语义边界、routing_sampling策略的贝叶斯评分与保护机制、响应头与 Router Replay 诊断帮助读者掌握如何在不改写语义决策的前提下让路由策略在运行时持续自我优化。一、Adaptation 是什么发生在请求路径哪个环节1.1 基本定位官方文档将 Adaptation 定义为Adaptation is online model-choice learning. It runs after the matched decision and base selector, then proposes a model from an allowed candidate set.也就是说一条请求的模型选择链大致是匹配决策matched decision→ 基础选择器base selector→ Adaptation提出候选模型→ Protection最终把关。源码applyRouterLearningsrc/semantic-router/pkg/extproc/router_learning.go给出的执行顺序与此完全一致先做保护预检applyProtectionPreflight决定此刻是否允许随机探索采样再执行 AdaptationapplyLearningAdaptation提出模型切换建议最后由 Protection 的切换闸门applyProtectionSwitch对建议做最终裁决只有learningChangesModel判定最终模型与基础模型不一致时才认为本次请求真正应用了学习。关键设计是Adaptation 只负责提出proposeProtection 负责放行/拒绝switch guard。两者在响应头中都会留下自己的方法、动作与原因因此一次请求可能同时出现adaptation与protection两类学习记录。1.2 为什么需要它静态配方与运行时证据之间的差距静态配方recipe编码的是部署时运维人员对流量与模型的认知哪些请求该走哪个决策、决策绑定了哪些modelRefs。但生产环境真正的信息——某个模型是否频繁力不从心underpowered或大材小用overprovisioned、某条 provider 是否反复故障、延迟与缓存命中率如何、有效成本是多少——只有在运行时才会暴露。Adaptation 做的事情就是把这份有界证据bounded evidence转成在线模型提议而配方本身始终是策略的事实来源policy source of truth。它不会改写决策、不会改动 recipe只是让模型选择本身随着证据不断自我修正。二、何时启用 Adaptation官方文档给出四类典型使用场景同一决策有多个候选模型且运行时结果能够改进模型选择多个相关决策共享同一 tier决策层级希望它们能互相借鉴彼此的模型证据希望做在线探索exploration但前提是保护机制确认当前 Agent 状态安全、可以探索希望通过离线评测offline evals预置模型经验而不立即改动配方。第一条对应candidate_set: decision第二条对应candidate_set: tier第四条在源码中有直接支撑prepareEvalRequest/finishEvalLearningsrc/semantic-router/pkg/extproc/router_learning_preview.go允许离线评测通过只读快照routerLearningPreviewSnapshot喂入经验与种子从而在不触碰线上状态的前提下预演 Adaptation 会怎样选择。三、配置全局开关与策略选择3.1 最小配置示例官方文档给出第一份配置启用routing_sampling策略global: router: learning: enabled: true adaptation: enabled: true strategy: routing_sampling candidate_set: decision对应到源码结构src/semantic-router/pkg/config/learning_config.goglobal.router.learning下有四个子配置配置路径结构体说明learning.enabledRouterLearningConfig.Enabled总开关缺省视为关闭learning.adaptationRouterLearningAdaptationConfigAdaptation 本体enabled/candidate_set/strategylearning.protectionRouterLearningProtectionConfig保护机制enabled/scope/identity/tuninglearning.state_storeRouterLearningStateStoreConfig可选的共享保护状态存储local或redis3.2 默认值语义RouterLearningAdaptationConfig提供了三个Effective*方法源码明确EffectiveEnabled()Enabled nil || *Enabled即不写adaptation.enabled视为开启在总开关开启前提下EffectiveCandidateSet()candidate_set为空时回退为decisionEffectiveStrategy()strategy为空时回退为routing_sampling。因此最小写法甚至可以只保留adaptation.enabled: true。不过官方示例显式写出全部字段便于运维一目了然。3.3 校验规则配置写错会被拒绝配置加载时的校验逻辑位于 src/semantic-router/pkg/config/validator_learning.gocandidate_set只允许decision、tier、global三者之一空值按默认decision处理否则报错global.router.learning.adaptation.candidate_set must be decision, tier, or globalstrategy目前只允许routing_sampling其他值直接报错决策级adaptations.mode只允许apply/observe/bypass三种模式模式边界约束当决策级adaptations.mode为bypass时其下adaptation/protection子组件模式必须同为bypass当决策级模式为observe时子组件不能设为apply只能保持 observe 或为空继承。3.4 决策级覆盖decision-level adaptations除了全局配置单个决策可以在 recipe 中通过adaptations覆盖全局学习行为src/semantic-router/pkg/config/learning_config.go 的DecisionAdaptationsConfigdecisions: - name: some_decision adaptations: mode: apply # apply | observe | bypass adaptation: mode: apply candidate_set: tier # 决策级覆盖候选集 protection: mode: apply stability_weight: 0.9 switch_margin: 0.05源码中AdaptationMode()与AdaptationCandidateSet()的优先级逻辑是决策级显式值优先未写则继承全局若决策级mode为observe即使子组件写apply也会被压制回observe即决策级 observe 是只观测、不生效的硬边界。四、候选集Candidate Set搜索边界即安全边界4.1 三种候选集的语义取值候选模型来源说明decision命中决策的modelRefs最安全默认值搜索空间最小tier同decision.tier的所有决策的modelRefs并集让同层级相关路由共享候选与经验global配方模型/provider 清单中所有已部署模型最广可提出不在命中决策modelRefs中的模型官方文档特别强调global范围最广可能提出未出现在命中决策modelRefs中的部署模型因此它附带更严格的成本与可靠性护栏。这一表述在源码中得到量化印证4.2 源码中的边界实现与惩罚系数learningCandidateModelssrc/semantic-router/pkg/extproc/router_learning_adaptation.go按候选集取值构建模型清单tier收集decision.Tier tier的所有决策的modelRefs并集globaldeployedLearningModelRefs会把默认模型、全部决策modelRefs、全部VLLMEndpoints的模型以及ModelConfig中的模型去重合并默认decision直接克隆当前选择上下文中的候选模型。候选集的边界同时体现在评分惩罚系数上costPenalty与routingSamplingMargin候选集成本惩罚系数切换所需最小 margindecision0.04 × (模型输入成本/最大成本)0tier0.060.03global0.100.08可以看到候选范围越宽成本惩罚越重、切换门槛越高这正是global 使用更严格护栏的实现细节。candidateCostMargin还会在获胜者比基础模型更贵时追加惩罚差值的 margin防止为了一点质量提升而显著加价。4.3 候选集是硬边界官方文档强调两个不会Protection 不会把候选集之外的旧会话模型重新引入不会让已学习到的连续性推翻命中决策或模型能力契约已知上下文窗口不足的候选会在 Adaptation 之前被剔除candidate_requirements相关逻辑负责能力契约过滤。也就是说候选集解析结果是一个不可逾越的硬边界——学习可以改选谁但不能改选不该出现在这里的谁。五、routing_sampling 策略从证据到评分的完整算法5.1 评分输入模型级经验routing_sampling对每个候选模型从模型经验routerLearningModelExperience定义于 src/semantic-router/pkg/extproc/router_learning_runtime.go读取以下维度字段含义QualitySeed/SeedWeight离线或中性质量种子离线评测预置经验的入口GoodFitCount/UnderpoweredCount/OverprovisionedCount/FailedCount四类运行时结局计数LatencyEWMA延迟指数滑动平均CacheHitEWMA/CacheWriteEWMA缓存命中/写入指数滑动平均InputCostMultiplierEWMA有效输入成本倍率滑动平均LastUpdated最近更新时间用于冷启动判定官方文档列出的评分证据清单——离线质量种子、good_fit/underpowered/overprovisioned/failed结局、延迟证据、缓存复用证据、有效输入成本、可靠性证据——在源码的routerLearningModelExperience结构体中一一对应。5.2 贝叶斯评分公式源码级scoreRoutingSamplingCandidatessrc/semantic-router/pkg/extproc/router_learning_adaptation.go对每个模型执行先验/后验均值把质量种子与好坏结局计数折成 Beta 分布的 α、β 参数α SeedWeight × QualitySeed GoodFitCount 1 β SeedWeight × (1 − QualitySeed) UnderpoweredCount 1 posteriorMean α / (α β)预测质量默认取后验均值predicted mean当保护允许探索且使用采样时predicted sampleBeta(α, β, rng)——即从 Beta 后验中随机抽取一个值实现受控的在线探索。sampleBeta通过sampleGammaMarsaglia-Tsang 算法实现。各项惩罚与调整所有项都先clamp01到 [0,1]costPenalty costMultiplier(candidateSet) × (模型输入成本 / 候选最大成本) 0.03 × InputCostMultiplierEWMA overusePenalty 0.03 × OverprovisionedCount / 总结局数 reliabilityPenalty 0.10 × FailedCount / 总结局数 latencyAdjustment −0.02 × LatencyEWMA cacheAdjustment 0.02 × CacheHitEWMA其中模型输入成本取自ModelConfig[model].Pricing的prompt_per_1m completion_per_1mmodelInputCost。此外若候选恰好是基础选择器选中的模型会获得0.001的微小倾向分stay bias 的一个实现细节。最终得分score predicted − costPenalty − overusePenalty − reliabilityPenalty latencyAdjustment cacheAdjustment得分按降序稳定排序平局时按模型名字典序。5.3 获胜者选择采样与确定性两条路径routingSamplingWinner的逻辑分两条路径保护允许探索usedSamplingtrue先从得分列表取第一个coldStart候选LastUpdated为零即该模型还没有任何线上结局记录。冷启动候选优先——这是让新模型有机会被尝试的关键机制若无冷启动候选则取确定性得分最高的模型。保护抑制探索usedSamplingfalse全部按后验均值确定性排序直接取得分最高者不做随机抽取。5.4 何时触发 keep_baseselectRoutingSamplingWinner里有一条兜底规则当获胜者不是基础模型但winner.score baseScore requiredMargin时强制回到基础模型动作keep_base原因base_best。其中requiredMargin routingSamplingMargin(candidateSet) candidateCostMargin(...)。也就是说模型切换必须赢出足够多而不是略胜即可避免在线学习导致模型在质量、成本边缘来回抖动。5.5 动作语义routingSamplingAction输出三类动作情形动作原因决策处于observe模式observeobserve_only获胜者就是基础模型keep_basebase_best采样探索下换了模型propose_switchsampled_win确定性均值下换了模型propose_switchposterior_win当获胜模型是冷启动候选且处于apply模式时原因改写为cold_start便于诊断。5.6 冷启动候选的保底失败路径官方文档说Protection 仍然拥有最终发言权而 Adaptation 自身也有多层保底候选集为空返回candidate_set_empty、策略不可用返回strategy_unavailable、无评分返回scores_missing、所选模型最终找不到对应ModelRef返回selected_model_missing——所有这些情况都安全回退为keep_base不会破坏基础选择结果。六、Protection 如何与 Adaptation 协同6.1 探索许可sampling allowedapplyProtectionPreflightsrc/semantic-router/pkg/extproc/router_learning_protection.go在 Adaptation 之前就给出samplingAllowed预检结论依据包括决策/协议状态若命中决策模式不是apply、或会话中存在活动工具循环ActiveToolLoop、或存在不可移植上下文HasNonPortableContext则禁止采样原因tool_or_protocol_stateAgent 会话稳态若存在暖的上一模型CacheWarmth 0.65且CacheWarmthOK判定为steady_state禁止采样倾向保持当前模型这正是文档所说保护在随机采样之前的保护身份缺失missing_identity无法解析会话/对话身份时直接抑制采样observe/bypass模式下同样禁止采样。6.2 切换闸门switch guard即使 Adaptation 提出了propose_switchProtection 的切换闸门还会用稳定性权重、切换成本、margin 等参数做最终裁决——可能输出allow_switch放行、hold_current保持当前、rescue_switch强制救援切换等动作。因此一条请求最终的模型可能是adaptationpropose_switchprotectionallow_switch→ 真正切换adaptationpropose_switchprotectionhold_current→ 学习提议被保护机制拦截保持当前模型。官方文档诊断示例中的protectionhold_current, reasoncache_cost_high正是这种提议被闸门拦截的可观测形态。七、诊断与可观测性7.1 紧凑响应头官方文档给出的示例响应头x-vsr-learning-methods: adaptation,protection x-vsr-learning-actions: adaptationkeep_base,protectionhold_current x-vsr-learning-reasons: adaptationbase_best,protectioncache_cost_high这些头的定义位于 src/semantic-router/pkg/headers/headers.gox-vsr-learning-methods本次请求参与的学习方法如adaptation或adaptation,protectionx-vsr-learning-actions按方法键控的紧凑决策如adaptationpropose_switch,protectionallow_switchx-vsr-learning-scopes保护作用域如protectionconversationx-vsr-learning-reasons按方法键控的原因如adaptationsampled_win,protectionswitch_allowed。头保持紧凑详细诊断不下发到响应路径而是写入 Router Replay 供离线分析。7.2 Router Replay 的详细诊断Router Replay 的 typed 存储结构定义于 src/semantic-router/pkg/routerreplay/store/learning_diagnostics.go官方文档列出其保存字段候选得分、后验均值、采样值、基础模型、提议模型、最终模型、候选集、策略与原因。对应结构体字段LearningDiagnosticsprotection_preflight/adaptation/protection三段 protection_state_keyLearningAdaptationDiagnosticscandidate_set、strategy、base_model、proposal_model、decision、decision_tier、sampling含used与seed、scoresLearningCandidateScorescore、posterior_mean、predicted_quality、cost_penalty、overuse_penalty、reliability_penalty、latency_adjustment、cache_adjustment——与评分公式逐项对应任何一次学习决策都可以被完全复盘。routerLearningAdaptationDiagnostics.toPolicyMapsrc/semantic-router/pkg/extproc/router_learning_adaptation.go把这些信息同时以策略映射的形式挂到请求上下文采样时还会记录随机种子seed保证探索过程可复现、可审计。7.3 采样种子的来源在线请求的采样种子来自time.Now().UnixNano()routerLearningSamplingSeedSource而在离线评测/预览路径中种子来自routerLearningPreviewSnapshot.Seed可由调用方显式传入SamplingSeed保证评测场景可复现。这正对应官方文档offline evals to seed model experience的诉求——离线评测不仅能预置质量种子还能用固定种子稳定复现采样决策。八、落地实践建议先用observe模式灰度全局或决策级先把adaptations.mode设为observe让 Adaptation 只输出诊断与propose_switch建议而不实际改模型通过 Router Replay 观察posterior_win/sampled_win的频率与合理性再切换到apply。候选集从小到大优先decision最安全需要跨决策学习时再升到tierglobal仅在已充分理解成本与可靠性护栏时使用因为它会引入不在命中决策modelRefs中的部署模型。关注冷启动路径cold_start与cold_start_win是判断新模型是否获得探索机会的关键信号若长期无冷启动候选说明候选集内所有模型都已有经验记录。把响应头与 Replay 串起来排障线上看到x-vsr-learning-actions: adaptationpropose_switch,protectionhold_current时说明学习想换模型但保护闸门基于会话连续性/缓存成本拦截了切换——此时应查 Replay 中的protection诊断switch_cost、stability_weight、cache_warmth而非 Adaptation 本身。配置先过校验candidate_set与strategy的取值由 validator_learning.go 强制校验写错会直接导致配置加载失败决策级adaptations与全局配置的继承/覆盖关系务必按决策级优先、空则继承、observe 是硬边界的规则设计。九、总结Adaptation 把生产环境中的模型表现证据转化为受保护、受约束的在线模型提议candidate_set划定硬边界routing_sampling用贝叶斯后验 成本/过度使用/可靠性惩罚 延迟/缓存调整给出可解释评分Protection 在采样前与切换前双重把关紧凑响应头 Router Replay 保证全程可观测、可复盘。掌握这套机制后你可以在不触碰语义决策与配方的前提下让路由器随真实流量证据持续收敛到更合适的模型组合——这正是 semantic-router 作为可编程决策层在模型与算力之上提供的运行时智能。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Semantic Router 的 ML 模型选择器knn / kmeans / svm / mlp 四种学习式选择算法的配置、原理与训练产物Semantic Router 的 ML 模型选择器knn / kmeans / svm / mlp 四种学习式选择算法的配置、原理与训练产物 本文围绕 se后端API网关模型推理服务AI Agent破解浏览器本地交互难题的终极解决方案PluginOK中间件技术深度解析破解浏览器本地交互难题的终极解决方案PluginOK中间件技术深度解析 在当今数字化转型浪潮中企业面临着一个严峻的技术挑战如何在现代化的浏览器环境中无缝集semantic-router 的 AutoMix 选择器基于 POMDP 的成本-质量权衡模型选择算法详解与配置实战semantic router 的 AutoMix 选择器基于 POMDP 的成本 质量权衡模型选择算法详解与配置实战 AutoMix automix 是后端API网关模型推理服务AI Agent上一篇使用 Ray Tune 与 PyTorch 调优 MNIST 手写数字识别模型的完整实战指南下一篇Spaceship Prompt 的 PureScript 分区版本展示、触发条件与源码级配置解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考