请求生命周期与重试
从入口到上游的一次完整请求,以及失败后如何在模型与密钥之间转移。
6. 请求生命周期与重试
收到请求
├─ 解析逻辑 modelId(body.model)→ 未配置 → 404 model_not_found
├─ 转移预算检查(max_hops 默认 3 个路由模型)
├─ 【尝试】选目标模型 → 耗尽该模型全部可用 key → 改写 body.model 为真实模型名 → 转发
│ ├─ 首字节前失败(超时/connection_failed/5xx/429/401/403)
│ │ ├─ 按 §5 归因更新状态
│ │ ├─ 429/401/403/5xx/超时 → 先换同模型下一把 key;该模型密钥全部失败后才消耗一个模型 hop
│ │ │ 转移顺序:同模型全部 key → 下一个目标模型
│ │ └─ 4xx 其他 → 透传错误给客户端,结束
│ ├─ 首字节到达(流式:首个 SSE data;非流式:响应完整)
│ │ ├─ 记录 ttft_ms —— ⚠️ 从此不可再换后端重试
│ │ └─ SSE 逐块透传给客户端,边转发边累计 token
│ │ 收尾按 completion/(total-ttft) 计算流式速度 tps
│ └─ 流中途上游断开:无法重试,记 error(stream_broken)。成功必须看到结束信号(OpenAI `[DONE]`/最终 usage、Anthropic `message_delta.stop_reason`、Responses `completed`);仅有 token(如 Anthropic `message_start.usage`)不够。客户端取消未完成的流记 `client_disconnected`,不计入熔断。
└─ 收尾:写 request_log(成功/失败均写),更新 key.last_used_at、成本计算
要点:
- 重试窗口 = 收到首字节之前。一旦开始向客户端吐流,错误只能就地终结(LLM 代理标准做法)
- 每次尝试独立计时:
provider.timeout_ms约束"建连 + 首字节";流式读取阶段设 300s 空闲超时兜底 - token 统计:流式请求自动注入
stream_options.include_usage=true获取上游精确 usage(可按提供商关闭);上游不给则按 字符数/4 估算并标记tokens_estimated=1 retries字段记录本次请求消耗的失败尝试次数(不含最终成功那一跳),用于报表观察后端质量;breaker.max_hops限制的是尝试过的不同路由模型数,不是 attempt 次数