AI 网关怎么做模型降级：请求契约、错误分类与幂等重试

AI 网关最容易出现的一种事故，是上游模型一报错，网关就把请求原样重发给另一个模型。这样看起来“有降级”，实际上可能把同一笔扣费请求执行两次，也可能把参数错误扩散到多个供应商。更稳的做法是先统一请求契约，再把错误分成可降级、可重试和必须直返三类，最后用幂等键把一次业务请求的身份固定下来。

先把“降级”定义成一次可追踪的决策

一次业务请求至少要有 request_id、idempotency_key、模型候选序列和当前尝试次数。网关收到请求后，不要立刻把供应商名称暴露给业务层，而是把它转换成自己的统一结果：成功、客户端错误、上游限流、上游暂时不可用、网络未知和安全拒答。

OpenAI 的 API 参考文档建议记录服务端 x-request-id 以及限流相关响应头；这类上游证据应该进入网关日志，但不应直接成为业务接口的字段。网关自己的请求 ID 负责串起一次调用，供应商请求 ID 负责定位单次上游尝试，二者不要混用。

三类错误决定三种动作

第一类：可以尝试重试或降级

限流、连接超时、网关超时和明确表示暂时不可用的服务错误，才有资格进入重试判断。Google Gemini 文档把 429、408 和 5xx 归入需要按策略处理的范围，并建议指数退避、加入抖动和设置最大次数。网关还要看请求是否可能已经被上游执行：如果响应在读取阶段丢失，不能简单假设“上游没收到”。

因此，安全的顺序通常是：保留原始幂等键，先按供应商建议的退避窗口尝试一次；若预算、延迟和业务优先级允许，再切换到候选模型。流式输出已经产生部分内容时，除非业务协议支持从断点续传，否则不要把半截结果当成可透明重试的请求。

第二类：必须修配置，不能靠换模型掩盖

400 参数错误、401 鉴权失败、403 权限不足、模型名不存在以及超出上下文限制，通常说明网关自己的请求映射或账号配置有问题。把这些错误改写成“主模型失败，已切备用模型”，会让值班人员错过真正的修复信号。

Google 的错误码说明也把模型不存在、配额耗尽和服务暂不可用分开处理。网关可以根据供应商的错误码做更精细的映射，但不要只按 HTTP 状态码猜测原因。

第三类：必须原样直返

内容安全拒答、业务权限拒绝和用户输入本身不合法时，换一个模型并不能改变请求的责任边界。网关应返回稳定的业务错误码、可读的修复建议和追踪 ID，同时在内部记录供应商原始分类。

统一请求契约要保护哪些字段

主模型和备用模型的参数名称不一定相同，但网关内部应固定一份最小契约：消息或提示词、输出格式要求、最大输出预算、工具调用能力、超时预算、隐私级别和幂等键。供应商适配器只负责把这份契约翻译成对应 API 参数，并把结果还原为统一响应。

降级时可以缩短输出预算、关闭非必要工具或改用更快的模型，但这些都必须是显式策略，而不是适配器偷偷删字段。策略命中后，把变更写入尝试记录，方便复盘为什么备用模型返回了不同形态的结果。

幂等键如何穿过重试链路

幂等键不是每次 HTTP 请求重新生成的随机字符串，而是一次业务意图的稳定标识。例如订单摘要任务第一次调用主模型超时，第二次调用备用模型仍应使用同一个 idempotency_key，同时用不同的 attempt_id 区分两次上游尝试。

1. 网关入口生成或校验业务幂等键，并设置过期时间。
2. 状态机先写入 accepted，再创建主模型尝试记录。
3. 只有被策略判定为可重试或可降级的状态，才能创建下一次尝试。
4. 任意一次成功都要以幂等键为条件写入最终结果，后到的重复成功只能变成审计记录。
5. 超过总耗时、金额或次数预算后，状态转为 failed_retry_exhausted，不能无限寻找下一个模型。

一个够用的降级决策表

可以先用下面的最小规则上线，再根据真实流量补充供应商特有错误码：

• 429：读取 Retry-After 或供应商限流提示；在预算内退避，仍失败再选备用模型。
• 408 或连接超时：记录“是否已发出请求”的不确定性；幂等业务才允许继续尝试。
• 500、502、503：仅在请求契约可复用且剩余预算足够时重试或降级。
• 400、401、403、404 模型不存在：直返并告警，先修映射、凭据或模型配置。
• 安全拒答或业务拒绝：直返稳定错误，不通过换模型绕过规则。

上线前核对四个可观测结果

第一，看每个业务幂等键最终只有一个成功结果；第二，看主模型与备用模型的耗时、费用和成功率是否分开统计；第三，看未知网络错误是否被标记为“可能已执行”；第四，用故障注入验证预算耗尽时状态机会停止。OpenAI 文档提供的请求 ID 和限流头可以作为供应商维度的排查字段，但不能替代网关自己的审计链。

常见问题

所有 5xx 都应该切备用模型吗？

不应该。先确认是否属于暂时性故障、请求是否可能已执行、剩余延迟和费用预算是否允许继续。未知执行状态的写入型业务尤其需要幂等保护。

备用模型参数少一些可以吗？

可以，但必须在统一契约和策略中明确记录哪些能力被关闭，并让调用方知道结果可能是降级版本。

网关只返回最终错误还需要保存供应商错误吗？

需要。对外可以隐藏供应商细节，对内仍应保存状态码、错误码、请求 ID、尝试序号和决策原因，否则很难区分配置错误与服务波动。

把降级当作受预算约束的状态机

模型降级不是“失败后换一个名字”，而是一次受延迟、费用、数据安全和重复执行风险约束的状态迁移。统一请求契约让适配器可替换，错误分类让策略可解释，幂等键则把多次上游尝试收束为一次业务结果。三者同时成立，网关才真正具备可运营的降级能力。