Weave Router 请求头控制终极清单：8个 x-weave-* 头如何精确操控路由
【免费下载链接】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
Weave Router 是一款面向 AI Agent 的模型路由器，能在 50ms 内将每个 prompt 路由到最合适的模型，通过更换一个 endpoint 即可降低 40–70% 的推理成本。它提供了一组x-weave-*请求头，让无界面客户端（CI、评测脚本、headless 集成）可以精确控制路由决策，无需任何 slash 命令。本文列出 8 个核心请求头，覆盖从模型固定、策略切换、评分旋钮调参到集群 A/B 测试的完整操控面。
🎯 快速总览
| # | 请求头 | 一句话用途 |
|---|---|---|
| 1 | x-weave-force-model | 将会话固定到指定模型 |
| 2 | x-weave-force-cluster | 限定本轮必须来自某个路由集群 |
| 3 | x-weave-allowed-models | 缩小路由候选模型范围 |
| 4 | x-weave-router-strategy | 按请求切换路由策略 |
| 5 | x-weave-routing-alpha等 | 微调评分函数的权重旋钮 |
| 6 | x-weave-router-debug | 开关策略调试模式 |
| 7 | x-weave-policy-pin | 锁定指定策略工件 + roster |
| 8 | x-weave-cluster-version | 按请求切换评分器版本（A/B） |
1.x-weave-force-model— 将会话固定到指定模型
作用：等价于在聊天窗口输入/force-model <模型名>，但通过 HTTP 头实现，适配无 UI 的 headless 客户端。
取值规则：
- 接受标准目录 ID（如
qwen/qwen3.8-max）、裸名称（qwen3.8-max）、或别名（opus、sonnet、gpt） - 可附加
:level难度后缀，如opus:high - 严格精确匹配，不支持前缀/模糊匹配；未知模型名直接返回HTTP 400
为什么严格：模糊匹配曾导致/fm qwen 3.8被解析为qwen/qwen3-coder并假装成功。现在整个命令行作为模型名解析，无法匹配则拒绝。
源码：internal/proxy/force_model.go
2.x-weave-force-cluster— 限定本轮来自某个路由集群
作用：将本轮请求约束到策略 sidecar 的某个命名集群（cluster），集群内的具体模型选择仍由策略决定。
关键规则：
- 接受不透明标签（opaque label），路由器不维护合法集群列表
- 标签不在当前 live roster 中 →HTTP 400（无论是拼写错误还是已退役集群）
- 标签在 roster 中但无可用模型（全部被排除/超窗/能力不匹配）→HTTP 400
- 仅在
hmm/hmm_embedding策略下有效；默认cluster策略无命名分组，发此头返回 400 - 不写入会话 pin：每轮独立生效，不改变后续请求行为
与force-model的区别：force-model写会话级 pin（后续请求沿用），force-cluster仅约束当前轮次。
源码：internal/proxy/force_cluster.go
3.x-weave-allowed-models— 缩小路由候选范围
作用：指定本轮请求只从给定模型子集中路由，相当于"临时白名单"。
行为：
- 与 installation 级 allowlist 取交集
- 未知别名或交集为空 →HTTP 400
- 未授权的调用方 →HTTP 403（不会静默回退到全量模型）
- 需要 installation 授权
policy_header_overrides_enabled，或组织级 flag 开启
典型场景：CI 流水线只允许路由到低成本模型，避免意外消耗高端模型配额。
源码：internal/server/middleware/allowed_models_override.go、internal/proxy/allowed_models_header.go
4.x-weave-router-strategy— 按请求切换路由策略
作用：覆盖 installation 持久化的路由策略，让单次请求使用不同评分算法。
可用值： | 值 | 说明 | |---|------| |cluster| 默认评分器（匿名质心评分） | |rl| 训练好的 RL/DPO 策略路由 | |bandit| Thompson 采样 + 冻结后验 | |hmm/hmm_embedding| HMM 隐马尔可夫分类器 |
优先级（从高到低）：
- 已授权的
x-weave-router-strategy请求头 - Installation 持久化策略
- 部署级默认值（
ROUTER_DEFAULT_STRATEGY）
安全规则：未授权的 installation 发送此头会被静默忽略（不报错、不 503），保证安全。
源码：internal/server/middleware/router_strategy_override.go
5.x-weave-routing-*旋钮组 — 微调评分权重
作用：在请求级覆盖评分函数的超参数，无需重启或修改部署配置。
可用头及取值范围：
| 请求头 | 范围 | 含义 |
|---|---|---|
x-weave-routing-alpha | [0, 1] | 质量 vs 成本的权衡系数 |
x-weave-routing-speed-weight | [0, 1] | 延迟/速度权重 |
x-weave-routing-output-cost-ratio | [0, 10] | 输出 token 成本放大比 |
x-weave-routing-expected-output-tokens | [0, 100000] | 预期输出 token 数 |
x-weave-routing-per-model-verbosity | true/false | 是否按模型细分评分 |
示例：CI 快速评测想优先速度 → 设置x-weave-routing-speed-weight: 0.9。
源码：internal/server/middleware/routing_knobs_override.go
6.x-weave-router-debug— 开关策略调试模式
作用：按请求覆盖 installation 持久化的策略调试开关，便于调试而不修改全局配置。
取值：true/false
行为：
- 未授权的 installation → 头被忽略，保持持久化值
- 非布尔值 → 同上，保持持久化值
- 合法布尔值 → 覆盖本轮调试状态
注意：此头与x-weave-router-strategy遵循相同的授权规则（policy_header_overrides_enabled）。
源码：internal/server/middleware/policy_debug_override.go
7.x-weave-policy-pin— 锁定策略工件 + Roster
作用：将本轮路由锁定到指定的策略工件（policy artifact）和 roster 版本，用于精确复现和回放。
取值格式：<policy_artifact_sha256>@<roster_sha256>
关键行为：
- 仅在
ROUTER_POLICY_PIN_ENABLED=true时生效 - 需 installation 开启
policy_header_overrides_enabled - 格式错误 →HTTP 400（
policy_pin_malformed） - 工件/roster 未加载 →HTTP 503（
policy_pin_unavailable） - 永不回退到当前默认工件 — 要么精确命中，要么失败
- 会话 pin、
force-model、usage-bypass 等在 pin 模式下全部绕过 - 遥测记录
policy_pin_requested/policy_pin_honoured
典型场景：评测回放、合规审计、生产问题精确复现。
源码：internal/server/middleware/policy_pin_override.go
8.x-weave-cluster-version— 按请求切换评分器版本
作用：指定本轮使用哪个版本的 cluster 评分器，实现无状态 A/B 测试。
取值：v0.X格式（如v0.3）
行为：
- 携带此头的请求路由到对应版本的 Scorer
- 未携带的普通流量始终使用部署默认版本（
ROUTER_CLUSTER_VERSION→artifacts/latest） - 用于评估框架的逐请求 A/B 对比，不影响线上生产流量
源码：internal/server/middleware/cluster_version_override.go
⚠️ 授权与错误处理通则
| 场景 | 行为 |
|---|---|
| 未授权 installation 发送 policy 类头 | 静默忽略（strategy、debug、pin） |
未授权发送allowed-models | HTTP 403 |
| 值格式/取值非法 | HTTP 400（按请求路径返回对应 API 格式的错误包） |
| 策略不可用（如 RL sidecar 未配置） | HTTP 503，不回退到 cluster |
设计哲学：宁可拒绝请求也不静默降级 — 拼写错误不会"看起来生效了"。
📎 相关文档与模块
- 完整配置参考：docs/CONFIGURATION.md
- 中间件实现目录：internal/server/middleware/
- 路由策略注册：internal/proxy/service.go
- 策略 sidecar 契约：docs/POLICY_ROUTER_HARNESS.md
- 遥测 schema（记录各头效果）：internal/analytics/schema.go
总结
Weave Router 的x-weave-*请求头体系为 headless 场景（CI/CD、评测 harness、自动化流水线）提供了与 slash 命令等价的完整控制面。从"固定到某个模型"到"锁定精确策略工件版本"，8 个请求头覆盖了日常运维和高级调试的全部需求。核心原则只有一个：严格验证，拒绝即失败，绝不假装成功。
【免费下载链接】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），仅供参考
