Skip to Content
開發文件進階功能故障回退

故障回退

OfoxAI 的故障回退機制在主模型不可用時，自動切換到備選模型，確保你的服務不中斷。

運作原理

  1. 請求傳送到主模型
  2. 如果主模型回傳錯誤（5xx、逾時、限流等）
  3. 自動按順序嘗試 fallback 列表中的模型
  4. 回傳第一個成功的回應

單請求回退

透過 provider.fallback 參數為單個請求設定回退：

fallback.py
from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<你的 OFOXAI_API_KEY>"
)
 
response = client.chat.completions.create(
    model="openai/gpt-4o",  # 主模型
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "provider": {
            "fallback": [
                "anthropic/claude-sonnet-4.5",  # 第一備選
                "google/gemini-3-flash-preview"              # 第二備選
            ]
        }
    }
)
 
# 查看實際使用的模型
print(response.model)
fallback.ts
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '你好' }],
  // @ts-ignore OfoxAI 擴充參數
  provider: {
    fallback: [
      'anthropic/claude-sonnet-4.5',
      'google/gemini-3-flash-preview'
    ]
  }
})

全局回退設定

在 OfoxAI 控制台中設定全局回退策略，無需在每次請求中指定：

  1. 登入 OfoxAI 控制台 
  2. 進入 設定 → 路由策略
  3. 設定預設回退模型列表

單請求級別的 fallback 參數會覆蓋全局設定。

回退觸發條件

以下情況會觸發回退：

條件說明
HTTP 5xx伺服器錯誤
請求逾時模型回應逾時
429 限流上游模型達到速率限制
模型不可用供應商維護或下線

以下情況不會觸發回退：

條件說明
HTTP 4xx（非 429）用戶端錯誤需要修正請求
內容過濾模型拒絕生成的內容

配合路由使用

回退機制可以和供應商路由組合：

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "provider": {
            "routing": "latency",    # 延遲優先路由
            "fallback": [             # 回退列表
                "anthropic/claude-sonnet-4.5",
                "google/gemini-3-flash-preview"
            ]
        }
    }
)

推薦回退方案

通用對話

"provider": {
    "fallback": ["anthropic/claude-sonnet-4.5", "google/gemini-3-flash-preview"]
}

程式碼生成

"provider": {
    "fallback": ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"]
}

高性價比

"provider": {
    "fallback": ["openai/gpt-4o-mini", "google/gemini-3-flash-preview", "deepseek/deepseek-chat"]
}

最佳實踐

  1. 選擇能力相近的備選模型 — 確保回退後輸出品質一致
  2. 跨廠商回退 — 避免同一廠商的模型同時不可用
  3. 設定 2-3 個備選 — 足以應對大部分故障場景
  4. 監控回退頻率 — 如果頻繁回退，可能需要更換主模型
Last updated on
供應商路由提示快取