Weave Router force-model完全指南用x-weave-force-model头固定指定模型【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/routerWeave Router 是一款面向 Agent 系统的模型路由器model router能在 50ms 内把每个 prompt 路由到最合适的模型通常只需把 API 端点改一下就能帮你的 Agent 应用省下 40%–70% 的成本。默认情况下它自动做路由决策但有时你只想我就要用这一个模型——这时候force-model就登场了。对于无法输入斜杠命令的无头客户端CI、评测框架、脚本x-weave-force-model请求头就是/force-model命令的无头等价物一个头就能把整个会话固定到你指定的模型上。为什么需要 x-weave-force-model 头在交互式终端里Claude Code、Codex 等你可以直接输入/force-model model别名/fm来固定当前会话使用的模型。但这类斜杠命令会在到达路由器之前就被客户端当作本地命令吃掉脚本和 CI 环境根本没有打字的入口。为此 Weave Router 提供了x-weave-force-model请求头。它的核心行为定义于 force_model.go写在每个请求上头随每个请求携带路由器每收到一次就重新写入会话固定session pin并在同一轮直接按该模型提供服务语义与/force-model完全一致同样的精确匹配规则、同样的会话级固定效果失败即报错绝不假装生效拼错的模型名会直接让请求失败而不是悄悄路由到别的模型这是官方刻意的设计模糊匹配会让调用方收到一个从未请求过的模型还误以为固定生效了。宁可显式失败。三种合法的模型写法规范 ID、裸名、别名x-weave-force-model的值支持三种写法详见 CONFIGURATION.md写法示例说明规范目录 IDcanonical IDqwen/qwen3.8-max模型目录中的完整 ID最稳妥裸名bare nameqwen3.8-max去掉厂商前缀的模型名仅当不歧义时可用别名aliasopus、gpt、qwen-max指向当前该家族的旗舰模型内置了上百个常见别名映射表见 force_model.go 别名定义几个典型例子opus/claude/anthropic→claude-opus-5gpt/openai→gpt-5.6-solqwen/qwen-coder→qwen/qwen3-codergemini/google→gemini-3-pro-preview⚠️匹配是精确的不做前缀、子串或最接近回退。比如/fm qwen 3.8里的空格会导致整个值无法解析而被拒绝——这种严格性正是为了防止误配。进阶一个头同时固定模型 设置努力等级Effort在模型名后追加:level后缀可以在固定模型的同时指定推理努力等级源码中的剥离与校验逻辑见 stripEffortSuffix示例opus:high、gpt:low合法后缀fast、low、medium/med、high、max、xhigh、ultra、minimal/min没有后缀时使用模型自身的默认 effort。这一能力对应数据库层session_pins表的effort列0076_session-pin-effort.up.sql。固定后的会话行为一次写入全程生效理解固定机制关键在于session pin会话固定记录写入applyForceModelHeader校验通过后会把模型写入以force_model为角色的会话 pin 记录且永不过期setForceModelSessionPin覆盖范围pin 作用于共享同一客户端会话身份的所有父子 Agent 线程与首轮 prompt 和当前路由策略无关优先级高固定 pin 会压过自动路由的各类决策包括自动压缩触发的硬 pin测试佐证见 force_model_tier_fallback_internal_test.go解绑普通对话不会刷新该记录只有再次 force 或显式清除才会改变它想恢复自动路由在客户端输入/unforce-model别名/ufm即可命令说明见 unforce-model.md。清除操作会留下一个持久墓碑记录防止旧线程上的固定残影复活clearForceModelSessionPin。错误处理什么情况下会收到 HTTP 400两种情况会让携带x-weave-force-model的请求直接失败而非降级处理场景行为说明值不匹配任何目录模型HTTP 400错误类型为ForcedModelUnknownError明确报出无法解析的值定义见 L31-L48模型被排除策略禁用HTTP 400所有可能提供该模型的 provider 都被排除时拒绝强制并说明原因被排除的模型拒绝逻辑见 applyForceModelHeader。排除exclusion是权威策略而非偏好连显式强制都绕不过它。已固定的会话如果其固定模型后来被排除同样会显式失败而不是悄悄退回自动路由——此时请用/unforce-model清除。冒烟测试中也有专门断言未知x-weave-force-model值会在派发到上游之前就被 400 拒绝SMOKE.md。对比x-weave-force-model 与 x-weave-force-clusterWeave Router 其实提供了一对强制头区别值得了解CONFIGURATION.md 对照表请求头效果是否写 session pinx-weave-force-model把会话固定到一个模型✅ 写入整个会话生效x-weave-force-cluster把服务限制在一个路由集群内集群内选择仍交给策略❌ 不写入仅当次请求生效简单记model 头管用哪个模型cluster 头管从哪组里选。集群头只支持hmm/hmm_embedding策略且集群标签必须存在于策略 sidecar 当前报告的 roster 中否则同样 400。在 CI 和评测框架里怎么用无头场景正是这个头的设计初衷。项目内置的 Codex 评测基准就用它来固定对照组模型bench/weave_bench/arms.py 与 codex_config.py基准中的router-sol、router-luna等臂就是带x-weave-force-model头的路由器用来衡量路由器自身开销bench/README.md冒烟测试的每次模型调用都通过该头固定目标模型保证决策可复现smoke/harness_test.go用法非常直接在任意指向路由器的请求上加上该头即可例如把x-weave-force-model: gpt-5.6-luna加入请求头该会话后续所有轮次都会由gpt-5.6-luna提供服务直到你换值或清除固定。快速上手清单确认目标模型在目录中不确定 ID 时先列出可用模型Claude Code 里用/router-models别名/models终端里用npx weave-os/router models --claude命令说明见 router-models.md请求头加值规范 ID、裸名或别名均可精确匹配需要调力度就加后缀模型名:high一次搞定别被 400 吓到它是宁缺毋滥的护栏修正模型名即可用完记得解绑/unforce-model恢复自动路由相关源码与文档索引资料路径force-model 核心实现头解析、别名、pin 写入internal/proxy/force_model.go官方配置文档强制模型/集群章节docs/CONFIGURATION.md/force-model斜杠命令定义install/commands/force-model.md/unforce-model清除命令定义install/commands/unforce-model.md会话 pin 的 effort 列迁移db/migrations/0076_session-pin-effort.up.sql无头固定模型的行为测试service_session_pin_test.go冒烟测试中的头行为断言docs/SMOKE.md掌握x-weave-force-model后你可以在任何自动化流程里精确控制模型选择固定它做回归评测、锁定它做成本对比、或临时指定最强模型攻克最难的任务——而一旦需要一个/unforce-model就能让 Weave Router 重新接管自动路由。【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考