模型路由与故障切换 - API Docs

一次请求如何选路

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

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

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

重试的边界

网关会考虑请求取消、重试预算、错误分类、渠道限制和会话策略。普通 HTTP 响应已经开始写出后会停止对应的重试路径；严格会话或固定渠道也可能阻止切换。不要承诺任何错误一定会切到另一条渠道。客户端 SDK 的重试次数与网关内部次数不是同一个计数。本地示例默认关闭生成请求的 SDK 自动重试。上线前让部署方说明内部预算，再设置应用总截止时间、排队上限和恢复策略。

如果业务需要备用模型

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

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

从 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 迁移 · 生产接入 Read in English