接入一个模型 API最容易写出的代码通常只有三步组装请求、等待响应、失败后再试一次。Demo 阶段这足够了进入生产环境以后同一段“再试一次”却可能同时制造请求风暴、重复扣费、半截流式输出和不可解释的模型切换。问题不在于有没有重试而在于系统是否知道自己正在重试什么。429表示当前请求受到速率或配额约束连接超时表示客户端没有在期限内得到结果502可能是上游临时故障而“连接在提交后断开”则意味着外部系统可能已经接受请求。它们都表现为一次异常但恢复动作并不相同。生产级调用层的第一条规则应该是先分类再决定重试、对账、回退还是显式失败。一、把失败分成六类可以先建立一个与具体 SDK 无关的错误表。类型常见现象默认动作RATE_LIMIT429、响应带重试提示遵守服务端等待时间并受全局重试预算限制TRANSIENT连接建立失败、临时 502/503有上限地退避重试INVALID_REQUEST参数错误、模型名不存在、Schema 不合法立即失败修复请求后再发AUTH_OR_POLICYKey 无效、权限不足、策略拒绝立即失败并告警禁止换通道绕过PARTIAL_STREAMSSE 已输出部分 token 后断开标记不完整由业务决定整体重跑或交给用户RESULT_UNKNOWN请求可能已提交但响应在确认前丢失先对账禁止盲目重放这里最容易被忽略的是最后两类。只要客户端已经把部分内容展示给用户换一个模型继续生成就可能造成语气、事实和结构突变。只要某个工具调用可能产生外部副作用网络报错也不等于调用失败。把这两种情况重新放回普通重试队列是重复发信、重复写库和结果拼接错乱的常见起点。二、429 不是“立刻换一个 Key”收到 429 后立即轮换 Key看起来能提高成功率实际上可能绕过账号级限流也会把原本可控的拥塞扩散到全部通道。更稳妥的顺序是读取服务端提供的等待时间没有明确提示时再使用指数退避。为同一租户、模型和来源设置并发上限避免一个热点用户拖垮全局。给一次业务运行设置总重试预算而不是让每层 SDK 各自重试三次。等待时间超过业务截止期限时直接返回可解释的繁忙状态。只有策略明确允许时才进入候选模型或候选来源。退避要加入随机抖动。假设一百个 worker 同时在整秒收到 429如果都在两秒后同时重发下一轮仍会形成尖峰。Full Jitter 的思路很简单先按尝试次数计算等待上限再在零到上限之间随机取值。import random import time def retry_delay(attempt: int, retry_after: float | None None) - float: if retry_after is not None: return max(0.0, retry_after) cap min(30.0, 0.8 * (2 ** (attempt - 1))) return random.uniform(0.0, cap) def sleep_before_retry(attempt: int, retry_after: float | None) - None: time.sleep(retry_delay(attempt, retry_after))这段代码只解决“等多久”没有解决“能不能再发”。真正的重试条件还要同时检查错误类型、截止时间、剩余预算和请求是否可安全重放。三、把重试预算放在最外层一个常见的隐性放大来自多层重试HTTP 客户端试三次模型 SDK 再试三次任务队列失败后又重跑三次理论上一次业务动作可能被放大到二十多次。即便每一层都“很保守”组合起来也会失控。调用链应该只保留一个拥有最终决策权的重试控制器。底层库可以报告规范化错误但不自行无限恢复。控制器至少持有以下状态run_id 本次业务运行 deadline 最晚完成时间 attempts_used 已使用尝试次数 retry_budget 总尝试上限 selected_route 当前模型与来源 request_hash 规范化请求哈希 stream_started 是否已经向用户输出内容 effect_state none / pending / confirmed / unknown当stream_startedtrue时自动换模型续写通常应被禁止当effect_stateunknown时恢复器应先查询效果账本或下游回执。一次请求是否可重放是业务属性不是 HTTP 状态码能够单独决定的。四、安全回退必须满足三个等价条件多模型网关最危险的设计是把“回退”理解为主通道报错后随机挑一个还能用的模型。能返回文本不代表结果可替代。至少要检查三类等价性。第一是接口等价。候选模型是否支持所需的工具调用、结构化输出、图片输入、上下文长度和流式协议如果主模型要求严格 JSON而候选只能尽力输出文本回退后下游解析失败只是把故障推迟了一步。第二是业务等价。营销文案草稿可能允许换模型合同结论、权限判断和会触发交易的决策通常不能静默降级。高风险任务可以失败可以进入人工队列但不应在用户不知道的情况下改变决策能力。第三是审计等价。系统必须记录实际使用的模型、来源、路由原因、尝试序号和 Prompt 版本。否则用户看到一个答案却无法知道它是不是由预期模型产生也无法复盘同一任务为什么前后表现不同。可以把路由策略写成显式配置而不是散落在异常处理代码中。routes: code_draft: fallback_allowed: true require: - streaming candidates: - primary-code-model - secondary-code-model contract_decision: fallback_allowed: false on_failure: manual_review tool_agent: fallback_allowed: true require: - tool_calling - strict_json forbid_after_stream_started: true配置的价值不只是方便修改更重要的是让评审、测试和审计有一个确定对象。每次变更都应带版本运行记录保存当时采用的策略版本。五、SSE 断流要按“部分结果”处理流式请求有三个不同阶段尚未收到响应头、已建立流但未输出业务 token、已经把部分 token 发给用户。前两种情况在满足预算和幂等条件时可能重试第三种情况则需要更谨慎。如果客户端已经展示“建议执行以下三步”随后连接中断另一个模型从头生成的内容不能直接接在后面。可选做法有三种丢弃当前可见内容明确提示用户正在整体重试并从新响应重新渲染。保留部分内容标记输出不完整让用户主动决定是否重新生成。对不可重复的长任务保存 checkpoint从确定性步骤恢复而不是要求模型猜测前文。无论采用哪一种都不要把两个模型的 token 流无标记地拼成一个答案。服务端日志还应记录首 token 时间、最后事件序号、已发送字节数和断开位置这些字段比一条笼统的“stream error”更有诊断价值。六、熔断器保护的是依赖不是成功率报表当某个模型或来源持续超时继续把每个新请求送过去再等待失败会耗尽连接池并抬高全部用户的尾延迟。熔断器可以按“模型 来源 区域”维护状态CLOSED正常放行并统计结果。OPEN短时间拒绝新请求避免继续冲击故障依赖。HALF_OPEN只放少量探测请求确认恢复后再逐步放量。熔断阈值不能照搬固定数字。低频通道只失败两次就熔断样本可能不足高频通道只看失败比例又可能掩盖大量绝对失败。更实用的做法是同时考虑最小样本、滚动窗口、错误类别和业务等级并通过历史基线确定阈值。回退通道也必须有独立熔断器和容量保护。主通道故障时流量会瞬间转向备选如果备选没有预留容量所谓高可用只会变成级联故障。七、可观测性要能还原一次路由决策建议为每次尝试记录结构化事件而不是只保存最终状态。{ run_id: demo_run_001, attempt: 2, route: secondary-code-model, reason: primary_rate_limited, error_class: null, stream_started: false, latency_ms: 0, policy_version: route-policy-v4 }上面的数值只是字段示例不代表任何线上统计。真实系统应在请求结束时填写实际延迟同时避免记录完整 Key、敏感 Prompt 和用户数据。监控至少回答五个问题429 集中在哪个租户与模型重试放大了多少请求回退后成功与失败分别是多少有多少流在输出后中断有多少调用进入“结果未知”并等待对账。只盯最终成功率很容易把高延迟、重复尝试和静默降级藏起来。八、上线前做四类故障注入在预发布环境可以主动模拟连续 429 并返回不同等待时间上游在接收请求后断开连接SSE 输出一半后中止主备通道同时拥塞。验收标准不只是最后得到答案还应包括总尝试次数没有超预算、不可回退任务没有切模型、部分流没有被错误拼接、结果未知的动作没有重复执行。最后再检查一个经常遗漏的边界认证和策略错误不得通过换 Key、换来源自动绕过。高可用解决的是暂时性故障不是规避权限控制。生产级多模型调用的目标不是“无论如何都返回一段文本”而是在依赖异常时仍能说明发生了什么、为什么选择当前动作以及是否可以安全继续。关于可回退与不可回退任务的进一步检查项可参考 失败回退策略清单。
接入一个模型 API最容易写出的代码通常只有三步组装请求、等待响应、失败后再试一次。Demo 阶段这足够了进入生产环境以后同一段“再试一次”却可能同时制造请求风暴、重复扣费、半截流式输出和不可解释的模型切换。问题不在于有没有重试而在于系统是否知道自己正在重试什么。429表示当前请求受到速率或配额约束连接超时表示客户端没有在期限内得到结果502可能是上游临时故障而“连接在提交后断开”则意味着外部系统可能已经接受请求。它们都表现为一次异常但恢复动作并不相同。生产级调用层的第一条规则应该是先分类再决定重试、对账、回退还是显式失败。一、把失败分成六类可以先建立一个与具体 SDK 无关的错误表。类型常见现象默认动作RATE_LIMIT429、响应带重试提示遵守服务端等待时间并受全局重试预算限制TRANSIENT连接建立失败、临时 502/503有上限地退避重试INVALID_REQUEST参数错误、模型名不存在、Schema 不合法立即失败修复请求后再发AUTH_OR_POLICYKey 无效、权限不足、策略拒绝立即失败并告警禁止换通道绕过PARTIAL_STREAMSSE 已输出部分 token 后断开标记不完整由业务决定整体重跑或交给用户RESULT_UNKNOWN请求可能已提交但响应在确认前丢失先对账禁止盲目重放这里最容易被忽略的是最后两类。只要客户端已经把部分内容展示给用户换一个模型继续生成就可能造成语气、事实和结构突变。只要某个工具调用可能产生外部副作用网络报错也不等于调用失败。把这两种情况重新放回普通重试队列是重复发信、重复写库和结果拼接错乱的常见起点。二、429 不是“立刻换一个 Key”收到 429 后立即轮换 Key看起来能提高成功率实际上可能绕过账号级限流也会把原本可控的拥塞扩散到全部通道。更稳妥的顺序是读取服务端提供的等待时间没有明确提示时再使用指数退避。为同一租户、模型和来源设置并发上限避免一个热点用户拖垮全局。给一次业务运行设置总重试预算而不是让每层 SDK 各自重试三次。等待时间超过业务截止期限时直接返回可解释的繁忙状态。只有策略明确允许时才进入候选模型或候选来源。退避要加入随机抖动。假设一百个 worker 同时在整秒收到 429如果都在两秒后同时重发下一轮仍会形成尖峰。Full Jitter 的思路很简单先按尝试次数计算等待上限再在零到上限之间随机取值。import random import time def retry_delay(attempt: int, retry_after: float | None None) - float: if retry_after is not None: return max(0.0, retry_after) cap min(30.0, 0.8 * (2 ** (attempt - 1))) return random.uniform(0.0, cap) def sleep_before_retry(attempt: int, retry_after: float | None) - None: time.sleep(retry_delay(attempt, retry_after))这段代码只解决“等多久”没有解决“能不能再发”。真正的重试条件还要同时检查错误类型、截止时间、剩余预算和请求是否可安全重放。三、把重试预算放在最外层一个常见的隐性放大来自多层重试HTTP 客户端试三次模型 SDK 再试三次任务队列失败后又重跑三次理论上一次业务动作可能被放大到二十多次。即便每一层都“很保守”组合起来也会失控。调用链应该只保留一个拥有最终决策权的重试控制器。底层库可以报告规范化错误但不自行无限恢复。控制器至少持有以下状态run_id 本次业务运行 deadline 最晚完成时间 attempts_used 已使用尝试次数 retry_budget 总尝试上限 selected_route 当前模型与来源 request_hash 规范化请求哈希 stream_started 是否已经向用户输出内容 effect_state none / pending / confirmed / unknown当stream_startedtrue时自动换模型续写通常应被禁止当effect_stateunknown时恢复器应先查询效果账本或下游回执。一次请求是否可重放是业务属性不是 HTTP 状态码能够单独决定的。四、安全回退必须满足三个等价条件多模型网关最危险的设计是把“回退”理解为主通道报错后随机挑一个还能用的模型。能返回文本不代表结果可替代。至少要检查三类等价性。第一是接口等价。候选模型是否支持所需的工具调用、结构化输出、图片输入、上下文长度和流式协议如果主模型要求严格 JSON而候选只能尽力输出文本回退后下游解析失败只是把故障推迟了一步。第二是业务等价。营销文案草稿可能允许换模型合同结论、权限判断和会触发交易的决策通常不能静默降级。高风险任务可以失败可以进入人工队列但不应在用户不知道的情况下改变决策能力。第三是审计等价。系统必须记录实际使用的模型、来源、路由原因、尝试序号和 Prompt 版本。否则用户看到一个答案却无法知道它是不是由预期模型产生也无法复盘同一任务为什么前后表现不同。可以把路由策略写成显式配置而不是散落在异常处理代码中。routes: code_draft: fallback_allowed: true require: - streaming candidates: - primary-code-model - secondary-code-model contract_decision: fallback_allowed: false on_failure: manual_review tool_agent: fallback_allowed: true require: - tool_calling - strict_json forbid_after_stream_started: true配置的价值不只是方便修改更重要的是让评审、测试和审计有一个确定对象。每次变更都应带版本运行记录保存当时采用的策略版本。五、SSE 断流要按“部分结果”处理流式请求有三个不同阶段尚未收到响应头、已建立流但未输出业务 token、已经把部分 token 发给用户。前两种情况在满足预算和幂等条件时可能重试第三种情况则需要更谨慎。如果客户端已经展示“建议执行以下三步”随后连接中断另一个模型从头生成的内容不能直接接在后面。可选做法有三种丢弃当前可见内容明确提示用户正在整体重试并从新响应重新渲染。保留部分内容标记输出不完整让用户主动决定是否重新生成。对不可重复的长任务保存 checkpoint从确定性步骤恢复而不是要求模型猜测前文。无论采用哪一种都不要把两个模型的 token 流无标记地拼成一个答案。服务端日志还应记录首 token 时间、最后事件序号、已发送字节数和断开位置这些字段比一条笼统的“stream error”更有诊断价值。六、熔断器保护的是依赖不是成功率报表当某个模型或来源持续超时继续把每个新请求送过去再等待失败会耗尽连接池并抬高全部用户的尾延迟。熔断器可以按“模型 来源 区域”维护状态CLOSED正常放行并统计结果。OPEN短时间拒绝新请求避免继续冲击故障依赖。HALF_OPEN只放少量探测请求确认恢复后再逐步放量。熔断阈值不能照搬固定数字。低频通道只失败两次就熔断样本可能不足高频通道只看失败比例又可能掩盖大量绝对失败。更实用的做法是同时考虑最小样本、滚动窗口、错误类别和业务等级并通过历史基线确定阈值。回退通道也必须有独立熔断器和容量保护。主通道故障时流量会瞬间转向备选如果备选没有预留容量所谓高可用只会变成级联故障。七、可观测性要能还原一次路由决策建议为每次尝试记录结构化事件而不是只保存最终状态。{ run_id: demo_run_001, attempt: 2, route: secondary-code-model, reason: primary_rate_limited, error_class: null, stream_started: false, latency_ms: 0, policy_version: route-policy-v4 }上面的数值只是字段示例不代表任何线上统计。真实系统应在请求结束时填写实际延迟同时避免记录完整 Key、敏感 Prompt 和用户数据。监控至少回答五个问题429 集中在哪个租户与模型重试放大了多少请求回退后成功与失败分别是多少有多少流在输出后中断有多少调用进入“结果未知”并等待对账。只盯最终成功率很容易把高延迟、重复尝试和静默降级藏起来。八、上线前做四类故障注入在预发布环境可以主动模拟连续 429 并返回不同等待时间上游在接收请求后断开连接SSE 输出一半后中止主备通道同时拥塞。验收标准不只是最后得到答案还应包括总尝试次数没有超预算、不可回退任务没有切模型、部分流没有被错误拼接、结果未知的动作没有重复执行。最后再检查一个经常遗漏的边界认证和策略错误不得通过换 Key、换来源自动绕过。高可用解决的是暂时性故障不是规避权限控制。生产级多模型调用的目标不是“无论如何都返回一段文本”而是在依赖异常时仍能说明发生了什么、为什么选择当前动作以及是否可以安全继续。关于可回退与不可回退任务的进一步检查项可参考 失败回退策略清单。
