Skip to Content
开发指南故障回退

故障回退

provider.fallback 用于列出备选模型。主模型在上游调用失败时，按列表顺序依次尝试。

配置方式

fallback 接受一个模型 ID 数组，与 type 同级挂在 provider 下。最多 3 个模型，超出返回 400。

Terminal
curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-6.1-sol", "google/gemini-3.8-flash"]
      }
    }
  }'

使用官方 OpenAI SDK 时，extra_body 需作为请求体中的字面量键存在。TypeScript SDK 在参数对象中直接书写 extra_body 即可；Python SDK 的 extra_body= 参数会将其内容合并至请求体顶层，因此需额外嵌套一层，或改用请求头传递。

什么情况下会降级

降级只覆盖路由选定渠道之后发生的失败：

情况行为
上游供应商返回错误降级 —— 按顺序尝试列表中的模型，返回第一个成功的响应
路由期失败（模型不存在，或指定的供应商不承载该模型）不降级 —— 请求直接终止

第二行值得明确写出来：把 provider.type 指定到不承载该模型的供应商，返回 400 provider_type_unavailable；指定不存在的模型，返回 404 model_not_found。两者都不会走到 fallback 列表。具体哪些上游错误会触发降级，以网关的实际行为为准，文档不列固定清单。

与指定供应商组合

fallback 与 type 可以同时传 —— type 约束主模型跑在哪个供应商上，fallback 负责主模型失败之后的事：

{
  "model": "anthropic/claude-sonnet-5.5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-6.1-sol"]
    }
  }
}

字段完整说明见 供应商路由。

常见错误

error.type触发条件
invalid_request_errorfallback 列表超过 3 个模型。

最佳实践

  1. 选择能力相近的备选模型 —— 确保降级后输出质量一致。
  2. 跨厂商备选 —— 同一厂商的模型往往同时不可用。
  3. 监控降级频率 —— 频繁降级说明主模型该换了。
最后更新于
供应商路由错误处理与重试