14.2 模型网关与路由：能力、政策、Fallback 和版本合同

工坊同时接入了本地小模型、远程通用模型和一套高成本推理模型。最初的路由规则只有一句：“简单问题走便宜模型。”很快就出现三个问题：路由器把专业短问题当成简单问题；供应商限流后请求被悄悄切到不支持工具调用的模型；同一版本名称背后的行为发生变化，却没人知道。

模型网关要统一协议、身份、预算、版本和观测；路由器要在明确能力与政策约束内选择候选。它们不是把所有差异藏起来，而是把差异显式编码成可验证合同。

本课目标

• 设计 canonical request/response 和 capability manifest；
• 区分静态、规则、分类器与 cascade routing；
• 处理 provider failure、rate limit 和 incompatible fallback；
• 对 model/prompt/tool/safety policy 做 resolved versioning；
• 通过 shadow、canary 和 paired evaluation 验证路由变化。

1. 网关先统一“最小公共语义”

Canonical request 可包含：

principal / tenant / request_id / deadline
task_type / messages / attachments
required capabilities: tools, vision, JSON schema, logprobs...
data residency / retention / sensitivity policy
quality tier / latency tier / cost budget
model allowlist / denylist / pinned revision
sampling / stop / max output

Canonical response 除文本外，还返回 resolved provider/model revision、finish reason、usage、tool calls、safety decisions、latency breakdown 和 trace ID。

供应商对 system messages、tool schema、JSON constraint、token counting、stop、logprobs 和 streaming error 的语义可能不同。Adapter 层要明确不支持或转换后的差异，不能静默丢字段。

2. Capability Manifest 比模型名可靠

每个 endpoint 登记：

• modalities、context/output limits；
• tool calling 和 structured-output subset；
• tokenizer/template、sampling 与 determinism contract；
• data residency、retention、training-use terms；
• safety/policy constraints；
• latency/capacity/cost envelope；
• supported adapters、fine-tunes 和 versions；
• known limitations 与 deprecation date。

路由先做硬约束过滤，再优化质量、延迟和成本。若任务要求图片输入和严格 schema，不具备这两项能力的低价模型不能成为 fallback。

3. 四类路由方式

静态路由

任务或租户固定模型。最易复现，适合高风险和稳定流程；利用率和成本优化空间有限。

规则路由

按 modality、长度、语言、数据级别、工具、deadline 和预算选择。规则可审计，但冲突和边界会增长。

Learned Router

分类器或模型预测任务类型、难度或候选成功概率。要独立评估 misrouting cost、calibration、slice 和 drift；路由器自称“我有 90% 信心”不是可校准置信度。

Cascade

先运行便宜模型，用 verifier 或业务检查判断是否接受，否则升级强模型。只有 acceptance criterion 与最终任务质量相关，cascade 才能可靠省成本。

cheap model → deterministic/schema/fact verifier → accept
                                      └ failure → stronger model

如果 verifier 只是让便宜模型评价自己，错误可能被一起放行。

4. 一个政策优先的路由骨架

from dataclasses import dataclass

@dataclass(frozen=True)
class RouteRequest:
    task_type: str
    required_capabilities: frozenset[str]
    sensitivity: str
    region: str
    deadline_ms: int
    cost_limit: float

def choose_endpoint(request: RouteRequest, registry, policy):
    candidates = [
        endpoint for endpoint in registry.healthy_endpoints()
        if request.required_capabilities <= endpoint.capabilities
        and policy.data_allowed(request, endpoint)
        and endpoint.estimated_cost(request) <= request.cost_limit
        and endpoint.estimated_latency(request) <= request.deadline_ms
    ]
    if not candidates:
        raise NoCompliantRoute(request.task_type)
    return min(candidates, key=lambda e: policy.utility_score(request, e))

estimated_latency/cost 是基于当前负载与历史分布的估计，可能失准。最终仍要 admission control；找不到合规路线时应明确失败或降级，不得绕过政策。

5. Fallback 不是换个模型重试

触发原因要区分：timeout、rate limit、5xx、overload、policy denial、invalid request、content refusal、quality failure。它们的处理不同：

• policy denial 不能通过另一供应商绕过；
• 参数/schema 错误应修请求，不应盲目切模型；
• 未知执行结果的 tool call 先查状态；
• 质量 verifier 失败可升级，但要限制级数和总预算；
• streaming 已发送部分 token 后切模型可能造成语义断裂，通常要终止并显式重试；
• fallback model 必须满足能力、数据和安全合同。

防止 retry multiplication：客户端、网关、provider SDK 和 orchestrator 若各重试三次，会形成调用风暴。由一层拥有总 retry budget，并传播 attempt/deadline。

6. 版本合同覆盖完整行为

Resolved deployment identity 不是一个模型别名，而是：

provider + model revision
tokenizer / chat template
system prompt / few-shot bundle
tool schemas / response schema
retriever / index / embedding / reranker
safety policy / guard versions
sampling defaults
adapter / quantization / serving config

供应商只提供浮动模型名时，用固定 probe/regression 监测行为漂移，并为关键场景准备迁移和退出。Prompt、tool schema 或 safety policy 变更也应走同一 release process。

7. 数据治理进入路由决策

不同 endpoint 可能具有不同 data residency、retention、human review、training-use 与 subcontractor 条款。路由前按数据分类和用途匹配政策；日志和 fallback 也必须遵守。

不要把敏感 prompt 发给所有候选做“并行选优”。Shadow testing 生产流量时需要去敏、授权和明确数据处理边界。

Tenant/model quotas、防滥用 limits 和预算在网关统一执行，但下游服务仍要自行授权。网关身份不是所有业务资源的万能通行证。

8. 路由评测要计入选择错误

离线 replay 对每个候选模型运行同一组样本，建立 quality/latency/cost matrix，再模拟 route policy。报告：

• end-to-end task success；
• route distribution 与 per-route success；
• misroute/error taxonomy；
• escalation/fallback rate；
• SLO/quality guardrail violations；
• cost per successful task；
• language、length、risk、tenant 等 slices；
• no-compliant-route rate。

不能只评价 router 的 task-classification accuracy。把高风险请求误送到不合规模型的代价远高于普通分类错误。

9. Shadow 与 Canary

先 shadow 新路由：主路径照常服务，新策略只计算选择或在允许的数据上调用候选，不影响用户。比较 paired results 后做小比例 canary。

Canary guardrails 包含质量、安全、隐私、错误、TTFT/TPOT、成本和 fallback；按 request/tenant 一致分桶，避免同一会话在模型间抖动。回滚要恢复 route rules、model aliases、prompt bundle 和 cache namespace。

常见误区

• 统一 API 就统一了模型语义：工具、停止、JSON 和安全行为仍可能不同。
• 小模型处理短问题：长度不等于难度或风险。
• 供应商失败就换另一家：数据政策和能力可能不兼容。
• 模型自报置信度可直接路由：需要外部校准和任务验证。
• 只要平均成本下降就成功：失败重试和质量回归会提高单位成功成本。

练习

1. 为文本、图像、工具和敏感数据写 capability manifest。
2. 设计一个便宜模型到强模型的 cascade verifier。
3. 列出五种不能自动 fallback 的失败。
4. 为第三方浮动模型别名设计 drift probes。
5. 计算两个路由策略的 cost per successful task，而不是 cost/request。

小结

模型网关把身份、协议、政策、预算和观测集中起来；路由器在硬约束内优化质量、延迟和成本。可靠 fallback 需要兼容能力与数据合同，完整版本身份和路由评测让每次选择可以复盘。

下一课处理另一种“看似省钱”的优化：缓存。复用答案之前，必须先证明输入语义、权限和知识版本仍然相同。