AI API 備援策略:建立供應商故障矩陣
依故障類別、回應階段、冪等性與嘗試上限,決定何時重試、切換至同契約路由、停止或核對副作用。

AI API 的重試、路由備援與模型替換是三種不同動作。重試是在同一契約下再嘗試一次;路由備援是把相同模型與協定送往另一條合格路徑;模型替換則會改變模型,可能連帶改變品質、價格、延遲、工具行為、上下文限制與輸出格式。
可靠的策略不應在事故發生後才臨時決定。它必須預先回答:這是什麼類型的失敗、回應是否已交付、完整業務操作能否安全重播,以及使用者的截止時間內還容得下幾次嘗試。
分清重試、路由備援與模型替換
在設定、日誌與操作手冊中使用不同名稱。
| 動作 | 改變內容 | 合適用途 | 主要風險 |
|---|---|---|---|
| 同一路由重試 | 時間與嘗試編號 | 從同一路徑的短暫故障恢復 | 持續向不健康的依賴增加負載 |
| 同契約備援 | 上游渠道、帳戶或有序分組 | 某一路徑失敗時維持原模型與協定 | 名義相同的路徑其實不相容 |
| 模型替換 | 模型 ID 或具名模型政策 | 經產品核准的品質、成本或可用性取捨 | 靜默改變行為與計費 |
不要把三者都寫成「重試」。維運人員必須知道請求是原路重播、換了供應商路徑,還是由另一個模型回答。模型替換也必須是明確的產品契約,不應成為隱藏的救援捷徑。
部分閘道支援有序的供應商或模型步驟。例如 Cloudflare 的備援文件會揭示最後成功的步驟。值得採用的不是某家供應商的固定順序,而是「路徑一旦改變,就保留每次嘗試的證據」這項設計原則。
重播前通過四道檢查
狀態碼本身不是重試政策。每次重播前都要判斷:
- 失敗類別:失敗是暫時性、永久性、由呼叫端造成,還是完成狀態不明?
- 回應階段:發生在標頭前、有效輸出前,還是輸出已交付後?
- 冪等性:完整應用操作能否重做而不產生重複副作用?
- 嘗試額度:剩餘實際時間是否足夠,且還有未使用的嘗試次數?
Google Cloud 的重試策略對一般 API 也強調兩個基礎判斷:回應是否代表重試可能有效,以及操作是否具備冪等性。408、429、5xx、通訊端逾時與斷線常屬暫時性故障,但非冪等操作仍需要更嚴格的條件。
對 AI 工作流程而言,冪等邊界不只在模型 HTTP 請求。重播提示詞可能再次提出寄信、退款、部署或資料庫寫入。即使推論本身唯讀,工具執行仍需要穩定的冪等鍵與持久化結果。
從失敗矩陣建立策略
以下矩陣是偏保守的應用層策略。閘道可能在應用收到終態前,已完成內部的同契約渠道切換,因此兩層必須協調,不能重複放大嘗試次數。
| 失敗或階段 | 同一路由重試 | 同契約備援 | 停止或調查 | 原因 |
|---|---|---|---|---|
| 用戶端驗證錯誤、不支援的欄位或格式錯誤的請求 | 否 | 否 | 修正請求 | 重播相同錯誤契約不會成功 |
| 閘道驗證、授權、額度或政策拒絕 | 否 | 否 | 修正帳戶或政策 | 不能用另一條供應商路由繞過閘道決策 |
| 輸出前的上游憑證或帳戶失敗 | 不重試失敗路徑 | 有已驗證的合格渠道時可以 | 隔離並調查失敗渠道 | 可以在不改使用者契約下移除不健康憑證 |
輸出前的網路失敗或 408 |
冪等時最多一次有界嘗試 | 可以 | 到截止時間即停止 | 故障可能短暫,但斷線後完成狀態可能不明 |
輸出前 429 |
延後重試並遵守 Retry-After |
其他同契約路徑有容量時可以 | 額度用盡即停止 | 立即連續重試會放大限流 |
輸出前 500、502、503、504 |
有界退避 | 可以 | 路徑反覆失敗時調查 | 通常短暫,但不代表所有路徑都安全 |
| 下游輸出前收到不符合結構描述或格式錯誤的供應商回應 | 通常否 | 僅限已驗證相同結構描述的路徑 | 隔離或調查相容性 | 重複呼叫不相容實作通常無效 |
| 模型拒絕或符合安全政策的完成結果 | 否 | 否 | 回傳模型結果 | 合法拒絕不是基礎設施故障 |
呼叫端取消或下游 499 |
否 | 否 | 立即停止 | 呼叫端已不需要結果,繼續只會浪費容量與成本 |
| 可見內容或工具參數已送達後的部分串流 | 不透明重播 | 不透明備援 | 標記為部分完成,由應用決定 | 第二條串流可能重複或矛盾 |
| 工具副作用的完成狀態不明 | 核對前否 | 核對前否 | 查詢冪等紀錄或下游系統 | 再次推論可能重複提出同一副作用 |
這個矩陣刻意納入回應階段。輸出前收到 503,與已呈現 400 個文字權杖後連線中斷,不是同一種故障。
把串流開始視為提交邊界
在下游輸出開始前,閘道通常能捨棄失敗的嘗試,改走另一條合格路徑,而不讓呼叫端看到兩份答案。第一個有意義的位元組一旦到達呼叫端,透明重播就不再安全。
重新啟動串流可能:
- 重複答案開頭;
- 產生不同續寫;
- 以新的呼叫 ID 發出重複的函式呼叫;
- 在沒有清楚邊界下增加用量與成本;
- 讓用戶端無法判斷事件屬於哪次嘗試。
輸出後串流中斷時,應以原請求識別回傳明確的部分完成或傳輸錯誤。應用可以提供顯式「再試一次」、從安全檢查點繼續,或捨棄部分結果;不應把新的模型串流拼接到舊串流,假裝沒有發生故障。
函式呼叫的安全邊界更嚴格:任何重試可能重新建立工具呼叫前,先持久化已接受的工具呼叫識別與副作用結果。函式呼叫格式比較進一步說明呼叫 ID 與應用冪等性的配合方式。
同時限制嘗試次數與實際經過時間
指數退避讓嘗試分散在時間上,隨機抖動則避免大量用戶端在共同故障後同步重試。
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
有效的 Retry-After 若沒有超過使用者的截止時間,應優先遵守。但退避並不等於獲得重試許可;失敗類別與冪等性檢查仍須先通過。
策略需要總額度,而不只是重試次數:
- 單一使用者動作的最大嘗試次數;
- 包含排隊與退避的最大經過時間;
- 選擇備援分組前後各自的嘗試上限;
- 產生有用答案至少需要保留的時間;
- 呼叫端取消向所有進行中嘗試的傳播。
若互動請求的截止時間為 15 秒,安排三次各 10 秒的嘗試並不是可執行策略。批次工作負載可以使用較長額度,但仍需最終截止時間與持久工作識別。
避免跨層重試放大
假設 SDK 做一次請求加兩次重試,共三次用戶端嘗試;閘道對每次用戶端嘗試都試主要渠道加兩條備援渠道,共三次閘道嘗試;上游代理又各重試一次,共兩次供應商呼叫:
3 次用戶端嘗試 × 3 次閘道嘗試 × 2 次上游嘗試 = 18 次供應商呼叫
一個使用者動作因此變成 18 次供應商呼叫。事故期間,這會同時增加排隊、限流、成本與恢復時間。
應明確分配重試責任:
- 閘道負責立即的同契約渠道切換;
- 應用程式決定完整使用者動作是否可以重播;
- 閘道已重試時,SDK 自動重試應停用或嚴格限制;
- 非同步工作使用單一持久工作 ID 與嘗試帳本;
- 呼叫端取消後,任何一層都不得啟動新嘗試。
同時記錄「本層嘗試編號」與穩定的端到端請求 ID,否則每層看起來只重試兩三次,整體放大卻無法察覺。
驗證備援是否真的維持契約
相同公開模型名稱不代表兩條路由行為一致。把渠道加入同契約備援集合前,至少驗證:
| 契約範圍 | 所需證據 |
|---|---|
| 模型身分 | 要求的模型可用,且沒有靜默映射 |
| 端點 | 設定的 Responses 或 Chat Completions 請求能被接受 |
| 串流 | 事件類型、終止方式、用量與取消都能處理 |
| 結構化輸出 | 必要的 JSON Schema 子集與嚴格行為可運作 |
| 函式呼叫 | 工具定義、呼叫 ID、參數串流與結果能完整往返 |
| 限制 | 上下文、輸出、速率與並行限制符合工作負載 |
| 錯誤 | 狀態與錯誤本文可分類,且不洩露密鑰 |
| 用量與成本 | 權杖、快取欄位、服務層級與價格政策已釐清 |
| 安全與區域 | 政策、資料路徑與資料落地要求仍符合 |
只要候選路由未通過任何必要範圍,它就不是該工作負載的透明備援。它仍可能在另一套顯式產品政策下使用。
換成不同模型永遠是產品決策。必須定義允許的模型、最低品質、價格上限、工具契約與對使用者的明確揭露,不能只因某條路由報錯就靜默換成較弱或較便宜的模型。
正確理解 Modelflare 的備援語意
Modelflare 會為 API 用戶端指定的模型搜尋合格路徑。一般 API 金鑰有一個主要分組,也可以設定有序備援分組;Smart API Key 則依路由策略評估帳戶可用分組。兩種機制都不應靜默把要求的模型換成另一個模型。
分組層級的 RPM 接納發生在計費與上游請求前。選定分組已滿時,可以評估有序備援分組或智慧路由候選;若沒有合格分組,請求回傳 429。
在分組內,渠道優先順序定義帳戶切換順序。上游錯誤後,失敗渠道會被排除,選擇器繼續尋找其餘合格渠道。現行渠道切換不依賴 RetryTimes 或 AutomaticRetryStatusCodes;成功、路徑耗盡、呼叫端取消,或下游回應已開始而無法透明重播時即停止。
這些是內部的同模型路徑決策,並不代表用戶端可以再加一個無限重試迴圈。分組與渠道設計可參考可靠 AI API 路由;AI API 錯誤排查則可協助區分閘道政策錯誤與上游失敗。
為每次嘗試保留可重建證據
最終 200 不代表第一條路由成功;最終渠道 ID 也無法描述前面的失敗。至少保留:
- 穩定的請求 ID 與呼叫端可見的關聯 ID;
- 嘗試順序與選中的分組或渠道參照;
- 各次嘗試使用的模型與端點契約;
- 失敗狀態、錯誤類別與串流階段;
- 下游輸出是否已開始;
- 時間里程碑與取消狀態;
- 可取得時的輸入、輸出與快取權杖用量;
- 已完成或可計費嘗試的成本歸屬;
- 成功、路徑耗盡、已取消、部分完成或政策停止等最終原因。
不要只為診斷備援就保留 API 金鑰、原始提示詞、原始回應或供應商憑證。一般情況使用去識別的錯誤類別與時間中繼資料即足夠;只有在明確啟用失敗調查時,才使用受限且短期的請求封存。
在正式環境上線前演練政策
以真實協定邊界與安全、可重現的輸入進行預備環境演練:
- 在標頭前讓主要渠道不可用,確認下一條合格的同模型路徑;
- 回傳限流錯誤,確認嘗試上限與
Retry-After行為; - 取消呼叫端,證明不會啟動後續嘗試;
- 在輸出後中斷串流,證明沒有透明重播;
- 送出無效請求,證明備援不會掩蓋錯誤;
- 重複工具流程,證明只記錄一次副作用;
- 耗盡所有路由,確認只有一個清楚的最終錯誤;
- 檢查嘗試帳本,核對用量與成本。
先在小流量工作負載上推出,分開監控嘗試次數、備援後成功率與原始成功率,並保留快速移除不健康路由的能力。目標不是讓備援次數最大化,而是在不改變原模型契約的前提下,於有限截止時間內安全恢復,且每次嘗試都有證據。