后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读本文围绕 semantic-router 的「决策自适应Decision Adaptations」机制展开它允许一个已匹配的路由决策decision在「继承全局在线学习行为」之外自主决定全局路由学习Router Learning的调整能力——是直接应用apply、仅观察observe还是完全绕过bypass并可在决策局部覆盖自适应候选集candidate_set与防护稳定性参数stability_weight、switch_margin。读完本文你将掌握决策级 adaptations 的完整 YAML 配置、三种模式的优先级语义、候选集选择原理、防护调优的底层实现以及对应的校验规则与可观测性输出。本文以 决策自适应官方文档 为骨架结合仓库源码与参考配置深入展开。什么是决策自适应把策略边界放回决策身边在 semantic-router 中全局路由学习global.router.learning默认对所有已匹配的决策生效自适应组件adaptation会根据跨请求经验提议更换模型防护组件protection负责维持会话/对话级稳定性避免模型在 Agent 会话中途被频繁切换。全局学习很方便但并非每个决策都适合被在线状态调整——隐私、仅本地、安全、合规和运维类路由往往需要硬边界。决策自适应routing.decisions[].adaptations正是为此设计的它让已匹配的决策最终决定学习是应用、观察还是绕过。代码注释中明确说明该字段采用复数命名DecisionAdaptationsConfig因为它同时控制多个学习组件自适应与防护在决策边界上的行为参见 决策配置结构定义。大多数决策应当继承全局学习行为只有少数需要硬边界、仅观察发布或少量防护调优的决策才需要显式添加adaptations块——这是一种稀疏式配置设计routing.decisions[].adaptations字段在 配置 Schema 中是可选的。主要优势把策略边界放在拥有它们的决策附近学习豁免与路由规则写在同一个 decision 块里可读性与可审计性更好让敏感路由用一个小块绕过学习仅需几行 YAML 即可为隐私/安全/合规路由建立硬边界无需改动全局配置支持在自适应或防护影响流量之前进行仅观察发布observe模式先记录诊断、验证效果再决定是否切换为apply让一个决策使用比全局默认更窄或更宽的自适应候选集通过adaptation.candidate_set在decision/tier/global之间调整搜索范围让一个决策在不更改全局默认的情况下调整稳定性权衡决策局部覆盖stability_weight与switch_margin。解决什么问题全局学习方便但并非每个决策都应在线上被调整。隐私、仅本地、安全、合规和运维路由常常需要硬边界——它们要么不允许在线学习更改已匹配的模型要么只允许观察诊断而不改变最终路由。决策自适应让策略边界成为路由配置的一等公民学习组件的生效与否由决策自己决定而不是由全局开关一刀切。何时使用当以下任一场景成立时为该决策添加adaptations已匹配的决策不得被在线学习更改——例如合规审计要求该路由始终命中固定模型希望在允许路由变更之前比较学习诊断——先用observe上线比对诊断后再收紧某个决策应搜索整个路由 tier而大多数决策留在自己的modelRefs内——用adaptation.candidate_set: tier扩大候选集某个决策需要比默认更强或更弱的防护余量——覆盖switch_margin同一决策的自适应和防护需要不同模式——例如自适应仅观察而防护保持应用。配置实战硬边界使用mode: bypass最典型的用法是隐私/安全类决策要求命中本地模型、绝不参与在线学习。此时整个adaptations块只需一个字段routing: decisions: - name: local_privacy_policy description: Keep privacy-sensitive traffic on the local model. priority: 200 modelRefs: - model: local-private-model adaptations: mode: bypassadaptations.mode: bypass会覆盖组件级模式阻止自适应和防护组件更改路由。从源码看AdaptationMode()与ProtectionMode()在决策模式为bypass时都会直接返回bypass参见 学习配置默认值实现。仓库参考配置 config/config.yaml 中同样存在adaptations: mode: bypass的真实用法。组件级拆分控制当自适应和防护应当表现不同时例如自适应先观察验证、防护继续实际保护会话使用组件级控制adaptations: adaptation: mode: observe candidate_set: tier protection: mode: apply这里自适应组件进入observe记录诊断但不改路由并搜索整个 tier防护组件保持apply可以阻止或允许模型切换。两个组件的模式、候选集与调优参数完全独立。三种模式语义模式含义apply该组件可以影响最终路由。observe该组件记录诊断但不能更改最终路由。bypass该组件不调整此决策。关键语义均有源码与测试佐证adaptations.mode省略时默认值为applyEffectiveMode()逻辑learning_config.go组件级mode省略时继承决策级modeAdaptationMode()/ProtectionMode()中对空组件模式的回退逻辑决策级observe会封顶组件级apply即adaptations.mode: observe时即使组件写mode: apply最终生效仍为observe——防止决策级只观察、组件级却悄悄改路由的矛盾配置adaptations.mode: bypass时组件模式只能同为bypass任何observe/apply都会被校验器拒绝该模式的边界约束由 validator_learning.go 中的validateDecisionComponentModeBoundary强制校验并在 validator_learning_test.go 中有对应的接受/拒绝测试用例。候选集candidate_set决策、tier 还是全局adaptation.candidate_set是可选的。省略时该决策继承global.router.learning.adaptation.candidate_set若全局也未配置则默认回落到decisionlearning_config.go。允许的取值取值含义代码常量decision自适应只在该已匹配决策的modelRefs内搜索全局默认RouterLearningCandidateSetDecisiontier自适应搜索该决策所属 tier 内所有决策的模型并集RouterLearningCandidateSetTierglobal自适应搜索全部已部署模型库存默认模型、所有决策 modelRefs、vLLM 端点、model_configRouterLearningCandidateSetGlobal候选集的扩大会显著改变搜索空间与评分行为这一点在运行时实现 router_learning_adaptation.go 中非常明确tier会调用unionRecipeDecisionModelRefs按decision.Tier汇总同 tier 决策的模型并集global会调用deployedLearningModelRefs汇总默认模型、全部决策 modelRefs、VLLMEndpoints 与 ModelConfig 中的全部模型去重后decision默认分支仅克隆当前选择上下文中的候选模型。同时候选集还影响评分倾向决策候选集的成本惩罚乘数为0.04tier 为0.06global 为0.10——候选范围越大成本惩罚越重防止自适应在大搜索空间里随便选中昂贵模型胜出所需的最小得分优势margin在 tier 为0.03、global 为0.08router_learning_adaptation.go。决策局部防护调优仅当某个决策需要不同于全局默认的稳定性权衡时才使用决策局部防护调优adaptations: protection: stability_weight: 1.5 switch_margin: 0.10protection.stability_weight更高的值更偏向稳定更低的值让自适应更容易切换模型。省略时默认1.0protection.switch_margin此决策切换前所需的最小模型优势得分差值省略时继承全局默认0.05见 会话感知选择器默认配置。这两个字段均为可选的*float64通过ApplyProtectionTuning在决策被选中后叠加到全局防护调优之上且不会修改全局配置learning_config.go。stability_weight 的底层机制从防护运行时实现看stability_weight并非一个独立的评分项而是统一缩放多个稳定性相关权重PrefixCacheWeight前缀缓存亲和、HandoffPenaltyWeight交接惩罚、SwitchHistoryWeight切换历史、ToolLoopStayBias工具循环驻留偏向会全部乘以该系数router_learning_protection.go。因此stability_weight 1缓存亲和、驻留偏向与切换惩罚同时增强模型更难被切换适合对连续性敏感的 Agent 路由stability_weight 1上述权重被削弱自适应与选择器更容易切换模型适合需要快速纠正错误模型的场景stability_weight 1默认或省略时直接保持基线权重不变。switch_margin 的作用switch_margin定义的是此决策内切换模型前必须达到的最小优势。运行时在防护切换判定switchGateVerdict与 session-aware 选择器中使用它当候选模型对当前模型的得分优势小于 margin 时选择器保持当前模型并产生switch_margin_not_met之类的策略原因可在 测试数据样例 中看到switch_margin_not_met、hold等诊断字段。决策级设置0.10意味着该路由比其他决策更难发生模型切换。运行时流程与模式如何生效决策自适应不是独立执行阶段而是嵌入全局学习管道base selector - protection preflight - adaptation - protection switch guard - final model保护预检preflightapplyProtectionPreflight依据ProtectionMode()决定本次请求是否允许采样与切换若为bypass直接返回decision_bypass策略后续学习组件全部停用router_learning_protection.go自适应applyRoutingSamplingAdaptation依据AdaptationMode()计算候选得分observe模式只产出诊断observe_only策略而不改动选择结果router_learning_adaptation.go防护切换闸门最终模型切换还必须通过 session-aware 选择器与 progress gate 的检查。自适应评分采用routing_sampling策略以 Beta-Bernoulli 后验均值为基础叠加成本惩罚、过度供给惩罚、可靠性失败率惩罚、延迟与缓存命中调整项再按模式决定是否用 Beta 分布采样探索sampling.used与seed会写入诊断。observe模式下不会采样adaptationSamplingAllowed对非apply模式返回false因此观察模式产出的是纯后验诊断适合用于发布前的效果评估。校验规则与错误边界仓库对决策自适应配置做了严格校验validator_learning.go常见错误会在配置加载时被直接拒绝mode仅允许apply/observe/bypass空值视为未设置非法值报错adaptations.adaptation.candidate_set仅允许decision/tier/global如cluster这类旧值会被拒绝stability_weight、switch_margin不允许为负决策级bypass下组件模式只能是bypass决策级observe下组件模式不能是applyadaptations块仅允许mode、adaptation、protection三个字段其余未知字段如旧的coordination、session_aware会被拒绝protection下不允许出现candidate_set历史迁移字段如决策内的algorithm.session_aware、全局旧global.router.learning.adaptations复数写法都会被明确拒绝并提示迁移目标见 loader.go 迁移校验。对应的接受/拒绝用例集中在 validator_learning_test.go完整解析含决策级 observe/候选集覆盖/防护调优与 validator_learning_test.go决策级 bypass 覆盖两个组件。可观测性策略头与诊断输出决策自适应的生效结果会通过x-vsr-learning-*响应头族对外暴露紧凑设计x-vsr-learning-methods: adaptation,protection x-vsr-learning-actions: adaptationpropose_switch,protectionallow_switch x-vsr-learning-scopes: protectionconversation x-vsr-learning-reasons: adaptationsampled_win,protectionswitch_allowed当决策处于observe或bypass时actions中会对应出现observe_only、decision_bypass等取值便于确认决策局部控制是否如预期生效。启用 Router Replay 后详细的 base_model、proposal_model、final_model、candidate_set、策略原因、采样种子与逐模型得分诊断会按x-vsr-replay-id持久化供离线vllm-sr optimize recipe-learning分析使用。相关字段定义可参考 学习策略字段常量 与 学习总览文档。与全局学习的配合要点决策自适应是全局 Router Learning 的决策级覆盖层两者配合的默认行为如下learning_config.go配置项默认值说明global.router.learning.enabledfalse总开关必须显式开启adaptation.enabled/protection.enabledtrue受总开关约束global.router.learning.adaptation.candidate_setdecision决策级省略时继承它protection.scopeconversation会话/对话级稳定性范围防护身份头x-session-id、x-conversation-id可通过protection.identity.headers覆盖注意防护依赖客户端携带稳定的会话/对话身份头缺失身份时该请求不参与防护并产生诊断。参考配置 config/config.yaml 中全局学习已开启candidate_set: decision、scope: conversation、switch_margin: 0.05、stability_weight: 1.0与本文示例可直接对照使用。参考路径索引官方文档原文decision-adaptations.md决策与自适应配置结构decision_config.go模式与候选集常量、默认值逻辑learning_config.go配置校验实现validator_learning.go校验测试用例validator_learning_test.go运行时自适应实现router_learning_adaptation.go运行时防护实现含稳定性权重缩放router_learning_protection.go会话感知选择器默认值session_aware.go配置 JSON Schemarouter-config-v0.3.schema.json参考配置文件config/config.yaml赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐semantic-router 决策级适应Decision Adaptations为单个路由决策定制 Router Learning 边界、观测与保护策略semantic router 决策级适应Decision Adaptations为单个路由决策定制 Router Learning 边界、观测与保护策略后端API网关模型推理服务AI Agentsemantic-router 的 Router Learning 设计解析在线自适应模型路由、会话稳定性保护与离线配方学习semantic router 的 Router Learning 设计解析在线自适应模型路由、会话稳定性保护与离线配方学习 本文依据仓库中的 Router后端API网关模型推理服务AI Agentsemantic-router 的 decision 选择算法让决策模型为每条请求挑选最合适的模型semantic router 的 decision 选择算法让决策模型为每条请求挑选最合适的模型 导读 decision 是 vLLM semantic r后端API网关模型推理服务AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考