1. 背景与并发痛点在大模型网关LLM Gateway的实际工程落地中依赖单一模型或单一供应商 API Key 往往会面临以下核心问题瞬时高频并发与 429 限流Rate Limit以 Google AI Studio Gemini 免费层为例其配额限制为15 RPM在高峰期或特定模型突发阶段可能降至5 RPM。当上层使用 Coding Agent如 Codex、OpenCode 或 Claude Code执行“阅读项目全部代码并重构”等重度任务时Agent 会在 10~20 秒内连续触发 10~15 轮函数调用Tool Calling Round-trips。单一 Key 的令牌桶Token Bucket会在 2~3 秒内被迅速抽干上游直接返回429 Too Many Requests并强制要求等待 30 秒以上。流式传输中途截断Mid-Stream Failure编码助手通常采用 SSE 流式传输stream: true。如果网关缺乏快速熔断机制在数据流吐出几个字符后上游抛出 429就会导致连接在半路异常关闭stream closed before response.completed触发客户端长达数分钟的挂起与重连。多账号与混合付费梯队难以统筹团队通常拥有多个不同来源的 Key例如个人免费老号、高信任分的 Google AI Pro 订阅号、即将过期的测试项目号。如何在保证 99.9% 流量享受免费的前提下实现平摊负载、自动升舱与终极兜底需要精细化的路由策略。本文基于在生产 K3s 集群中运行 LiteLLM 的真实踩坑经验系统剖析 LiteLLM 的重试、熔断与降级机制并给出三级阶梯容灾的工程实现。2. 核心路由参数与数学机理解析在 LiteLLM 的router_settings中有 3 个至关重要的参数决定了网关面对故障时的行为router_settings:routing_strategy:least-busynum_retries:5allowed_fails:1cooldown_time:60fallbacks:-gemini-3.7-flash:[gemini-3.7-pro-plan,gemini-3.7-backup]2.1num_retries: 重试次数与总尝试预算Why 5 instead of 3?在计算机网络和 LiteLLM 源码中num_retries表示在第 1 次初始尝试失败后额外允许发起的重试次数。整个请求允许消耗的最大尝试总数Total Attempts为最大尝试总数1 (初始调用)num_retries\text{最大尝试总数} 1 \text{ (初始调用)} \text{num\_retries}最大尝试总数1(初始调用)num_retries为什么 4 个 Key 至少需要num_retries: 5假设我们拥有 4 个 Key分布在 3 个梯队Tier 1: Key 1 Key 2Tier 2: Key 4Tier 3: Key 3若配置num_retries: 3总尝试次数为 4 次尝试 1Key 1 失败429尝试 2重试 1Key 2 失败429尝试 3重试 2Key 4 (Pro Plan) 失败尝试 4重试 3Key 3 (保底号) 尝试。风险重试预算卡在边缘。一旦中间任何一个 Key 发生 1 次网络握手抖动重试预算在轮到 Key 3 之前就会被提前耗尽导致 Key 3 连出场机会都没有就被直接向客户端报错。若配置num_retries: 5总尝试次数为 6 次即使 Key 1、Key 2、Key 4 相继遇到限流重试预算依然保有 2 次以上的安全裕度100% 保证 Key 3 终极保底号能够稳稳接力执行。2.2allowed_fails: 快速熔断阈值Why 1 instead of 3?allowed_fails定义了一个具体的 Deployment/Key连续失败多少次后被标记为不可用Unhealthy并进入冷却隔离。默认值通常为 3如果设为 3当 Key 1 遭遇 429 时LiteLLM 还会尝试在 Key 1 上重试 2 次。在已知 Key 1 已经透支的情况下这 2 次重试 100% 会继续报 429白白消耗重试预算并增加客户端延迟优化为allowed_fails: 1一旦 Key 1 返回 429 或 5xxLiteLLM在 0.01 秒内立即将 Key 1 打上冷却标记并移出可用池后续重试直接转交给健康的 Key 2 或备用梯队实现真正的秒级无感避震。2.3cooldown_time: 冷却隔离周期Why 60s instead of 30s?Google 免费层的限流是基于1 分钟60 秒滑动窗口计算的。若配置cooldown_time: 30容易引发二次暴毙第 0 秒Key 1 突发透支报 429第 30 秒禁闭解除Key 1 被放回可用池。但此时 Google 的 60 秒窗口才走了一半Key 1 的令牌桶中只恢复了 2~3 个令牌第 31 秒Agent 发起多文件调用Key 1 接下前 2 个请求后立即再次暴毙后果Key 1 在“冷却 ➔ 刚放出 ➔ 秒挂”之间剧烈抖动Rate Limit Flapping。优化为cooldown_time: 60满血复活将故障 Key 隔离整整 60 秒确保其完全跨越 Google 的 1 分钟滑动惩罚期重新归队时Key 1 的令牌桶100% 满血回满15 次完整额度能够从容承接下一轮大任务在 Key 1 隔离期间多 Key 池中的其余 Key 无缝承接流量客户端 0 感知。3. 三级主备阶梯式容灾架构设计为了最大化利用各账号的特性我们设计了“双核日常轮换 Pro Plan 应急升舱 历史项目终极保底”的三级阶梯架构[ 客户端请求: modelgemini-3.7-flash ] │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Tier 1: 主力日常轮换池 (gemini-3.7-flash) │ │ ├── Key 1 (本人老号 Gmail, RPM: 15) │ │ └── Key 2 (太太帐号 Gmail, RPM: 15) │ │ • 策略: least-busy 最闲优先平摊 50/50 负载 (合并 30 RPM) │ │ • 覆盖 99% 的日常编码与问答 │ └──────────────────────────────────┬───────────────────────────────┘ │ (若 Key 1 和 Key 2 均报 429) ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Tier 2: 一级应急升舱池 (gemini-3.7-pro-plan) │ │ └── Key 4 (Google AI Pro 订阅账号, 高信用分) │ │ • 平时 0 流量消耗 │ │ • 主力池被打满时触发利用高权重账号迅速解围 │ └──────────────────────────────────┬───────────────────────────────┘ │ (若 Pro Plan 偶发异常) ▼ ┌──────────────────────────────────────────────────────────────────┐ │ ️ Tier 3: 终极应急保底池 (gemini-3.7-backup) │ │ └── Key 3 (即将回收的项目账号) │ │ • 额度永久满格作为最后一道防线 │ │ • 即使该项目未来被彻底回收也不影响前两级主力运行 │ └──────────────────────────────────────────────────────────────────┘3.1 完整配置文件实现 (config.yaml)# # LiteLLM Proxy Model Multi-Tier Routing Configuration# # Key 角色与梯队定义说明# - OPENAI_API_KEY_FREE_1 : 本人老号 1 - Tier 1 日常轮换# - OPENAI_API_KEY_FREE_2 : 太太帐号 2 - Tier 1 日常轮换# - OPENAI_API_KEY_PRO_PLAN: 主力 Google AI Pro 旗舰号 - Tier 2 一级应急升舱# - OPENAI_API_KEY_FREE_3 : 终极应急保底号 - Tier 3 终极避震保底# model_list:# 梯队一主力日常轮换组 (Key 1 Key 2 平摊 50/50 负载) -model_name:gemini-3.7-flashlitellm_params:model:gemini/gemini-3.6-flashapi_key:os.environ/OPENAI_API_KEY_FREE_1rpm:15-model_name:gemini-3.7-flashlitellm_params:model:gemini/gemini-3.6-flashapi_key:os.environ/OPENAI_API_KEY_FREE_2rpm:15# 梯队二一级应急升舱组 (Pro Plan 专属主力 429 时触发) -model_name:gemini-3.7-pro-planlitellm_params:model:gemini/gemini-3.6-flashapi_key:os.environ/OPENAI_API_KEY_PRO_PLANrpm:15# ️ 梯队三终极应急保底组 (Key 3 专属平时 0 流量) -model_name:gemini-3.7-backuplitellm_params:model:gemini/gemini-3.6-flashapi_key:os.environ/OPENAI_API_KEY_FREE_3rpm:15router_settings:routing_strategy:least-busy# 负载均衡优先选择当前空闲/并发压力最小的 Key 派发请求# 充沛重试预算最多跨 Key / 跨梯队重试 5 次总共 6 次尝试机会确保覆盖所有梯队num_retries:5# 极速熔断触发器单个 Key 失败 1 次立即关禁闭绝不在报错 Key 上浪费重试次数allowed_fails:1# 满血禁闭冷却期故障 Key 隔离 60 秒完整错开 1 分钟滑动窗口惩罚期cooldown_time:60fallbacks:# 梯队级联降级链主力组 (FREE_1 FREE_2) - Pro Plan 升舱 - Key 3 终极保底-gemini-3.7-flash:[gemini-3.7-pro-plan,gemini-3.7-backup]litellm_settings:cache:truecache_params:type:redishost:redis.redis.svc.cluster.localport:6379password:os.environ/REDIS_PASSWORDsupported_call_types:[chat_completion]ttl:36004. 流式传输Streaming中途异常与客户端重连机制在使用 Codex、OpenCode 等 CLI 工具时客户端通常使用流式传输stream: true。理解网关重试与客户端重试的边界至关重要4.1 非流式 vs 流式的重试差异非流式请求Non-Streaming客户端发送请求 ➔ 网关在后台请求上游若 Key 1 报 429由于尚未向客户端发送任何数据包LiteLLM 在内部自动切换到 Key 2 重试最终返回正常的200 OKJSON 包客户端完全无感知。流式打字机请求Streaming / SSE连接在第 0.1 秒即已建立HTTP 200 SSE Stream部分头部或初始 Chunk 已发送给客户端若模型在生成第 10 个 Token 时突然被上游掐断抛出MidStreamFallbackErrorTCP 连接半路关闭客户端Codex发现流在没有收到response.completed结束标记前中断会由客户端自身触发断线重连• Reconnecting... 2/5 (stream closed before response.completed)4.2 Codex 客户端挂起保护当出现Reconnecting... waiting for network (esc to interrupt)时这是 Codex 为了防止用户的长输入丢失而开启的挂起保护状态在终端中按下Esc键或Ctrl C即可主动终止挂起并重新发送请求。5. 真实压测与分流验证数据在 Codex 客户端连续发起 3 次重度 Agent 任务包含读取全仓库 30 文件后分析网关实际承载的数据总请求统计3 次用户交互在底层共触发了9 次独立的 LLM Tool Calling Round-trips。分流结果Key 1 (本人自用)承接5 次调用55.5%Key 2 (太太自用)承接4 次调用44.5%Key 4 (Pro Plan)0 次主力池负载良好未触发 Tier 2Key 3 (终极保底)0 次满血待命中。性能表现9 次调用全部在 0.8~1.2 秒内响应成功率为100%双 Key 轮询将瞬时流速压制在安全线以下全程 0 次 429 告警。6. 总结在大模型网关的建设中高可用不能只寄希望于单点的稳定而必须通过工程化的流量分摊、极速熔断与多级容灾来实现num_retries: 5提供充足的重试预算确保多级 Fallback 链条能被 100% 完整遍历allowed_fails: 1单次失败即刻隔离杜绝在已知故障节点上盲目重试cooldown_time: 60匹配供应商的分钟级配额窗口确保节点冷却后满血归队主备分层调度日常使用主力免费池高并发或故障时自动升舱与兜底兼顾了成本控制与系统可用性。