路由
「路由」这一节讲的是：一个模型名进来之后，怎么决定用哪个渠道、失败了怎么办。
三层结构
| 层 | 实体 | 作用 |
|---|---|---|
| 模型名 | 路由 routes | model_pattern 匹配进来的模型名，可含通配符 |
| 候选集 | 路由成员 route_members | 这条路由下有哪些渠道可用，各自的优先级、权重与冷却状态 |
| 实体 | 渠道 channels | 真正被转发的对象 |
一条路由挂多个成员。成员分属不同分组，下游令牌用 route_group_name 选择用哪一组。
选型算法
同一优先级层内按权重分散流量；不同层之间严格梯次承接（高优先层还有可用成员时，不会用到低优先层）。在此之上可以叠加三种感知维度：
| 开关 | 环境变量 | 效果 |
|---|---|---|
| 时延感知 | ROUTING_LATENCY_AWARE | 按实测时延动态微调权重 |
| 错误感知 | ROUTING_ERROR_AWARE | 按实时错误率动态微调权重 |
| 并发感知 | ROUTING_CONCURRENCY_AWARE | 接近 ROUTING_CONCURRENCY_LIMIT 时降低该渠道被选中的概率 |
先稳定后扩展（stable first）
新加入的成员默认不会被立刻推上主链路。stable_first 系列参数控制这个灰度过程：
| 设置 | 含义 |
|---|---|
STABLE_FIRST_ENABLED | 是否启用该策略 |
STABLE_FIRST_DENOMINATOR | 初始流量分母（新成员先拿 1/N 的流量） |
STABLE_FIRST_PROMOTE_REQUESTS | 累计多少次成功请求后升为正式成员 |
路由上还有 stable_first_requests 记录当前累计数。
会话粘性
同一个会话内的多轮请求尽量落在同一个上游，避免多轮对话被拆到不同后端导致上下文不一致。
| 设置 | 含义 |
|---|---|
STICKY_ENABLED | 全局开关 |
STICKY_TTL_MINUTES | 粘性窗口 |
路由的 sticky_session | 按路由单独开启或关闭 |
失败处理
四套机制分工不同，别混起来看：
| 机制 | 触发条件 | 持续时间 | 作用范围 |
|---|---|---|---|
| 请求级重试 | 单次尝试失败 | 立即 | 该请求，按 retry_times 换渠道 |
| 冷却（cooldown） | 连续失败达到阈值 | COOLDOWN_SECONDS，渐进式递增 | 该路由成员 |
| 熔断（breaker） | 连续硬失败达到下限 | 熔断窗口 | 该渠道（可按上游密钥维度粘性） |
| 自动禁用 | 连续失败达到 CHANNEL_AUTO_DISABLE_THRESHOLD | 直到恢复探测通过 | 整个渠道 |
- 跨渠道重试由
CROSS_CHANNEL_FAILOVER_ENABLED控制；RETRY_TIMES（默认 2）是轮次上限。 生成类端点（图像 / 音频 / 视频 / 音乐 /responses）另受非幂等闸门限制：默认只发一次， 其中图像连Idempotency-Key都不认（见流式 / 重试与幂等）。 - 恢复探测（
RECOVERY_PROBE_ENABLED/RECOVERY_PROBE_INTERVAL_SECONDS）负责把冷却或禁用中的渠道静默试回来。 FAULT_PROTECTION_ENABLED是这组机制的总体开关。
IMPORTANT
网络抖动不会直接把正常渠道禁用。偶尔超时只进入平滑冷却并在后台静默探活；只有连续硬失败且探活全部失败，才会触发渠道保护。
模型名的归一
上游各家对同一个底座模型的命名不一样（claude-3-5-sonnet-latest ↔ claude-3-5-sonnet-20241022）。两种处理方式：
| 方式 | 做法 | 适合 |
|---|---|---|
| 一键挂载（auto-match） | 把「确实提供该模型的启用渠道」挂进指定分组 | 新模型接入 |
| 模型统一（unify） | 把多个原名路由合并成一个对外名，可撤销 | 已经积累了一堆别名 |
auto-match 有两种匹配范围：
exact—— 普通名字精确匹配（*由操作员自己写）；related—— 额外接受「以 pattern 开头的其他模型」，并为命中的变体成员写mapping_json={"real":"<命中名>"}。
related 只改成员的转发名，不改路由名。否则挂上去的成员会把基础名发给根本不认它的上游——挂了个只会报错的成员。
unify 是一个批次 + op 回放状态机：合并前对整行做快照，Undo 逆序回放并跳过已撤销的 op，重建时按原 id 原样插回。
模型能力注册表
网关要知道的不只是「模型叫什么」，还有「该用哪个端点、哪种编码调用它」——/v1/images/edits 与 /v1/chat/completions 的分工、参考图上限、是否异步。
四档来源，覆盖优先级为 人工校正 > 外部目录同步 > 内置推断：
| 来源 | 说明 |
|---|---|
builtin | 按模型名推断 |
discovery | 探测时自动标注 |
catalog | 外部目录（LiteLLM / models.dev）同步 |
manual | 人工校正，标记后冻结，后续自动写入不再覆盖 |
机器推断的行会在规则改进后被重算——否则改进一条规则永远到不了已经存在的行。
模型变更追溯
上游模型清单发生变化时自动记录审计，可预览影响范围并一键做平滑映射替换。相关保留期由 MODEL_CHANGE_RETENTION_DAYS（默认 90）与 MODEL_CHANGE_AUTO_IGNORE_DAYS 控制。