40行Python搞定LLM重试、超时与模型回退

调用大模型API时，最先拖垮原型的往往不是提示词，而是429限流、请求挂起或某个模型临时不可用。一位APIGOTO团队成员分享了一个约40行的Python封装，同时解决这三个问题——时间硬超时、指数退避重试、模型回退。虽然作者声明自己就职于该网关项目，但代码本身与具体厂商无关，任何OpenAI兼容端点都能用。

核心思路：三层防护

作者把问题拆成三步。第一，给每个请求设置硬超时，避免worker被慢响应卡死；第二，遇到限流和服务端错误时用指数退避重试；第三，如果某个模型反复失败，就换用列表里的下一个模型。三者的优先级是：能在同一模型内重试解决的不换模型，只有重试耗尽才进入回退环节。

这个顺序很关键。重试成本低、不改变输出风格；模型回退虽然能保证可用性，但不同模型的输出可能不一致，属于不得已的选择。

指数退避是一种应对临时性故障的重试策略：每次重试的等待时间随失败次数指数级增长，通常还加入随机抖动（jitter）以避免多个客户端同时重试造成“惊群效应”。其核心假设是，限流和服务端错误往往是瞬时的，立即重试只会加重拥塞。代码中的 min(2 ** i, 8) 即第 i 次重试等待 2 的 i 次方秒，并封顶 8 秒，既给了服务端恢复窗口，又防止单个请求阻塞过久。

模型回退（model fallback）指当主模型在重试耗尽后仍不可用时，自动切换到备选模型列表中的下一个。它提升的是系统可用性，代价是不同模型在输出风格、格式遵循、知识时效上可能存在差异，因此适合对一致性要求不高的场景，或作为最后一道防线。

代码实现：40行内的取舍

封装里创建OpenAI客户端时就设定了两个关键参数：timeout=30保证请求不会无限等待，max_retries=0则关闭SDK自带的自动重试，把控制权交给自己的chat函数。作者定义了一个可重试状态码集合{429, 500, 502, 503, 504}，覆盖限流和网关层错误。

chat(messages, models, attempts=3)双层循环：外层遍历模型列表，内层对每个模型最多尝试3次。捕获APIStatusError时先判断状态码——若不在可重试集合内（比如400、401、404）就break，因为重试无意义，直接进入下一个模型；可重试错误和APITimeoutError、APIConnectionError则记录异常后继续退避。退避时长用min(2 ** i, 8)，即1秒、2秒、4秒封顶8秒，避免长时间阻塞。全部模型失败后抛出RuntimeError并带上最后一次异常信息。

函数成功时返回(model, text)二元组而不是只返回文本，这样调用方可以知道实际是哪个模型应答的。作者在Notes里专门强调要记录这一点：回退频繁触发时，你需要立刻知道主模型是不是出了问题。

OpenAI Python SDK 的 max_retries 参数控制 SDK 内部对连接错误、超时和 5xx/429 响应的自动重试次数，默认通常为 2。将其设为 0 意味着关闭这层内建重试，所有重试逻辑完全由业务代码掌控。这样做的好处是避免“双重退避”——SDK 重试与自定义重试叠加导致等待时间不可预测，也便于统一记录重试次数和最终失败原因。代价是需要自行处理原本由 SDK 兜底的瞬时故障。

几个容易踩的坑

作者给出了几条来自实践的建议。模型ID要用供应商实际列出的值（通过client.models.list()确认），不要凭猜测填写；401或404意味着密钥或模型名有误，重试不会解决问题；因为只依赖base_url和API key两个变量，同一段代码可以指向OpenAI官方、自托管服务或网关。

这类封装的真正价值在于把“可用性”从前端业务逻辑中抽离。原型阶段靠它就能应对大部分生产环境的第一波故障，等流量上来再叠加熔断、指标和告警也不迟。授权声明也提醒读者：示例默认的base_url指向作者所在团队的网关，但改成任意兼容端点即可独立运行，不影响代码的有效性。

适用边界

需要注意的是，模型回退解决的是“可用性”而非“一致性”。如果下游对输出格式或风格有严格要求，换模型可能带来额外校验成本。另外，重试期间的消息可能重复发送，涉及计费的场景下要留意；作者没有展开讨论幂等或请求去重，这部分需要使用者根据自身场景补充。