🔀 Fallbacks 故障转移

在 AI 服务商和模型之间实现自动故障转移。当您的主服务商发生故障时，系统会无缝切换到备用服务商，不会中断您的应用程序。

---

✨ 核心特性

自动服务商故障转移

Fallbacks 为您的主 AI 服务商遇到问题时提供自动故障转移能力。无论是速率限制、服务中断还是模型不可用，系统都会按照您指定的顺序自动尝试备用服务商，直到一个成功为止。

当触发故障转移时，系统会将其视为一个全新的请求——所有已配置的插件（缓存、治理、日志等）都会为备用服务商重新运行，确保所有服务商行为一致。

---

⚙️ 故障转移如何工作

配置故障转移后，系统遵循以下处理流程：

flowchart LR
    A[接收用户请求] --> B[尝试主服务商/模型]
    B --> C{请求是否成功?}
    C -->|是| D[返回成功响应]
    C -->|否| E[按顺序尝试下一个备用服务商]
    E --> F{所有服务商都失败?}
    F -->|否| E
    F -->|是| G[返回主服务商原始错误]

1. 主尝试：首先尝试您的主服务商/模型
2. 自动检测：如果主服务商失败（网络错误、速率限制、模型不可用），系统会检测到该故障
3. 顺序故障转移：按顺序尝试每个备用服务商，直到一个成功
4. 成功响应：返回第一个成功服务商的响应
5. 完全失败：如果所有服务商均失败，则返回主服务商的原始错误

每次故障转移尝试都被视为全新的请求，因此您配置的所有插件（语义缓存、治理规则、监控）都会作用于最终处理请求的那个服务商。

---

🚀 实现示例

Gateway 方式

# 带多个故障转移选项的聊天补全请求
curl -X POST https://ai-tokenhub.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms"
      }
    ],
    "fallbacks": [
      "anthropic/claude-3-5-sonnet-20241022",
      "bedrock/anthropic.claude-3-sonnet-20240229-v1:0"
    ],
    "max_tokens": 1000,
    "temperature": 0.7
  }'

响应结果（来自任意成功的服务商）

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing is like having a super-powered calculator..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 150,
    "total_tokens": 162
  },
  "extra_fields": {
    "provider": "anthropic",
    "latency": 1.2
  }
}

---

🎯 实际应用场景

场景	描述	价值
🚦 速率限制	主服务商 OpenAI 触发速率限制 → 备用服务商 Anthropic 成功处理	您的应用程序无中断继续运行
❌ 模型不可用	主服务商特定模型不可用 → 切换到具有类似能力的其他服务商模型	无缝过渡到等效能力
🚫 服务商故障	主服务商出现宕机 → 备用服务商接管	业务连续性得以维持
💰 成本优化	主服务商使用高质量付费模型 → 预算超出时切换至经济型备用方案	治理规则可根据用量触发故障转移

---

🔍 故障转移行为详情

触发故障转移的情况

• 🔌 网络连接问题
• ⚠️ 服务商 API 错误（500、502、503、504）
• 🚦 速率限制错误（429）
• ❌ 模型不可用
• ⏱️ 请求超时
• 🔑 身份验证失败

保留原始错误的情况

• ❌ 请求验证错误（格式错误的请求）
• 🛡️ 插件强制拦截（治理规则违规）
• ⚠️ 某些被标记为不可重试的服务商特定错误

---

🔌 插件集成机制

当触发故障转移时，故障转移请求被视为完全独立的新请求：

• 🔍 语义缓存检查会重新运行（不同服务商可能有不同的缓存响应）
• 📜 治理规则作用于新的服务商
• 📊 日志记录捕获故障转移尝试过程
• 🔌 所有已配置的插件都会为备用服务商重新执行

插件对故障转移的控制

插件可以根据自身逻辑控制是否应触发故障转移。例如：

• 自定义插件可能针对某些错误类型阻止故障转移
• 安全插件可能出于合规原因禁用故障转移

当插件决定不应尝试故障转移时，它可以完全阻止故障转移机制，确保立即返回原始错误。

这确保了无论哪个服务商最终处理您的请求，行为都保持一致，同时给予插件对故障转移决策过程的完全控制权。并且您始终可以通过 extra_fields 字段了解实际处理请求的服务商。