故障回退

通过 provider.fallback 配置备用模型，在主模型不可用时自动切换到下一个可用模型，提升服务可用性。

工作原理

当主模型返回 5xx 错误或超时等可恢复错误时，UloveGPT Gateway 会自动尝试 fallback 列表中的下一个模型。这个过程对客户端完全透明，返回的响应格式保持一致。

使用方法

在请求的 extra_body 中添加 provider.fallback 数组：

from openai import OpenAI

client = OpenAI(
    base_url="https://www.ulovegpt.com/v1",
    api_key="<你的 API_KEY>"
)

# 使用 provider.fallback 指定备用模型
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "user", "content": "解释量子纠缠"}
    ],
    extra_body={
        "provider": {
            "fallback": [
                "anthropic/claude-sonnet-4-20250514",
                "openai/gpt-5.4",
                "google/gemini-3.1-pro"
            ]
        }
    }
)

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

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://www.ulovegpt.com/v1',
  apiKey: '<你的 API_KEY>'
})

async function main() {
  const response = await client.chat.completions.create({
    model: 'anthropic/claude-sonnet-4.6',
    messages: [
      { role: 'user', content: '解释量子纠缠' }
    ],
    extra_body: {
      provider: {
        fallback: [
          'anthropic/claude-sonnet-4-20250514',
          'openai/gpt-5.4',
          'google/gemini-3.1-pro'
        ]
      }
    }
  })

  console.log(response.choices[0].message.content)
}

main()

Fallback 顺序策略

建议按照以下优先级排列 fallback 模型：

1. 同提供商的替代版本：如 claude-sonnet-4.6 → claude-sonnet-4-20250514
2. 同类别的竞品模型：如 claude-sonnet → gpt-5.4（同等级别）
3. 更广泛可用的模型：如 gpt-5.4-mini、gemini-flash（确保最终有可用模型）

最佳实践

• 响应头标识：检查响应 Header 中的 x-used-model 确认实际使用的模型
• 能力兼容：确保 fallback 模型支持你使用的功能（如 function calling、vision）
• 成本控制：fallback 到更贵的模型会增加成本，合理安排优先级
• 日志记录：记录 fallback 触发事件，用于分析模型可用性
• 不要过多：建议 2-3 个 fallback 即可，过多增加延迟