故障回退

概述

当前公开 API 没有开放“按请求指定 fallback 规则”的 Header 或前台配置项。就现状而言，更可靠的回退方式仍然是：在后台准备备用模型/备用上游 Key，并在客户端按模型列表做重试切换。

回退策略

1. 同 provider 多 Key 冗余

当前最接近“回退”的平台能力，是在同一个 provider 下准备多把可用 Key，避免单 Key 配额或状态问题直接影响整体可用性：

provider: openai_compatible
provider_api_keys:
  - key_primary
  - key_backup

控制台虽然会把 openai_compatible 显示名为 OpenAI，但请求头中的 provider 值仍需使用 openai_compatible，不要把展示名直接写进程序里的 fallback 配置。

2. 客户端模型重试

如果某个模型不可用，更稳妥的做法是在客户端准备一组候选模型，并按 /v1/models 的返回结果依次尝试：

preferred_models = [
  "qwen3.5-plus",
  "your-backup-chat-model"
]

触发条件

以下情况通常意味着您需要执行备用模型或备用 Key 策略：

• 上游返回 5xx 或明确错误
• 请求超时
• 模型未启用或 model_not_found
• 当前 Key 限流或失效

配置示例

from openai import OpenAI

client = OpenAI(
    base_url="https://api.vip.lingapi.ai/v1",
    api_key="sk-xxxxxxxx"
)

# 客户端侧模型回退示例
for model_id in ["qwen3.5-plus", "your-backup-chat-model"]:
    try:
        response = client.chat.completions.create(
            model=model_id,
            messages=[{"role": "user", "content": "Hello"}]
        )
        print(response.choices[0].message.content)
        break
    except Exception:
        continue

{"x-fallback-providers": "openai,bailian,openai_compatible"}

最佳实践

• 预先拉取模型列表：不要硬编码不存在的模型 ID
• 准备备用模型：按场景准备至少一个候选模型
• 记录失败原因：结合错误码判断是模型、Key 还是上游问题