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 outputCanonical 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 只是让便宜模型评价自己，错误可能被一起放行。
按一个简化账本，便宜尝试花 1 单位、验证花 0.2、升级再花 8，升级率为 25% 时，期望成本为
4. 一个政策优先的路由骨架
片段需要实时 registry，以及绑定已认证调用者的 policy。Cost 使用统一单位，latency 使用毫秒，utility 越大越好；估算器调用失败时，外围网关还需把该候选按不可用处理。
from dataclasses import dataclass
from math import isfinite
class NoCompliantRoute(RuntimeError):
pass
@dataclass(frozen=True)
class RouteRequest:
task_type: str
required_capabilities: frozenset[str]
sensitivity: str
region: str
deadline_ms: int # Remaining budget at this routing decision.
cost_limit: float
def choose_endpoint(request: RouteRequest, registry, policy):
if not isfinite(request.deadline_ms) or request.deadline_ms <= 0:
raise ValueError("positive remaining deadline required")
if not isfinite(request.cost_limit) or request.cost_limit < 0:
raise ValueError("finite nonnegative remaining cost limit required")
candidates = []
for endpoint in registry.healthy_endpoints():
if not request.required_capabilities <= endpoint.capabilities:
continue
if not policy.data_allowed(request, endpoint):
continue
cost = endpoint.estimated_cost(request)
latency = endpoint.estimated_latency(request)
if not (isfinite(cost) and isfinite(latency) and cost >= 0 and latency >= 0):
continue
if cost > request.cost_limit or latency > request.deadline_ms:
continue
utility = policy.utility_score(request, endpoint) # Higher is better.
if isfinite(utility):
candidates.append((utility, endpoint))
if not candidates:
raise NoCompliantRoute(request.task_type)
return max(candidates, key=lambda pair: pair[0])[1]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；需要会话连续性时按 session 或 tenant 稳定分桶；散列互不相关的 request ID 不能固定同一会话版本。回滚要恢复 route rules、model aliases、prompt bundle 和 cache namespace。
常见误区
- 统一 API 就统一了模型语义：工具、停止、JSON 和安全行为仍可能不同。
- 小模型处理短问题：长度不等于难度或风险。
- 供应商失败就换另一家：数据政策和能力可能不兼容。
- 模型自报置信度可直接路由：需要外部校准和任务验证。
- 只要平均成本下降就成功：失败重试和质量回归会提高单位成功成本。
练习
- 为文本、图像、工具和敏感数据写 capability manifest。
- 设计一个便宜模型到强模型的 cascade verifier。
- 列出五种不能自动 fallback 的失败。
- 为第三方浮动模型别名设计 drift probes。
- 计算两个路由策略的 cost per successful task，而不是 cost/request。
小结
模型网关把身份、协议、政策、预算和观测集中起来；路由器在硬约束内优化质量、延迟和成本。可靠 fallback 需要兼容能力与数据合同，完整版本身份和路由评测让每次选择可以复盘。
下一课处理另一种“看似省钱”的优化：缓存。复用答案之前，必须先证明输入语义、权限和知识版本仍然相同。