跳到主要内容

熔断与恢复

熔断粒度是 模型×密钥 组合。这一页说明失败分类、阶梯冷却、模型可达性的派生口径与全部不可用时的兜底。

5. 失败处理与熔断​

5.1 失败分类​

上游表现归因层级处理计入熔断
401 / 403key(密钥失效)立即禁用该 key,disable_reason 记录,UI 告警否(key 已禁用,无需阶梯)
429key(限流)key 短冷却:优先 Retry-After,缺省 60s否
超时 / 连接错误 / 5xx模型(上游故障)阶梯熔断(5.2)是
4xx 其他(400 等)调用方不重试不转移,直接透传给客户端,记 client_error否

5.2 模型×密钥组合的阶梯熔断状态机​

粒度口径:模型级与密钥级独立状态机已退役,禁用/熔断只发生在「模型+密钥」组合 (model_key_ban)这一粒度上:可重试失败走阶梯冷却、连续失败达阈值转永久禁用; 组合成功即清零。下文沿用「模型级」的说法描述该组合状态机的阶梯行为。 密钥侧的 401/403 立即禁用、429 短冷却同样落在组合行上(见 §5.1)。

默认配置:阶梯 30s, 1m, 3m;禁用阈值 3(均可改,见 §9)。

失败(超时/5xx/connection_failed) 失败 失败
┌──────┐ ──────────────────▶ ┌──────┐ ─────▶ ┌──────┐ ─────▶ ┌──────────┐
│active│ │cool30│ │cool60│ │ DISABLED │
└──────┘ ◀───────────────── └──────┘ └──────┘ └──────────┘
▲ 半开探测成功 │ 到期半开 │ │
└────────────────(计数清零)────┴───探测────────┘ 手动解禁(Web UI)
  • 第 N 次连续失败 → 冷却 ladder[min(N, len)-1];连续失败 ≥ 阈值(3) → disabled (默认参数下的实际序列:失败1→30s,失败2→1m,失败3→禁用;若把阈值调大,3m 档生效,末档自动重复)
  • 冷却到期 = 半开:恢复正常候选,下一次真实流量即探测;探测成功 → fail_count 清零回归 active;探测失败 → 阶梯继续升级
  • disabled 仅能手动恢复:Web UI / POST /api/models/{id}/enable;重启不丢(状态在 DB)
  • 状态转移即时落库(本地 SQLite 写放大可忽略)

5.3 模型可达性(组合禁用的派生口径)​

模型可达性 = 其绑定密钥中是否存在可用 key(组合行未禁用)。全部不可用 → 路由选择时跳过该模型。派生态不落库、不告警,组合行状态即事实来源;模型级 disabled 的派生判定与通知见 §8.4。

5.4 全部不可用(防阻断兜底)​

某路由所有目标模型均 disabled/cooldown 且无可用 key 时,返回:

HTTP 503
{
"error": {
"code": "all_backends_unavailable",
"message": "路由 'glm' 无可用后端:glm-4.6 已禁用(连续3次超时,最近错误: dial tcp ...);glm-4.5-flash 冷却中(剩余42s)",
"backends": [
{"model": "glm-4.6", "status": "disabled", "reason": "连续3次超时,最近错误: dial tcp ..."},
{"model": "glm-4.5-flash", "status": "cooldown", "retry_after_s": 42}
]
}
}

明确告诉调用方哪个后端因什么不可用,而非无限挂起或含糊报错。记一条 error_code=all_backends_unavailable 的请求日志。

路由级兜底模型(route.fallback_model_id,路由 CRUD 各自配置,无全局开关):

  • 触发条件:路由模型 hop 全部耗尽(入口即无候选,或已尝试模型达到 max_hops / 没有更多目标)。兜底不计入 hop
  • 兜底模型必须与路由端点协议/类型匹配(创建/更新时校验,口径同目标模型);mcp 路由不支持兜底
  • 兜底为单次尝试、不重试:PickFallback 按该模型密钥权重选一把未禁用组合(等权轮询),失败就地终结
  • 命中时记 request_log.is_fallback=1(统计口径:fallback_count / fallback_rate 不变)
  • 兜底下沉到路由级(routes.fallback_model_id),不存在全局 fallback 配置项