# 失败重试与备用模型

来源: https://platform.lyrouter.com/ai_gateway/docs/fallback
更新日期: 2026-10-22

一次调用失败时，网关会在开始向客户端输出内容之前，自动改用下一个凭证、通道或模型，直到成功或候选用完。客户端只收到最终结果，所以一次请求成功，不代表过程中没有发生上游失败；每次实际尝试都记录在请求日志中。

## 回退顺序

直接调用模型 ID 时，网关按以下顺序尝试：

1. 按「多渠道选路策略」排好序的第 1 个通道：
   - 先用该通道下的 BYOK 凭证，按你在 BYOK 中设置的顺序；
   - 再用该通道的平台凭证（工作空间在模型广场开通了该通道时）。
2. 第 2 个、第 3 个……通道，每个通道内同样先用 BYOK 凭证、再用平台凭证。
3. 最后是工作空间「默认模型」的通道（设置了默认模型、且与请求的模型不同时）。

- **哪些失败会换下一个**：上游返回任何非 2xx 状态码、连接上游失败或等待超时，都会换下一个凭证或通道。
- **已达限额的凭证先被跳过**：达到限额的凭证或通道在排序时就被移出。全部因限额被移出、也没有默认模型可以接手时，返回 429 `all upstream credentials for this model are rate limited`。
- **全部失败时**：返回最后一次尝试的上游状态码和响应体。
- **通道排序与 BYOK 偏好**：见[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing)。「优先使用此 Channel」只把通道提到最前，失败后照常回退；「仅用此 BYOK」会限制回退范围，见下表。

## 跨模型的备用模型

需要在一个模型失败后改用另一个模型时，有两种做法：

- **[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)**：按「默认模型 → 备用模型（按填写顺序）→ 工作空间默认模型」的顺序尝试，前一个模型的所有通道都失败后才进入下一个模型。
- **工作空间[默认模型](https://platform.lyrouter.com/ai_gateway/docs/routing)**：作为所有对话类请求的最后兜底。

[`lyrouter/auto`](https://platform.lyrouter.com/ai_gateway/docs/auto) 也按模型依次尝试，最后同样是工作空间默认模型。

（截图：在虚拟模型配置中确认主模型和备用模型；备用模型还需支持原请求的关键能力。）

备用模型必须支持原请求使用的接口、输入类型和工具调用。网关不会因为备用模型能力不足而跳过它；模型不支持请求的输入时，请求会直接返回 400，不再尝试后面的模型。

## 不会回退的情况

| 情况 | 结果 |
| --- | --- |
| 流式请求（`stream: true`）已经开始输出后，上游中断或超时 | 不换通道。在流末尾补发一个错误事件后结束：Chat Completions 中 `error.code` 为 `stream_interrupted`，Responses 中是 `response.failed` 事件，见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors) |
| 通道开启了「仅用此 BYOK」 | 只尝试该通道的 BYOK 凭证，全部失败即结束，不使用平台凭证、其他通道或默认模型。通过虚拟模型或 `lyrouter/auto` 调用时，仍会尝试下一个候选模型，但不再回退到默认模型 |
| 网关拒绝了这次尝试：余额不足（402）、安全围栏的模型策略禁止所选模型（403 `Request blocked by guardrail policy`）、所选模型不支持当前接口或输入（400 `unsupported_model_api`、`unsupported_model_input`） | 直接返回该错误，不换下一个候选 |
| 上游以约定格式声明生成失败（`error.code` 为 `upstream_rejected` 或 `upstream_no_artifact`，常见于图像生成） | 直接返回，不换通道 |
| 图像、视频和语音接口 | 只在同一模型的通道之间回退，不改用默认模型或其他模型 |

## 客户端的重试

网关已经在内部回退，客户端不需要对每个错误都自动重试：

- 对 400、401、402、403 这类请求或配置问题，修正后再调用；同样的请求重试会得到同样的结果。
- 对 429 和 503，按[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)和[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable)的说明处理，使用有上限的退避重试。
- 同一个 API Key 在 60 秒内至少有 100 次请求、且 90% 以上失败时会被临时熔断，网关自己返回的 4xx 也计入失败。持续失败的程序不停重试，会很快把密钥熔断，多次熔断后会被永久封禁。

## 定位一次回退

### 怎么判断一次请求是否发生了回退？

**答：** 在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中打开这条记录，查看「路由追踪」中的「上游调用尝试」，它记录每一次实际尝试的状态码、耗时和换下一个候选的原因；只尝试了一次的请求不显示这一块。「各阶段耗时」的「④ 上游调用」旁显示「N 次尝试」时，也说明发生过重试。「全部候选」只是排好序的候选列表，不能证明候选都被调用过。「路由追踪」只对账号管理员和工作空间管理员显示，其他成员可以把日志详情顶部的 Request ID 发给账号管理员协助核查。

（截图：日志详情的路由追踪显示实际模型、服务商和上游调用尝试。）

### 为什么回答来自请求之外的模型？

**答：** 请求的模型全部失败，或在本工作空间未开通时，网关会改用工作空间的默认模型。日志的「模型（实际）」显示实际回答的模型。不需要这种兜底时，请账号管理员在智能路由中清空默认模型。

### 流式输出已经开始，断开后可以直接重试吗？

**答：** 网关不会在输出开始后换通道。收到 `stream_interrupted` 错误事件或 `response.failed` 事件，或没有收到结束标记（`data: [DONE]`、`message_stop` 或 `response.completed`）时，应把这次调用视为失败。重新调用可能重复生成内容或再次触发工具，应用需要自行处理取消、重试和去重，详见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors)。