故障回退

主模型失败时自动切换到备用模型，保障服务高可用

什么是故障回退

故障回退（Fallback）是一种高可用机制，当主模型请求失败时，系统会自动尝试备用模型列表中的下一个模型，直到请求成功或所有备用模型都失败。

fallback 参数

通过 provider.fallback 配置数组指定备用模型列表，按顺序依次尝试

数组格式 — 支持配置多个备用模型，按配置顺序优先级递减
模型格式 — 与主模型格式一致，如 anthropic/claude-sonnet-4-5
自动切换 — 主模型失败后自动切换，无需额外处理

使用示例

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.mintcloud.ai/v1",
    api_key="<your MINTCLOUD_API_KEY>"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {
            "fallback": [
                "anthropic/claude-sonnet-4-5",
                "google/gemini-3.1-flash-lite-preview"
            ]
        }
    }
)

print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai"

const client = new OpenAI({
  baseURL: "https://api.mintcloud.ai/v1",
  apiKey: process.env.MINTCLOUD_API_KEY,
})

async function main() {
  const response = await client.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
    extra_body: {
      provider: {
        fallback: [
          "anthropic/claude-sonnet-4-5",
          "google/gemini-3.1-flash-lite-preview"
        ]
      }
    }
  })
  console.log(response.choices[0].message.content)
}

main()

路由策略 + 回退

路由策略和故障回退可以组合使用，发挥各自优势

priority+fallback组合示例

使用 priority 策略确保优先使用高优先级供应商，当主供应商完全不可用时，fallback 机制接管，切换到备用模型列表

主模型：openai/gpt-4o（priority 策略）
备用模型 1：anthropic/claude-sonnet-4-5
备用模型 2：google/gemini-3.1-flash-lite-preview

触发条件

超时

请求响应时间超过预设阈值（默认 30s）

服务器错误

供应商返回 5xx 错误码

限流

触发 Rate Limit 或配额限制

最佳实践

配置 2-3 个备用模型 — 过多会增加延迟，过少则无法充分保障可用性
选择能力相近的模型 — 确保回退后输出质量相对一致，用户体验不受影响
定期测试回退流程 — 建议每月模拟故障场景，验证回退机制有效性