熔断与恢复
熔断粒度是 模型×密钥 组合。这一页说明失败分类、阶梯冷却、模型可达性的派生口径与全部不可用时的兜底。
5. 失败处理与熔断
5.1 失败分类
| 上游表现 | 归因层级 | 处理 | 计入熔断 |
|---|---|---|---|
| 401 / 403 | key(密钥失效) | 立即禁用该 key,disable_reason 记录,UI 告警 | 否(key 已禁用,无需阶梯) |
| 429 | key(限流) | 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 配置项