AI APIフォールバック戦略：プロバイダー故障マトリクス
故障分類、レスポンス段階、冪等性、Attempt Budgetから、再試行、同一契約Fallback、停止、副作用照合、ルート調査を判断します。
AI APIの再試行、ルートフォールバック、モデル置換は3つの異なるアクションです。再試行は同じ契約でAttemptを繰り返します。ルートフォールバックは、要求されたモデルとプロトコルを別の適格なチャネルまたはグループへ送ります。モデル置換は要求モデルを意図的に変更するため、品質、価格、レイテンシ、ツール動作、Context上限、出力形式が変わる可能性があります。
信頼できるポリシーは、インシデント前に許可するアクションを決めます。判断には、故障の種類、呼び出し元へすでに出力したか、Replayが冪等か、ユーザーのDeadline内に残っているAttempt数を使います。
再試行、フォールバック、モデル置換を分ける
設定、ログ、Runbookで別々の名前を使います。
| アクション | 変わるもの | 適した目的 | 主なリスク |
|---|---|---|---|
| 同一ルート再試行 | 時刻とAttempt Number | 同じルートの短い一時障害から回復 | 不健全な依存先へ負荷を繰り返す |
| 同一契約フォールバック | アップストリームチャネル、アカウント、明示的に順序付けたグループ | 1つの経路が失敗しても要求モデルとプロトコルを維持 | 同等と考えたルート間に隠れた互換性差異がある |
| モデル置換 | モデルIDまたは名前付きモデルポリシー | プロダクトが承認した品質、コスト、可用性のTrade-off | 動作と課金が見えないまま変わる |
3つすべてを「再試行」と呼ばないでください。運用担当者は、リクエストが再実行されたのか、別経路へ移ったのか、別モデルが回答したのかを知る必要があります。モデル置換は、ユーザーに対して明示されたプロダクト契約であるべきで、見えない復旧手段にしてはいけません。
順序付きのモデルまたはプロバイダーステップを提供するGatewayもあります。たとえばCloudflareのフォールバックドキュメントは、どのステップが最終レスポンスに成功したかを公開します。重要なのは特定ベンダーのポリシーをそのまま使うことではなく、ルートが変わったときにAttempt単位の証拠を残すことです。
リクエストをReplayする前に4つのGateを通す
ステータスコードだけでは再試行ポリシーになりません。4つのGateを評価します。
- **故障分類：**一時的、恒久的、呼び出し元起因、不明確のどれか。
- **レスポンス段階：**Header前、有効出力前、出力配信後のどこで発生したか。
- **冪等性：**アプリケーション操作全体を繰り返しても副作用が重複しないか。
- **Attempt Budget：**残り時間が十分で、未使用のAttemptが残っているか。
Google Cloudの再試行戦略も、一般APIについて同じ2つの基礎判断を示しています。レスポンスから再試行が有用かを判断し、冪等性からReplayが安全かを判断します。同ドキュメントは408、429、5xx、Socket Timeout、切断を一般的な一時障害として挙げる一方、非冪等操作にはより強い条件が必要だと説明しています。
AIワークフローの冪等性は、モデルへのHTTPリクエストだけではありません。同じPromptをReplayすると、同じメール、返金、デプロイ、データベース書き込みを再び提案する場合があります。そのため推論自体が読み取り専用でも、Tool Executionには安定した独自のIdempotency Keyと保存済み結果が必要です。
故障マトリクスから始める
次の表は保守的なアプリケーションポリシーです。アプリケーションが最終結果を受け取る前に、Gatewayが内部で同一契約チャネルへフォールバックする場合があるため、2つのレイヤーを重複させずに連携させます。
| 故障または段階 | 同一ルート再試行 | 同一契約フォールバック | 停止または調査 | 理由 |
|---|---|---|---|---|
| クライアント検証エラー、未対応フィールド、不正なリクエスト | いいえ | いいえ | リクエストを修正 | 同じ不正契約のReplayは成功しない |
| Gateway認証、認可、Quota、ポリシー拒否 | いいえ | いいえ | 停止してアカウントまたはポリシーを修正 | 別プロバイダールートでGateway判断を回避してはいけない |
| 出力前のアップストリームCredentialまたはアカウント障害 | 故障ルートでは行わない | 検証済みの適格チャネルがあれば可能 | 故障チャネルを隔離して調査 | 不健全なCredentialを外しながらユーザー契約を維持できる |
レスポンス出力前のネットワーク障害または408 |
冪等なら最大1回の有界Attempt | 可能 | Deadlineで停止 | 一時障害でも、切断後の完了状態が不明確な場合がある |
出力前の429 |
遅延再試行ではRetry-Afterに従う |
別の同一契約ルートに容量があれば可能 | Budget消費後に停止 | 即時の連続再試行はRate Limitを増幅する |
出力前のアップストリーム500、502、503、504 |
Backoff付きの有界再試行 | 可能 | ルート障害が続けば調査 | 通常は一時的だが、すべてのルートが安全という証拠ではない |
| ダウンストリーム出力前のスキーマ不正または壊れたプロバイダーレスポンス | 通常は行わない | 同じスキーマを検証済みのルートだけ | 互換性を隔離または調査 | 同じ非互換実装を繰り返しても改善しにくい |
| モデル拒否または安全ポリシーに沿った完了 | いいえ | いいえ | モデルの結果を返す | 正常な拒否は回避すべきインフラ障害ではない |
呼び出し元キャンセルまたはダウンストリーム499 |
いいえ | いいえ | 即時停止 | 呼び出し元は処理を必要としておらず、再試行は容量とコストを浪費する |
| 可視コンテンツまたはTool Argument配信後のPartial Stream | 透明Replayなし | 透明Fallbackなし | Partialとして記録しアプリケーションが判断 | 2本目のStreamは配信済み出力と重複または矛盾する可能性がある |
| Toolの副作用が完了したか不明 | 照合まで行わない | 照合まで行わない | 冪等記録または下流システムを確認 | 再推論が同じ副作用を提案する可能性がある |
この表はレスポンス段階を意図的に区別しています。ダウンストリーム出力前の503と、テキストを400 Token描画した後の切断は同じ故障ではありません。
開始済みStreamをCommit Boundaryとして扱う
ダウンストリーム出力前なら、Gatewayは失敗したAttemptを破棄し、2つの回答を公開せずに別の適格ルートを試せる場合があります。意味のある最初のByteが呼び出し元へ到達した後は、透明なReplayが危険になります。
再起動したStreamは、次の問題を起こす可能性があります。
- 回答の冒頭を繰り返す。
- 異なる続きを生成する。
- 新しいCall IDで重複した関数呼び出しを行う。
- 明確な境界なしに使用量とコストを変える。
- どのEventがどのAttemptに属するかクライアントが判断できなくなる。
出力開始後にStreamが切れた場合、元のRequest Identityを使い、明示的なPartialまたはTransport Errorを返します。アプリケーションは明示的な「再試行」を表示する、安全なCheckpointから続ける、Partial出力を破棄する、のいずれかを選べます。何も起きなかったように新しいモデルStreamを古いStreamへ連結してはいけません。
Function Callingでは、さらに厳しい境界が必要です。再試行が呼び出しを再作成する前に、受け入れたTool Call Identityと副作用結果を保存します。Function Callingの比較では、Call IDとアプリケーション冪等性の組み合わせを説明しています。
BackoffをAttempt数と総時間で制限する
Exponential Backoffは繰り返しAttemptを時間方向に分散します。Jitterは共有障害後に多数のクライアントが同時再試行することを防ぎます。
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
有効なRetry-AfterがユーザーのDeadline内に収まる場合は従います。Backoff自体は再試行の許可ではありません。故障分類と冪等性のGateを先に通す必要があります。
再試行回数だけではなく、総Budgetを定義します。
- 1つのユーザー操作に対する最大Attempt数。
- QueueとBackoffを含む最大経過時間。
- フォールバックグループ選択前後の最大Attempt数。
- 有用な回答を作るために必要な最小残り時間。
- 呼び出し元からすべてのActive AttemptへのCancellation伝播。
Deadlineが15秒のインタラクティブリクエストに10秒のAttemptを3回設定しても、実行可能なポリシーではありません。後のAttemptはユーザー契約内で完了できません。バッチワークロードは長いBudgetを使えますが、最終Deadlineと永続Job Identityが必要です。
レイヤー間の再試行増幅を防ぐ
SDKが初回リクエストに加えて2回再試行すると、クライアントAttemptは3回です。Gatewayが各クライアントAttemptにPrimaryと2つのChannel Fallbackを実行すると、Gateway Attemptは3回です。さらにアップストリームProxyが各Attemptを1回再試行すると、プロバイダー呼び出しは2回です。
3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls
1つのユーザー操作が18回のプロバイダー呼び出しになります。障害時にはQueue、Rate Limit、コスト、復旧時間をすべて増加させます。
再試行のOwnerを明確に割り当てます。
- Gatewayは即時の同一契約チャネルフォールバックを担当する。
- アプリケーションはユーザー操作全体を繰り返せるか判断する。
- Gatewayがすでに再試行する場合、SDKの自動再試行を無効化または制限する。
- 非同期Jobは1つの永続Job IDとAttempt Ledgerを使う。
- 呼び出し元キャンセル後は、どのレイヤーも新しいAttemptを開始しない。
「このレイヤーのAttempt Number」と、安定したEnd-to-end Request Identityの両方を記録します。そうしないと各レイヤーは2、3回しか試していないように見え、組み合わせによる増幅が隠れます。
フォールバックが本当に契約を維持するか確認する
同じ公開モデル名でも、2つのルートが同じ動作をする証拠にはなりません。同一契約フォールバック集合へチャネルを追加する前に、次をテストします。
| 契約領域 | 必要な証拠 |
|---|---|
| モデルIdentity | 要求モデルが静かなMappingなしで利用できる |
| エンドポイント | 設定どおりResponsesまたはChat Completionsを受け付ける |
| Streaming | Event Type、終了、使用量、Cancellationを処理できる |
| Structured Output | 必要なJSON SchemaサブセットとStrict動作が機能する |
| Function Calling | Tool定義、Call ID、引数Streaming、結果が往復する |
| 制限 | Context、出力、Rate、並列数がワークロードに合う |
| エラー | StatusとError BodyをSecret漏えいなしで分類できる |
| 使用量とコスト | Token計算、Cacheフィールド、Service Tier、価格ポリシーを把握している |
| 安全性と地域 | 必要なポリシー、データ経路、Residency制約を満たす |
候補ルートが必須領域の1つでも失敗する場合、そのワークロードの透明なフォールバックではありません。別の明示的なプロダクトポリシーでは利用できる可能性があります。
別モデルへの変更は常に、そのようなポリシー判断です。許可モデル、品質下限、価格上限、Tool Contract、ユーザー向け説明を定義します。ルートがエラーを返したという理由だけで、安価または弱いモデルを使ってはいけません。
Modelflareの現在のフォールバック動作を理解する
Modelflareは、APIクライアントが要求したモデルに対して適格な経路を検索します。通常のAPI Keyは1つのPrimary Groupと順序付きFallback Groupsを設定できます。Smart API Keyは設定されたRouting Strategyで、アカウントが利用できるグループを評価します。どちらの仕組みも、要求モデルを別モデルへ静かに置換するべきではありません。
Group RPM Admissionは、課金とアップストリームリクエストの前に行われます。選択グループが満杯の場合、順序付きFallback GroupまたはSmart Routing候補を評価できます。適格なグループが残っていなければ、リクエストは429を返します。
選択グループ内では、チャネルPriorityがアカウントフォールバック順を定義します。アップストリームエラー後は失敗チャネルを除外し、残りの適格チャネルを選択します。現在のチャネルフォールバックはRetryTimesとAutomaticRetryStatusCodesから独立しています。成功、適格ルートの枯渇、呼び出し元キャンセル、またはダウンストリームレスポンス開始後で透明Replayできない場合に停止します。
これらは内部の同一モデル経路判断であり、クライアント側に無制限の再試行を追加してよいという意味ではありません。Reliable AI API Routingでグループとチャネルを設計し、AI API Error TroubleshootingでGatewayポリシーエラーとアップストリーム障害を区別します。
すべてのAttemptに証拠を残す
最終的な200は最初のルートが成功した証拠ではありません。最終Channel IDも失敗Attemptを表しません。経路を再構成できるメタデータを保存します。
- 安定したRequest IDと呼び出し元から見えるCorrelation ID。
- Attempt順序と選択Group/Channel参照。
- 各Attemptで使用したモデルとエンドポイント契約。
- 故障Status、Error Class、Stream段階。
- ダウンストリーム出力が開始したか。
- Timing MilestoneとCancellation状態。
- 利用できる場合は入力、出力、Cached Token使用量。
- 完了または課金対象Attemptごとのコスト帰属。
- 最終理由：成功、枯渇、キャンセル、Partial、ポリシー停止。
フォールバック診断のためだけにAPI Key、生のPrompt、生のResponse、プロバイダーCredentialを保存しないでください。通常はRedact済みError ClassとTiming Metadataで十分です。明示的に設定した障害調査だけに、制限された短期間のリクエストアーカイブを使います。
本番トラフィックが依存する前にポリシーを演習する
実際のプロトコル境界と安全で決定的な入力を使い、Staging演習を行います。
- Header前にPrimary Channelを利用不能にし、次の適格な同一モデル経路を確認する。
- Rate Limitを返し、Attempt上限と
Retry-After処理を確認する。 - 呼び出し元をキャンセルし、その後に新しいAttemptが始まらないことを証明する。
- 出力後にStreamを切り、透明Replayされないことを証明する。
- 不正リクエストを送り、フォールバックがエラーを隠さないことを証明する。
- Tool Workflowを繰り返し、副作用が1回だけ記録されることを証明する。
- すべてのルートを枯渇させ、明確な最終エラーが1つ返ることを確認する。
- Attempt Ledgerを確認し、使用量とコストを照合する。
ポリシーを小さなワークロードから展開し、Raw Success Rateとは別にAttempt CountとFallback後成功率を監視し、不健全なルートをすぐ外せるようにします。目標はフォールバック頻度の最大化ではありません。元のモデル契約を安全に維持でき、有界Deadline内で、すべてのAttemptに証拠を残せる場合だけ復旧することです。