AI API 備援策略:建立供應商故障矩陣

依故障類別、回應階段、冪等性與嘗試上限,決定何時重試、切換至同契約路由、停止或核對副作用。

AI API 備援策略:建立供應商故障矩陣

AI API 的重試、路由備援與模型替換是三種不同動作。重試是在同一契約下再嘗試一次;路由備援是把相同模型與協定送往另一條合格路徑;模型替換則會改變模型,可能連帶改變品質、價格、延遲、工具行為、上下文限制與輸出格式。

可靠的策略不應在事故發生後才臨時決定。它必須預先回答:這是什麼類型的失敗、回應是否已交付、完整業務操作能否安全重播,以及使用者的截止時間內還容得下幾次嘗試。

分清重試、路由備援與模型替換

在設定、日誌與操作手冊中使用不同名稱。

動作 改變內容 合適用途 主要風險
同一路由重試 時間與嘗試編號 從同一路徑的短暫故障恢復 持續向不健康的依賴增加負載
同契約備援 上游渠道、帳戶或有序分組 某一路徑失敗時維持原模型與協定 名義相同的路徑其實不相容
模型替換 模型 ID 或具名模型政策 經產品核准的品質、成本或可用性取捨 靜默改變行為與計費

不要把三者都寫成「重試」。維運人員必須知道請求是原路重播、換了供應商路徑,還是由另一個模型回答。模型替換也必須是明確的產品契約,不應成為隱藏的救援捷徑。

部分閘道支援有序的供應商或模型步驟。例如 Cloudflare 的備援文件會揭示最後成功的步驟。值得採用的不是某家供應商的固定順序,而是「路徑一旦改變,就保留每次嘗試的證據」這項設計原則。

重播前通過四道檢查

狀態碼本身不是重試政策。每次重播前都要判斷:

  1. 失敗類別:失敗是暫時性、永久性、由呼叫端造成,還是完成狀態不明?
  2. 回應階段:發生在標頭前、有效輸出前,還是輸出已交付後?
  3. 冪等性:完整應用操作能否重做而不產生重複副作用?
  4. 嘗試額度:剩餘實際時間是否足夠,且還有未使用的嘗試次數?

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 金鑰、原始提示詞、原始回應或供應商憑證。一般情況使用去識別的錯誤類別與時間中繼資料即足夠;只有在明確啟用失敗調查時,才使用受限且短期的請求封存。

在正式環境上線前演練政策

以真實協定邊界與安全、可重現的輸入進行預備環境演練:

  1. 在標頭前讓主要渠道不可用,確認下一條合格的同模型路徑;
  2. 回傳限流錯誤,確認嘗試上限與 Retry-After 行為;
  3. 取消呼叫端,證明不會啟動後續嘗試;
  4. 在輸出後中斷串流,證明沒有透明重播;
  5. 送出無效請求,證明備援不會掩蓋錯誤;
  6. 重複工具流程,證明只記錄一次副作用;
  7. 耗盡所有路由,確認只有一個清楚的最終錯誤;
  8. 檢查嘗試帳本,核對用量與成本。

先在小流量工作負載上推出,分開監控嘗試次數、備援後成功率與原始成功率,並保留快速移除不健康路由的能力。目標不是讓備援次數最大化,而是在不改變原模型契約的前提下,於有限截止時間內安全恢復,且每次嘗試都有證據。