> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型路由与故障切换

> 区分模型 ID、供应商选择、渠道重试与应用层回退。

## 一次请求如何选路

客户端发送部署方公布的一个 `model` ID。网关结合令牌允许的供应商类别、自动或手动路由设置、当前授权、模型、请求路径与渠道可用性筛选候选渠道。手动绑定和自动路由受各自配置约束；自动路由不代表可以访问所有供应商。

| 概念 | 接入方需要知道的内容 |
| - | - |
| 模型 ID | 从当前部署的模型列表选择；完整保留前缀和大小写 |
| 模型映射 | 部署方可把对外 ID 映射到上游 ID；请求中的 ID 不保证等于上游名称 |
| 供应商与渠道 | 一个模型可能有多个候选渠道；顺序、权重、健康状态与容量由部署策略决定 |
| 渠道重试 | 网关在同一请求内按策略重新尝试；次数、状态码和渠道覆盖配置都会影响结果 |
| 应用模型回退 | 应用主动用另一个模型发起新请求；应重新验证能力、上下文和输出结构 |

模型列表可见不等于每条渠道都支持工具、JSON Schema、媒体或状态恢复，先看[模型能力](/zh/guides/model-capabilities)。请求的 `group` 不是通用的供应商选择字段；当前代码只在 Playground 的专用入口处理该字段。

## 重试的边界

网关会考虑请求取消、重试预算、错误分类、渠道限制和会话策略。普通 HTTP 响应已经开始写出后会停止对应的重试路径；严格会话或固定渠道也可能阻止切换。不要承诺任何错误一定会切到另一条渠道。

客户端 SDK 的重试次数与网关内部次数不是同一个计数。本地示例默认关闭生成请求的 SDK 自动重试。上线前让部署方说明内部预算，再设置应用总截止时间、排队上限和恢复策略。

## 如果业务需要备用模型

1. 预先选择并验证主模型和备用模型的协议、工具 schema、上下文容量和输出约束。
2. 明确允许回退的错误与总尝试次数；鉴权失败、无权限和参数错误应先修正配置。
3. 在应用层记录每次新请求使用的模型及网关请求 ID。结果已经部分展示时，应明确开始新一轮，不能把两次输出拼接成同一个回答。
4. 已执行的工具、已提交的媒体任务和外部写操作要先核对状态。网络超时不能证明上游没有执行。
5. Responses ID、压缩状态、原生签名及 WebSocket 会话不能假定可跨渠道或跨模型复用；必要时使用经过审查的可移植对话历史。

本站不提供自动重发生成请求的通用脚本，因为重复提交与状态兼容性必须由应用处理。只读重试示例见[限流与重试](/zh/guides/rate-limits)。

## 从 OpenRouter 迁移时

OpenRouter 的 `models` 回退数组、`provider.order`、路由后缀及其专用限额查询 API 不属于本文档核对的通用接入契约。不要仅凭接口兼容就复制这些配置。这里采用单个 `model` 字段；具体扩展必须由目标部署另行确认。

本页按项目源码 `30a6d88a4` 的 `middleware/distributor.go`、`service/channel_select.go`、`service/group.go`、`service/relay_error.go` 与 `relay/helper/model_mapped.go` 核对。路由设置由部署方管理，本页不修改后台配置。

[SDK 迁移](/zh/guides/sdk-migration) · [生产接入](/zh/guides/production)

[Read in English](/en/guides/model-routing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.