AI APIフォールバック戦略:プロバイダー故障マトリクス
故障分類、応答段階、冪等性、試行上限から、再試行、同一契約の代替ルート、停止、副作用の照合、ルート調査を判断します。

AI APIの再試行、ルートフォールバック、モデル置換は3つの異なるアクションです。再試行は同じ契約で試行を繰り返します。ルートフォールバックは、要求されたモデルとプロトコルを別の適格なチャネルまたはグループへ送ります。モデル置換は要求モデルを意図的に変更するため、品質、価格、レイテンシ、ツール動作、コンテキスト上限、出力形式が変わる可能性があります。
信頼できるポリシーは、インシデント前に許可するアクションを決めます。判断には、故障の種類、呼び出し元へすでに出力したか、再実行が冪等か、ユーザーの期限内に残っている試行数を使います。
再試行、フォールバック、モデル置換を分ける
設定、ログ、運用手順書で別々の名前を使います。
| アクション | 変わるもの | 適した目的 | 主なリスク |
|---|---|---|---|
| 同一ルート再試行 | 時刻と試行番号 | 同じルートの短い一時障害から回復 | 不健全な依存先へ負荷を繰り返す |
| 同一契約フォールバック | アップストリームチャネル、アカウント、明示的に順序付けたグループ | 1つの経路が失敗しても要求モデルとプロトコルを維持 | 同等と考えたルート間に隠れた互換性差異がある |
| モデル置換 | モデルIDまたは名前付きモデルポリシー | 製品側が承認した品質、コスト、可用性のトレードオフ | 動作と課金が見えないまま変わる |
3つすべてを「再試行」と呼ばないでください。運用担当者は、リクエストが再実行されたのか、別経路へ移ったのか、別モデルが回答したのかを知る必要があります。モデル置換は、ユーザーに対して明示されたプロダクト契約であるべきで、見えない復旧手段にしてはいけません。
順序付きのモデルまたはプロバイダーステップを提供するゲートウェイもあります。たとえばCloudflareのフォールバックドキュメントは、どのステップが最終レスポンスに成功したかを公開します。重要なのは特定ベンダーのポリシーをそのまま使うことではなく、ルートが変わったときに試行単位の証拠を残すことです。
リクエストを再実行する前に4つの判定条件を通す
ステータスコードだけでは再試行ポリシーになりません。4つの判定条件を評価します。
- **故障分類:**一時的、恒久的、呼び出し元起因、不明確のどれか。
- **レスポンス段階:**応答ヘッダー前、有効出力前、出力配信後のどこで発生したか。
- **冪等性:**アプリケーション操作全体を繰り返しても副作用が重複しないか。
- **試行予算:**残り時間が十分で、未使用の試行回数が残っているか。
Google Cloudの再試行戦略も、一般APIについて同じ2つの基礎判断を示しています。レスポンスから再試行が有用かを判断し、冪等性から再実行が安全かを判断します。同ドキュメントは408、429、5xx、ソケットのタイムアウト、切断を一般的な一時障害として挙げる一方、非冪等操作にはより強い条件が必要だと説明しています。
AIワークフローの冪等性は、モデルへのHTTPリクエストだけではありません。同じプロンプトを再実行すると、同じメール、返金、デプロイ、データベース書き込みを再び提案する場合があります。そのため推論自体が読み取り専用でも、ツール実行には安定した独自の冪等キーと保存済み結果が必要です。
故障マトリクスから始める
次の表は保守的なアプリケーションポリシーです。アプリケーションが最終結果を受け取る前に、ゲートウェイが内部で同一契約チャネルへフォールバックする場合があるため、2つのレイヤーを重複させずに連携させます。
| 故障または段階 | 同一ルート再試行 | 同一契約フォールバック | 停止または調査 | 理由 |
|---|---|---|---|---|
| クライアント検証エラー、未対応フィールド、不正なリクエスト | いいえ | いいえ | リクエストを修正 | 同じ不正契約の再実行は成功しない |
| ゲートウェイ認証、認可、クォータ、ポリシー拒否 | いいえ | いいえ | 停止してアカウントまたはポリシーを修正 | 別プロバイダールートでゲートウェイ判断を回避してはいけない |
| 出力前のアップストリーム認証情報またはアカウント障害 | 故障ルートでは行わない | 検証済みの適格チャネルがあれば可能 | 故障チャネルを隔離して調査 | 不健全な認証情報を外しながらユーザー契約を維持できる |
レスポンス出力前のネットワーク障害または408 |
冪等なら最大1回の有界試行 | 可能 | 期限で停止 | 一時障害でも、切断後の完了状態が不明確な場合がある |
出力前の429 |
遅延再試行ではRetry-Afterに従う |
別の同一契約ルートに容量があれば可能 | 予算消費後に停止 | 即時の連続再試行はレート制限を増幅する |
出力前のアップストリーム500、502、503、504 |
バックオフ付きの有界再試行 | 可能 | ルート障害が続けば調査 | 通常は一時的だが、すべてのルートが安全という証拠ではない |
| ダウンストリーム出力前のスキーマ不正または壊れたプロバイダーレスポンス | 通常は行わない | 同じスキーマを検証済みのルートだけ | 互換性を隔離または調査 | 同じ非互換実装を繰り返しても改善しにくい |
| モデル拒否または安全ポリシーに沿った完了 | いいえ | いいえ | モデルの結果を返す | 正常な拒否は回避すべきインフラ障害ではない |
呼び出し元キャンセルまたはダウンストリーム499 |
いいえ | いいえ | 即時停止 | 呼び出し元は処理を必要としておらず、再試行は容量とコストを浪費する |
| 可視コンテンツまたはツール引数配信後の部分ストリーム | 透明な再実行なし | 透明なフォールバックなし | 部分失敗として記録しアプリケーションが判断 | 2本目のストリームは配信済み出力と重複または矛盾する可能性がある |
| ツールの副作用が完了したか不明 | 照合まで行わない | 照合まで行わない | 冪等記録または下流システムを確認 | 再推論が同じ副作用を提案する可能性がある |
この表はレスポンス段階を意図的に区別しています。ダウンストリーム出力前の503と、テキストを400トークン描画した後の切断は同じ故障ではありません。
開始済みストリームを確定境界として扱う
ダウンストリーム出力前なら、ゲートウェイは失敗した試行を破棄し、2つの回答を公開せずに別の適格ルートを試せる場合があります。意味のある最初のバイトが呼び出し元へ到達した後は、透明な再実行が危険になります。
再起動したストリームは、次の問題を起こす可能性があります。
- 回答の冒頭を繰り返す。
- 異なる続きを生成する。
- 新しい呼び出しIDで重複した関数呼び出しを行う。
- 明確な境界なしに使用量とコストを変える。
- どのイベントがどの試行に属するかクライアントが判断できなくなる。
出力開始後にストリームが切れた場合、元のリクエスト識別子を使い、明示的な部分失敗または転送エラーを返します。アプリケーションは明示的な「再試行」を表示する、安全なチェックポイントから続ける、部分出力を破棄する、のいずれかを選べます。何も起きなかったように新しいモデルストリームを古いストリームへ連結してはいけません。
関数呼び出しでは、さらに厳しい境界が必要です。再試行が呼び出しを再作成する前に、受け入れたツール呼び出し識別子と副作用結果を保存します。関数呼び出しの比較では、呼び出しIDとアプリケーション冪等性の組み合わせを説明しています。
バックオフを試行数と総時間で制限する
指数バックオフは繰り返し試行を時間方向に分散します。ランダムな揺らぎは共有障害後に多数のクライアントが同時再試行することを防ぎます。
delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)
有効なRetry-Afterがユーザーの期限内に収まる場合は従います。バックオフ自体は再試行の許可ではありません。故障分類と冪等性の判定条件を先に通す必要があります。
再試行回数だけではなく、総予算を定義します。
- 1つのユーザー操作に対する最大試行数。
- キューとバックオフを含む最大経過時間。
- フォールバックグループ選択前後の最大試行数。
- 有用な回答を作るために必要な最小残り時間。
- 呼び出し元からすべての実行中試行へのキャンセル伝播。
期限が15秒のインタラクティブリクエストに10秒の試行を3回設定しても、実行可能なポリシーではありません。後の試行はユーザー契約内で完了できません。バッチワークロードは長い予算を使えますが、最終期限と永続的なジョブ識別子が必要です。
レイヤー間の再試行増幅を防ぐ
SDKが初回リクエストに加えて2回再試行すると、クライアントの試行は3回です。ゲートウェイが各クライアント試行に主チャネルと2つのチャネルフォールバックを実行すると、ゲートウェイ試行は3回です。さらにアップストリームプロキシが各試行を1回再試行すると、プロバイダー呼び出しは2回です。
クライアントの3回の試行 × ゲートウェイの3回の試行 × 上流への2回の試行 = プロバイダー呼び出し18回
1つのユーザー操作が18回のプロバイダー呼び出しになります。障害時にはキュー、レート制限、コスト、復旧時間をすべて増加させます。
再試行の責任者を明確に割り当てます。
- ゲートウェイは即時の同一契約チャネルフォールバックを担当する。
- アプリケーションはユーザー操作全体を繰り返せるか判断する。
- ゲートウェイがすでに再試行する場合、SDKの自動再試行を無効化または制限する。
- 非同期ジョブは1つの永続ジョブIDと試行台帳を使う。
- 呼び出し元キャンセル後は、どのレイヤーも新しい試行を開始しない。
「このレイヤーの試行番号」と、安定したエンドツーエンドのリクエスト識別子の両方を記録します。そうしないと各レイヤーは2、3回しか試していないように見え、組み合わせによる増幅が隠れます。
フォールバックが本当に契約を維持するか確認する
同じ公開モデル名でも、2つのルートが同じ動作をする証拠にはなりません。同一契約フォールバック集合へチャネルを追加する前に、次をテストします。
| 契約領域 | 必要な証拠 |
|---|---|
| モデル識別 | 要求モデルが暗黙のマッピングなしで利用できる |
| エンドポイント | 設定どおりResponsesまたはChat Completionsを受け付ける |
| ストリーミング | イベント種別、終了、使用量、キャンセルを処理できる |
| 構造化出力 | 必要なJSON Schemaサブセットと厳格モードが機能する |
| 関数呼び出し | ツール定義、呼び出しID、引数ストリーミング、結果が往復する |
| 制限 | コンテキスト、出力、レート、並列数がワークロードに合う |
| エラー | ステータスとエラー本文を機密情報の漏えいなしで分類できる |
| 使用量とコスト | トークン計算、キャッシュフィールド、サービス階層、価格ポリシーを把握している |
| 安全性と地域 | 必要なポリシー、データ経路、データ所在地の制約を満たす |
候補ルートが必須領域の1つでも失敗する場合、そのワークロードの透明なフォールバックではありません。別の明示的なプロダクトポリシーでは利用できる可能性があります。
別モデルへの変更は常に、そのようなポリシー判断です。許可モデル、品質下限、価格上限、ツール契約、ユーザー向け説明を定義します。ルートがエラーを返したという理由だけで、安価または弱いモデルを使ってはいけません。
Modelflareの現在のフォールバック動作を理解する
Modelflareは、APIクライアントが要求したモデルに対して適格な経路を検索します。通常のAPIキーは1つの主グループと順序付き代替グループを設定できます。Smart API Keyは設定されたルーティング戦略で、アカウントが利用できるグループを評価します。どちらの仕組みも、要求モデルを別モデルへ静かに置換するべきではありません。
グループRPMの受け入れ判定は、課金とアップストリームリクエストの前に行われます。選択グループが満杯の場合、順序付き代替グループまたはSmart Routing候補を評価できます。適格なグループが残っていなければ、リクエストは429を返します。
選択グループ内では、チャネル優先度がアカウントフォールバック順を定義します。アップストリームエラー後は失敗チャネルを除外し、残りの適格チャネルを選択します。現在のチャネルフォールバックはRetryTimesとAutomaticRetryStatusCodesから独立しています。成功、適格ルートの枯渇、呼び出し元キャンセル、またはダウンストリームレスポンス開始後で透明に再実行できない場合に停止します。
これらは内部の同一モデル経路判断であり、クライアント側に無制限の再試行を追加してよいという意味ではありません。信頼できるAI APIルーティングでグループとチャネルを設計し、AI APIエラーのトラブルシューティングでゲートウェイのポリシーエラーとアップストリーム障害を区別します。
すべての試行に証拠を残す
最終的な200は最初のルートが成功した証拠ではありません。最終チャネルIDも失敗試行を表しません。経路を再構成できるメタデータを保存します。
- 安定したリクエストIDと呼び出し元から見える相関ID。
- 試行順序と選択したグループ/チャネル参照。
- 各試行で使用したモデルとエンドポイント契約。
- 故障ステータス、エラー分類、ストリーム段階。
- ダウンストリーム出力が開始したか。
- 計時上の節目とキャンセル状態。
- 利用できる場合は入力、出力、キャッシュ済みトークン使用量。
- 完了または課金対象試行ごとのコスト帰属。
- 最終理由:成功、枯渇、キャンセル、部分失敗、ポリシー停止。
フォールバック診断のためだけにAPIキー、生のプロンプト、生のレスポンス、プロバイダー認証情報を保存しないでください。通常はマスキング済みのエラー分類と計時メタデータで十分です。明示的に設定した障害調査だけに、制限された短期間のリクエストアーカイブを使います。
本番トラフィックが依存する前にポリシーを演習する
実際のプロトコル境界と安全で決定的な入力を使い、ステージング環境で演習を行います。
- ヘッダー前に主チャネルを利用不能にし、次の適格な同一モデル経路を確認する。
- レート制限を返し、試行上限と
Retry-After処理を確認する。 - 呼び出し元をキャンセルし、その後に新しい試行が始まらないことを証明する。
- 出力後にストリームを切り、透明に再実行されないことを証明する。
- 不正リクエストを送り、フォールバックがエラーを隠さないことを証明する。
- ツールのワークフローを繰り返し、副作用が1回だけ記録されることを証明する。
- すべてのルートを枯渇させ、明確な最終エラーが1つ返ることを確認する。
- 試行台帳を確認し、使用量とコストを照合する。
ポリシーを小さなワークロードから展開し、元の成功率とは別に試行回数とフォールバック後成功率を監視し、不健全なルートをすぐ外せるようにします。目標はフォールバック頻度の最大化ではありません。元のモデル契約を安全に維持でき、有界な期限内で、すべての試行に証拠を残せる場合だけ復旧することです。