企业官网建设流程全解析

在生产环境里接入大模型 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。

一个比较实用的判断方式是：网络抖动、5xx、短暂超时通常可以重试；参数错误、鉴权错误、上下文过长、安全拦截这类问题就不要重试。

三、超时设计：别只设置一个 timeout

不少系统接入大模型 API 时，只设置一个总 timeout，比如 60 秒。这个做法看起来简单，但其实有点粗。因为用户真正关心的不是“最终有没有返回”，而是“多久能看到响应”“多久没动静就应该放弃”。

更合理的方式，是把超时拆成几层来看：

这里最关键的一点是：单次 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.status==429:returnerror.retry_afterisnotNonereturnFalsedefcall_llm_with_retry(request,deadline):attempt=0max_attempts=request.max_retries+1whileattempt<max_attempts:ifremaining_time(deadline)<=0:raiseTimeoutError("business deadline exceeded")try:returncall_llm_once(request,timeout=min(request.per_call_timeout,remaining_time(deadline)))exceptExceptionaserror:attempt+=1ifattempt>=max_attemptsornotshould_retry(error):raisesleep_time=backoff_with_full_jitter(base=0.5,factor=2,cap=5,attempt=attempt)iferror.status==429anderror.retry_after:sleep_time=min(error.retry_after,sleep_time)ifsleep_time>=remaining_time(deadline):raiseTimeoutError("not enough budget for retry")sleep(sleep_time)

这段代码里，语法并不是重点，真正重要的是这些边界：

• 在线交互一般只重试 0–2 次；
• 后台任务可以重试 3–5 次，但必须配合限速和队列；
• 每次重试前，都要检查剩余 deadline；
• 遇到 429 时，优先尊重Retry-After；
• POST 请求最好设计幂等键，避免用户重复提交后产生重复扣费或重复生成；
• 一定要监控“重试放大系数”。

重试放大系数可以这样算：

重试放大系数 = 总 API 调用次数 / 原始业务请求数

举个例子，1000 个业务请求最终打出了 1500 次上游调用，那么放大系数就是 1.5。如果这个指标持续走高，就说明重试可能已经不再是“恢复机制”，而变成了“故障放大器”。

五、熔断与限流：别让上游故障拖垮自己

重试只能解决短暂失败，不能替代熔断和限流。如果某个供应商、某个模型或者某个区域持续异常，继续硬打请求，只会让延迟更高、成本更大。

大模型 API 的熔断，建议按这些维度拆开统计：

• provider：不同供应商单独看；
• model：同一供应商下，不同模型分别统计；
• endpoint/region：不同线路或区域分开观察；
• error type：timeout、5xx、429 最好也分开统计。

需要注意的是，400、401、403 这类客户端错误，不应该算进上游稳定性熔断里。否则很容易把自己的参数错误，误判成供应商故障。

一个相对保守的初始阈值可以参考下面这张表：

限流则最好放在两层：一层在请求入口，一层在真正调用上游之前。常见的限流维度包括用户、租户、模型、供应商、任务队列等。尤其是批处理任务，千万不要放任无限并发。否则供应商一抖动，系统里可能很快堆出大量重试任务。

六、服务降级策略：目标不是完美，而是先给出可接受结果

服务降级不是简单返回null，也不是一句“系统繁忙”就结束。更合理的思路，是按照业务价值逐层收缩能力。

大模型 API 的降级可以设计成一棵树：

对于在线请求，通常应该优先选择“更快返回一个能用的答案”；对于后台任务，则可以更看重结果质量，允许它晚一点完成。显然，这两类业务不应该共用同一套重试和降级参数。

如果系统使用的是第三方 Claude API 兼容接入服务，比如 ClaudeAPI 这类平台，也要明确它本质上是第三方服务。接入前应重点评估兼容能力、多线路选择、中文支持、企业充值、开票以及基础技术协助等方面。具体可用性、额度和价格，都应以平台最新说明为准，业务系统里不要默认它“绝对稳定”或“绝对不限速”。

七、流式响应：首 token、断流和续写都要单独处理

流式响应是大模型 API 稳定性里很容易被低估的一块。

非流式请求失败后，很多时候可以直接重试。但 streaming 不一样，一旦部分内容已经展示给用户，中途断流就会变得麻烦。这个时候如果系统自动从头重试，可能带来几个问题：

• 用户看到重复开头；
• 新答案和旧答案语义不一致；
• 后端重复消耗 token，但前端体验并没有变好。

更稳妥的处理方式是：

• 区分首 token 超时和生成过程中的中断；
• 如果首 token 出现前失败，可以按普通请求重试；
• 如果已经输出了内容，再失败时不要静默自动重放；
• 支持“继续生成”，把已生成内容作为上下文接着写；
• 长答案尽量分段生成，降低单次失败带来的损失；
• 前端明确提示“生成中断，可继续”或“正在恢复连接”；
• 日志里记录 stream start、first token、last token 和断开原因。

在流式场景下，首 token 延迟往往比完整响应耗时更影响用户感受。一个 30 秒完成、但 2 秒就开始输出的回答，通常比 12 秒没有任何反馈、最后一次性返回的回答更容易被接受。

八、生产环境推荐配置模板

下面这组配置可以作为初始参考，但不是绝对标准。真正上线后，还需要结合 p95/p99 延迟、错误率、token 成本和用户反馈继续调。

Agent 场景尤其要小心。比如一个任务有 8 个步骤，如果每一步都允许重试 2 次，最坏情况下就会变成 24 次模型或工具调用。更好的做法是先给整个任务设置总预算，然后再给每个步骤分配子预算。

九、监控与验收：没有指标，就只能靠猜

超时、重试和服务降级策略上线之后，一定要用指标验证它们是不是真的有效。否则系统到底是在变稳，还是只是在掩盖问题，很难判断。

如果重试成功率很低，但重试放大系数很高，那就说明当前策略可能应该减少重试、提前熔断，或者更快进入降级路径。

如果 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 才不至于在故障时变成一个不可控的黑盒。

说到底，稳定性实战的目标不是“永不失败”，而是在复杂的上游环境里，尽量稳定地交付一个用户可以接受、系统也承担得起的结果。