在生产环境里接入大模型 API真正让人头疼的往往不是偶尔失败一次而是失败之后系统没有“刹车”请求一直卡着不返回重试一轮又一轮地打出去token 成本不断上涨最后用户体验、上游限额和自己服务的稳定性全都被拖下水。普通 API 的稳定性通常重点看两件事请求能不能成功延迟是不是还能接受。但大模型 API 不太一样它天然多了不少约束。比如响应时间通常更长token 是按量计费的模型输出还带有一定不确定性如果是流式响应中途断开也很常见再加上不同模型之间能力并不完全等价不能简单地互相替换。所以API 超时和重试不能只写成“失败后重试 3 次”这么简单。服务降级也不是一句“返回默认值”就能解决的。更稳的做法是把超时、重试、熔断、限流和降级统一放进一个“请求预算”里考虑。也就是说每一次大模型 API 调用都应该有明确的 deadline、错误分类、重试边界以及失败之后该走哪条 fallback 路径。一、为什么大模型 API 不能直接套用普通 API 的方案大模型 API 和普通 HTTP 接口最大的区别在于一次调用消耗的不只是时间还包括 token 成本和用户耐心。比如一次聊天生成可能要 8 秒才返回完整内容如果走流式输出也许 2 秒能看到第一个 token但完整生成要 30 秒。再比如一次 RAG 问答通常要先检索再拼接上下文最后才调用模型。Agent 任务就更复杂了可能连续调用多个工具和多个模型。如果每一步都简单粗暴地“超时就重试”总耗时和总成本很快就会失控。因此大模型 API 的稳定性设计至少要同时看这几件事延迟用户最多能等多久首 token 多久之内必须出现成本重试会重复消耗 token尤其是长上下文请求失败一次的代价并不低。质量降级到小模型或备用供应商后答案质量可能会变。体验流式输出如果中途断了重新生成可能出现内容重复甚至前后语义接不上。所以这里的目标不是“无论如何都重试到成功”而是在有限的时间和成本预算内尽量给用户一个可以接受的结果。二、大模型 API 常见故障哪些值得重试哪些不该重试在设计 API 超时重试之前第一步是把错误类型分清楚。并不是所有失败都值得重试。有些错误继续重试只是在浪费时间和 token。失败类型常见表现是否重试推荐动作连接超时connect timeout、TLS handshake timeout是短退避重试必要时切换 endpoint首 token 超时请求已发出但长时间没有输出视情况看剩余 deadline可重试一次或切备用模型读超时流式输出中长时间没有新 token谨慎判断是否已有输出避免重复生成HTTP 429rate limit、quota exceeded视情况遵守Retry-After降速、排队或切备用模型HTTP 500/502/503/504上游错误、网关错误是指数退避 jitter超过阈值后触发熔断HTTP 400参数错误、上下文过长否修正请求、压缩上下文或返回明确错误HTTP 401/403鉴权失败、权限不足否告警并检查配置不应该自动重试context length exceeded输入超过模型上下文长度否截断、摘要压缩或切换长上下文模型content filter内容安全拦截否返回合规提示引导用户调整输入streaming 中断已输出部分内容后连接断开谨慎支持续写或提示恢复避免静默重放一个比较实用的判断方式是网络抖动、5xx、短暂超时通常可以重试参数错误、鉴权错误、上下文过长、安全拦截这类问题就不要重试。三、超时设计别只设置一个 timeout不少系统接入大模型 API 时只设置一个总 timeout比如 60 秒。这个做法看起来简单但其实有点粗。因为用户真正关心的不是“最终有没有返回”而是“多久能看到响应”“多久没动静就应该放弃”。更合理的方式是把超时拆成几层来看超时层级含义常见初始范围连接超时DNS/TCP/TLS 建连时间1–3 秒请求发送超时上传请求体的时间3–10 秒首 token 超时流式场景下多久必须开始输出5–15 秒读间隔超时连续多久没有新 token10–30 秒单次请求超时一次 API 调用最长等待时间30–120 秒业务总 deadline包含重试、排队、降级在内的总耗时在线 10–30 秒后台任务可更长队列等待超时在本地队列中最多等待多久按业务 SLA 设置这里最关键的一点是单次 timeout 不等于用户总等待时间。所有重试、fallback 和排队等待都必须受同一个业务 deadline 约束。比如在线聊天的总 deadline 是 25 秒。如果第一次调用已经耗掉了 18 秒即使还没有达到单次请求 timeout也不应该再发起一次完整重试。否则用户看到的结果就是页面转了很久最后还是失败。四、重试策略指数退避只是基础大模型 API 的超时重试最好同时满足三个条件当前错误确实属于可重试类型业务 deadline 还有剩余时间这次重试不会明显放大成本或流量压力。实际落地时建议使用“指数退避 full jitter”而不是固定间隔重试。固定 1 秒、2 秒、4 秒这样重试看似有节奏但在上游服务刚恢复之前很容易把大量请求一起打过去形成重试风暴。可以用下面这段伪代码来理解整体思路defshould_retry(error):iferror.statusin[500,502,503,504]:returnTrueiferror.typein[connect_timeout,temporary_network_error]:returnTrueiferror.status429:returnerror.retry_afterisnotNonereturnFalsedefcall_llm_with_retry(request,deadline):attempt0max_attemptsrequest.max_retries1whileattemptmax_attempts:ifremaining_time(deadline)0:raiseTimeoutError(business deadline exceeded)try:returncall_llm_once(request,timeoutmin(request.per_call_timeout,remaining_time(deadline)))exceptExceptionaserror:attempt1ifattemptmax_attemptsornotshould_retry(error):raisesleep_timebackoff_with_full_jitter(base0.5,factor2,cap5,attemptattempt)iferror.status429anderror.retry_after:sleep_timemin(error.retry_after,sleep_time)ifsleep_timeremaining_time(deadline):raiseTimeoutError(not enough budget for retry)sleep(sleep_time)这段代码里语法并不是重点真正重要的是这些边界在线交互一般只重试 0–2 次后台任务可以重试 3–5 次但必须配合限速和队列每次重试前都要检查剩余 deadline遇到 429 时优先尊重Retry-AfterPOST 请求最好设计幂等键避免用户重复提交后产生重复扣费或重复生成一定要监控“重试放大系数”。重试放大系数可以这样算重试放大系数 总 API 调用次数 / 原始业务请求数举个例子1000 个业务请求最终打出了 1500 次上游调用那么放大系数就是 1.5。如果这个指标持续走高就说明重试可能已经不再是“恢复机制”而变成了“故障放大器”。五、熔断与限流别让上游故障拖垮自己重试只能解决短暂失败不能替代熔断和限流。如果某个供应商、某个模型或者某个区域持续异常继续硬打请求只会让延迟更高、成本更大。大模型 API 的熔断建议按这些维度拆开统计provider不同供应商单独看model同一供应商下不同模型分别统计endpoint/region不同线路或区域分开观察error typetimeout、5xx、429 最好也分开统计。需要注意的是400、401、403 这类客户端错误不应该算进上游稳定性熔断里。否则很容易把自己的参数错误误判成供应商故障。一个相对保守的初始阈值可以参考下面这张表条件推荐动作1 分钟内请求数 ≥ 50且 5xx/timeout 比例 ≥ 30%打开熔断熔断打开 30–60 秒不再请求主模型走备用或降级半开状态放 3–5 个探测请求探测成功率达标关闭熔断探测继续失败保持打开并延长观察时间限流则最好放在两层一层在请求入口一层在真正调用上游之前。常见的限流维度包括用户、租户、模型、供应商、任务队列等。尤其是批处理任务千万不要放任无限并发。否则供应商一抖动系统里可能很快堆出大量重试任务。六、服务降级策略目标不是完美而是先给出可接受结果服务降级不是简单返回null也不是一句“系统繁忙”就结束。更合理的思路是按照业务价值逐层收缩能力。大模型 API 的降级可以设计成一棵树降级层级示例适用场景同模型重试主模型同 endpoint 短退避重试瞬时网络错误换线路/区域同供应商备用 endpoint区域性故障换供应商OpenAI-compatible 接口切到备用服务主供应商异常降模型高阶模型切到轻量模型在线问答、客服、摘要降上下文压缩历史对话或截断资料context length 超限降工具调用Agent 多步推理改为单轮回答工具链不稳定降输出长度完整报告改为要点摘要deadline 不足降实时性同步生成改为后台任务长文、批处理降数据源实时生成改为缓存或模板热点问题、FAQ最终兜底返回友好提示和追踪 ID全链路失败对于在线请求通常应该优先选择“更快返回一个能用的答案”对于后台任务则可以更看重结果质量允许它晚一点完成。显然这两类业务不应该共用同一套重试和降级参数。如果系统使用的是第三方 Claude API 兼容接入服务比如 ClaudeAPI 这类平台也要明确它本质上是第三方服务。接入前应重点评估兼容能力、多线路选择、中文支持、企业充值、开票以及基础技术协助等方面。具体可用性、额度和价格都应以平台最新说明为准业务系统里不要默认它“绝对稳定”或“绝对不限速”。七、流式响应首 token、断流和续写都要单独处理流式响应是大模型 API 稳定性里很容易被低估的一块。非流式请求失败后很多时候可以直接重试。但 streaming 不一样一旦部分内容已经展示给用户中途断流就会变得麻烦。这个时候如果系统自动从头重试可能带来几个问题用户看到重复开头新答案和旧答案语义不一致后端重复消耗 token但前端体验并没有变好。更稳妥的处理方式是区分首 token 超时和生成过程中的中断如果首 token 出现前失败可以按普通请求重试如果已经输出了内容再失败时不要静默自动重放支持“继续生成”把已生成内容作为上下文接着写长答案尽量分段生成降低单次失败带来的损失前端明确提示“生成中断可继续”或“正在恢复连接”日志里记录 stream start、first token、last token 和断开原因。在流式场景下首 token 延迟往往比完整响应耗时更影响用户感受。一个 30 秒完成、但 2 秒就开始输出的回答通常比 12 秒没有任何反馈、最后一次性返回的回答更容易被接受。八、生产环境推荐配置模板下面这组配置可以作为初始参考但不是绝对标准。真正上线后还需要结合 p95/p99 延迟、错误率、token 成本和用户反馈继续调。场景连接超时首 token 超时总 deadline重试次数降级策略在线聊天2s8–15s20–30s1–2 次切轻量模型、提示稍后重试RAG 搜索问答2s5–10s10–20s1 次返回检索摘要、缓存答案后台总结3s15–30s2–5min3–5 次入队延迟重试Agent 工具调用2s10–20s按步骤分配每步 0–1 次跳过非关键工具批量数据处理3s30s任务级 deadline多次但限速失败入死信队列Agent 场景尤其要小心。比如一个任务有 8 个步骤如果每一步都允许重试 2 次最坏情况下就会变成 24 次模型或工具调用。更好的做法是先给整个任务设置总预算然后再给每个步骤分配子预算。九、监控与验收没有指标就只能靠猜超时、重试和服务降级策略上线之后一定要用指标验证它们是不是真的有效。否则系统到底是在变稳还是只是在掩盖问题很难判断。指标说明用途业务请求成功率用户请求最终成功比例衡量用户侧可用性上游成功率单次大模型 API 调用成功比例衡量供应商稳定性p95 / p99 延迟长尾响应时间判断 timeout 是否合理首 token 延迟流式体验的核心指标判断模型是否卡顿超时率timeout 占比发现网络或性能问题重试成功率重试后成功比例判断重试是否值得重试放大系数调用次数 / 请求数控制成本和雪崩风险fallback 触发率降级次数占比衡量体验折损熔断打开次数熔断频率判断上游或阈值是否异常token 成本 / 请求单请求平均成本防止重试成本失控如果重试成功率很低但重试放大系数很高那就说明当前策略可能应该减少重试、提前熔断或者更快进入降级路径。如果 fallback 触发率持续升高也不要只看降级逻辑本身还要回头检查主模型稳定性、额度限制、请求参数以及业务峰值是否异常。十、完整调用流程示例一个相对可靠的大模型 API 调用链路可以按下面这个顺序来设计请求进入 - 校验用户、租户、配额 - 检查本地限流和并发池 - 设置业务总 deadline - 检查 provider/model 熔断状态 - 调用主模型 - 按错误类型判断是否重试 - 每次重试前检查剩余 deadline - 达到阈值后触发熔断 - 切换备用 endpoint / provider / model - 执行服务降级策略 - 记录 provider、model、latency、tokens、retry_count、fallback_used - 返回结果或友好失败提示用户侧的错误提示也要克制。不要把上游错误栈、供应商内部错误或者鉴权信息直接暴露给用户。在线场景可以提示“当前响应较慢请稍后重试”后台任务可以返回任务 ID让用户稍后查看结果长内容生成失败时最好提供“继续生成”的入口而不是让用户从头再提交一次。结语稳定性不是多重试几次而是让失败有边界大模型 API 稳定性设计的核心并不是把失败藏起来而是让失败有边界、可观测、可恢复。上线前可以用下面这份清单简单自查是否区分了可重试错误和不可重试错误是否设置了业务总 deadline是否使用了指数退避和 jitter是否遵守 429 返回的Retry-After是否按 provider、model、region 做了熔断是否准备了备用模型或备用供应商是否设计了分层服务降级策略是否处理了流式断流和续写是否记录了重试次数、fallback 和 token 成本是否做过超时、限流、上游 5xx 等故障演练。当超时、重试和降级被放进同一个请求预算里大模型 API 才不至于在故障时变成一个不可控的黑盒。说到底稳定性实战的目标不是“永不失败”而是在复杂的上游环境里尽量稳定地交付一个用户可以接受、系统也承担得起的结果。