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

故障回退

provider.fallback 用於列出備選模型。主模型在上游呼叫失敗時，按清單順序依次嘗試。

設定方式

fallback 接受一個模型 ID 陣列，與 type 同級掛在 provider 底下。最多 3 個模型，超出回傳 400。

Terminal
curl https://api.ofox.io/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

使用官方 OpenAI SDK 時，extra_body 需作為請求主體中的字面量鍵存在。TypeScript SDK 在參數物件中直接書寫 extra_body 即可；Python SDK 的 extra_body= 參數會將其內容合併至請求主體最上層，因此需額外巢狀一層，或改用請求標頭傳遞。

什麼情況下會降級

降級只涵蓋路由選定通道之後發生的失敗：

情況行為
上游供應商回傳錯誤降級 —— 按順序嘗試清單中的模型，回傳第一個成功的回應
路由期失敗（模型不存在，或指定的供應商不承載該模型）不降級 —— 請求直接終止

第二列值得明確寫出來：把 provider.type 指定到不承載該模型的供應商，回傳 400 provider_type_unavailable；指定不存在的模型，回傳 404 model_not_found。兩者都不會走到 fallback 清單。具體哪些上游錯誤會觸發降級，以閘道的實際行為為準，文件不列固定清單。

與指定供應商組合

fallback 與 type 可以同時傳 —— type 約束主模型跑在哪個供應商上，fallback 負責主模型失敗之後的事：

{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

欄位完整說明見 供應商路由。

常見錯誤

error.type觸發條件
invalid_request_errorfallback 清單超過 3 個模型。

最佳實務

  1. 選擇能力相近的備選模型 —— 確保降級後輸出品質一致。
  2. 跨廠商備選 —— 同一廠商的模型往往同時不可用。
  3. 監控降級頻率 —— 頻繁降級說明主模型該換了。
Last updated on
供應商路由提示快取