LLM APIゲートウェイのサーキットブレーカーは、すでに失敗しているルートにアプリケーションが繰り返しトラフィックを送るのを防ぎます。このガードレールがないと、タイムアウトが再試行を引き起こし、再試行がフォールバック試行を引き起こし、フォールバック試行がさらなるプロバイダーエラーを引き起こし、アプリは1つの上流インシデントをプロバイダー障害ループへと変えてしまう可能性があります。
目的は、再試行やモデルのフォールバックを置き換えることではありません。目的は、ルートがどれだけ不健全であればゲートウェイがしばらくそのルートへの試行を停止し、後で制御されたプローブを送信し、ブレーカーが開いている間はフォールバック、キューイング、機能低下、またはフェイルクローズのいずれかのより安全な結果を選ぶべきかを判断することです。
Flatkeyが関連するのは、flatkey.aiが製品を1つのAPIキー、https://router.flatkey.ai/v1 のOpenAI互換ベースURL、ルーティング、統合請求、利用分析、ダッシュボード制御、自動切り替え、負荷分散、クォータ制限を中心に公開して位置づけているためです。これらは信頼性向上のための有用な集中ポイントです。しかし、それだけで、独自のアプリケーションワークフローに対する明確な LLM APIゲートウェイのサーキットブレーカー ポリシーを定義する必要がなくなるわけではありません。
LLM API Gateway のサーキットブレーカーが行うべきこと: クイックアンサー
実用的なLLM API gateway circuit breakerには、3つのルート状態と1つの fail-closed パスがあります。ポリシーは、オンコールのエンジニアがインシデント中に説明できる程度にシンプルに保ちましょう。
| 状態 | Gateway の動作 | 何が状態を変えるか | ログに残す証跡 |
|---|---|---|---|
| Closed | トラフィックは、provider、model、endpoint family、account、または route group を利用できます。 | エラー率、タイムアウト率、レイテンシ、過負荷応答、または失敗したヘルスプローブがしきい値を超える。 | Route policy ID、選択された model、provider、endpoint family、latency、status code、retry count、cost。 |
| Open | Gateway は、クールダウン期間中、正常なトラフィックを不健全な route に送るのを停止します。 | クールダウンが期限切れになる、またはオペレーターが手動で probe を許可する。 | Breaker reason、opened-at time、blocked attempt count、fallback route、queue decision、または fail-closed reason。 |
| Half-open | Gateway は、トラフィックを復元する前に、限られた数の probe request を許可します。 | 成功した probe により breaker は閉じ、失敗した probe により再び開く。 | Probe sample size、probe workflow、probe result、latency、usage、route owner approval。 |
| Fail closed | Gateway は、問題が provider-health の問題ではないため、request の route を拒否します。 | Auth、policy、quota、safety、data-boundary、invalid request、または tool side-effect のリスク。 | Stop reason、owner、user-visible message、remediation path。 |
リトライがプロバイダー障害ループを生む理由
リトライは、リクエストが一時的な理由で失敗した場合に有用です。しかし、すべてのユーザーリクエストがさらに複数の上流呼び出しを発生させるようになると危険です。特に、プロバイダーの障害時や過負荷の時間帯ではなおさらです。リトライループは、レート制限を消費し、クォータを使い切り、レイテンシを増加させ、最終的なエラーの背後に本来の失敗を隠してしまう可能性があります。
サーキットブレーカーは、リトライの問いを変えます。「この1回のリクエストをもう一度リトライすべきか？」ではなく、ゲートウェイは「このルートは今、さらにトラフィックを受け取れるほど健全か？」と問いかけます。このルート単位の視点は、LLMワークロードでは重要です。なぜなら、各リクエストは高コストで、長時間実行され、ストリーミングし、ツールを使用し、顧客から見える状態になり得るからです。
Microsoft のサーキットブレーカーに関するクラウド設計パターンは、リモートサービスに対して同じ基本的な考え方を説明しています。失敗が繰り返されると回路が開き、失敗する可能性が高い処理をアプリケーションが継続して試行しないようにします。AIルートでは、同じパターンに LLM 特有の境界が必要です。モデルの挙動、エンドポイントファミリー、トークン消費、ストリーミング状態、ツールの副作用、データクラス、フォールバック承認です。
障害がブレーカーに到達する前に分類する
悪いAI API circuit breakerを作る最も速い方法は、あらゆる失敗をプロバイダーの健全性として数えることです。それでは誤検知が発生します。また、アプリ所有者が修正すべき問題を隠してしまうこともあります。
| エラーまたはイベント | ブレーカーの判断 | 理由 | デフォルトの結果 |
|---|---|---|---|
| Provider 500, 503, overload, unavailable, connection failure, repeated upstream timeout | ルートの健全性にカウントする。 | これらは、プロバイダー、ルート、容量、またはネットワークの健全性を示す妥当なシグナルです。 | 厳しい予算内で再試行し、その後しきい値を超えた場合はルートブレーカーを開く。 |
| 429 request-rate limit | 慎重に分類する。 | プロバイダー全体の過負荷シグナルと、アプリが作成したバーストでは異なる処理が必要です。 | スロットリングする、バックオフする、または実際に飽和しているスコープ付きルートのみを開く。 |
| 429 monthly quota, exhausted credits, or spend limit | プロバイダーの健全性としてカウントしない。 | これは予算またはアカウント所有者の条件です。 | クローズドフェイルにし、予算所有者に通知するか、事前承認済みの予算がある場合のみルーティングする。 |
| 401 auth, incorrect key, organization membership, IP allowlist, unsupported region | プロバイダーの健全性としてカウントしない。 | そのリクエストはそのルートの使用を許可されていません。 | クローズドフェイルにし、資格情報、アカウント、IP、またはリージョンポリシーを修正する。 |
| Invalid request, unsupported parameter, unsupported model, malformed schema | プロバイダーの健全性としてカウントしない。 | アプリが、そのルートでは処理できないリクエスト形状を送信しました。 | ルーティングする前にリクエストを修正するか、互換性のあるモデルを選ぶ。 |
| Safety, moderation, DLP, compliance, or unapproved data-class block | フォールバックで絶対にバイパスしない。 | 別のモデルへルーティングすると、ポリシー境界を越える可能性があります。 | クローズドフェイルにし、ポリシー判断を記録する。 |
| Tool already executed, partial stream already shown, user cancelled request | 黙って再実行しない。 | アプリが重複した副作用を生んだり、2つのモデル出力を混在させたりする可能性があります。 | 未完了としてマークし、明示的なユーザーの再試行を要求するか、冪等な復旧パスを使用する。 |
OpenAIのエラーコードガイドは、この分類体系が重要である理由を示す有用な例です。そこでは、認証とIP許可リストの問題、未対応リージョンの問題、レート制限、クォータ枯渇、サーバーエラー、過負荷、突然のリクエストレート低下が分けられています。AnthropicとGoogle Geminiのドキュメントも、レート制限、過負荷/利用不可の状態、無効なリクエスト、権限またはクォータの問題を同様に区別しています。あなたのLLM API gateway circuit breakerは、ルートを開く前にこれらのクラスを分けておくべきです。
失敗を説明する最小のルートまでブレーカーの範囲を絞る
範囲が広すぎるブレーカーは不要なダウンタイムを招きます。範囲が狭すぎるブレーカーは、同じプロバイダー障害のループを近接するパスにまで許してしまいます。障害を説明できる、最小のルート次元までブレーカーの範囲を絞ってください。
| 範囲 | 使う場面 | 誤った範囲設定をした場合のリスク |
|---|---|---|
| プロバイダー | 同じプロバイダーの複数のモデルが利用できない、または過負荷になっている。 | 1つのモデル、アカウント、またはエンドポイントファミリーだけが失敗している場合には広すぎる。 |
| モデル | 1つのモデルファミリーで、5xx、タイムアウト、または未対応ルートのエラーが繰り返し発生する。 | 上流のアカウントやプロバイダーが飽和している場合には狭すぎる。 |
| エンドポイントファミリー | Chat は動くが、Responses、image、video、Anthropic Messages、または Gemini ルートの挙動が異なる。 | エンドポイントファミリーを混在させると、プロトコル固有の障害を隠してしまうことがある。 |
| アカウント、グループ、リージョン、またはベンダーパス | 上流の特定のアカウント、ルーティンググループ、リージョン、またはベンダーパスだけが失敗している。 | 切り分けに失敗すると、他の健全なキャパシティを消耗してしまう可能性がある。 |
| ワークフロー | ツール呼び出し、ストリーミング、バッチジョブ、または顧客向けチャットでは、安全性や再試行のルールが異なる。 | バッチの拡張には安全でも、ライブのユーザーストリームには危険なルートがある。 |
Flatkey ユーザーにとって、これは実際に使う予定のワークフローとルートからテストすべきだという意味です。この記事に対する現在の Flatkey 価格 API のスナップショットでは、638件のモデル行、23のベンダー、そして OpenAI chat completions、OpenAI Responses、Anthropic messages、Gemini generateContent、image generation、OpenAI video のエンドポイントファミリーが返されました。これは 2026年6月18日時点の古い証拠であり、恒久的なルート契約ではないとみなしてください。
LLM トラフィックに合ったしきい値を設定する
LLM API ゲートウェイのサーキットブレーカーは、1回の孤立した失敗だけで開いてはいけません。また、すべての顧客リクエストが失敗するまで待つべきでもありません。最小トラフィック量、失敗率、レイテンシ、クールダウンを組み合わせたしきい値を使用してください。
| Threshold | Practical Starting Point | Why It Matters |
|---|---|---|
| Minimum sample size | Open only after enough requests or probes have been observed. | Prevents a single expensive completion from opening a global route. |
| Failure ratio | Track retryable upstream failures separately from app-owned failures. | Stops auth, quota, and malformed request errors from poisoning route health. |
| Latency or timeout threshold | Use endpoint-specific timeout budgets for chat, streaming, image, and video paths. | A good threshold for chat may be wrong for video or batch generation. |
| Open cooldown | Hold the route open long enough to stop retry storms, then probe. | Protects both the provider and your own request queue. |
| Half-open probe limit | Allow a small, controlled number of test requests before closing. | Prevents a full traffic surge when a provider is only partially recovered. |
| Cost ceiling | Set a maximum estimated spend for retries, fallback, and probes. | Prevents reliability recovery from becoming a billing incident. |
レート制限もしきい値の議論の一部です。OpenAI のレート制限ガイドでは、レート制限は悪用を防ぎ、公平なアクセスを確保し、集約負荷の管理に役立つと説明しています。アプリがレート制限されたルートに対してリトライを繰り返すと、あなた自身のトラフィックパターンがインシデントになり得ます。LLM API ゲートウェイのサーキットブレーカーは、クライアント側のペーシング、キューイング、クォータ制御と連携して動作し、それらと競合してはいけません。
ブレーカーが開いている間に何が起こるかを決める
ブレーカーを開くことが有用なのは、ゲートウェイに定義済みの次のアクションがある場合だけです。開いたルートがすべて、自動的に利用可能な任意のモデルへフォールバックしないようにしてください。
| オープン状態でのアクション | 使用する場面 | 必要なガードレール |
|---|---|---|
| フォールバックルート | バックアップのモデルまたはプロバイダーが、すでにワークフロー用として承認されている。 | 本番前に、同じ eval、schema、tool、data-boundary、cost のチェックを実行する。 |
| キュー | ジョブが非同期であるか、ユーザー体験が遅延に耐えられる。 | owner、customer、model、cost、retry のメタデータを保持する。 |
| 劣化 | キャッシュ済みレスポンスや機能を縮小した結果など、より低リスクの部分的な結果で許容できる。 | 劣化した状態をアプリとログに表示する。 |
| クローズドで失敗 | リクエストにポリシー、予算、安全性、認証、リージョン、または副作用のリスクがある。 | 別のモデルを試すのではなく、明確なエラーを返し、適切なオーナーに通知する。 |
公開されている Vercel AI Gateway のドキュメントでは、モデルフォールバックを、順序付きのバックアップモデルを持つゲートウェイパターンとして説明しています。これはカテゴリの根拠としてのみ使用してください。自分のスタックでは、フォールバックは別個の承認判断です。ブレーカーはルートが現在正常かどうかを決め、フォールバックは別のルートが同じリクエストを提供してよいかを決めます。
ストリーミングとツール呼び出しには追加の停止が必要
ストリーミングでは、プロバイダーの障害ループを隠しやすくなります。アプリが部分出力の後でリクエストを黙って再開始すると、ユーザーは2回の試行が混ざった回答を見ることがあります。ツール呼び出しには2つ目の問題があります。リトライやフォールバックによって、返金、チケット更新、メール、データベース書き込み、または外部アクションが重複する可能性があります。
LLM APIゲートウェイのサーキットブレーカポリシーでは、次のルールを使用してください:
- 最初の出力の前: ルートが承認され、ブレーカがクローズまたはハーフオープンであれば、リトライまたはフォールバックを許可できます。
- 最初の出力の後: ストリームを不完全としてマークし、黙ってフォールバックする代わりに明示的なユーザー再試行を要求します。
- ツール実行の後: ツールが冪等であり、操作に再生キーがある場合を除き、再実行しないでください。
- ポリシーブロックの後: クローズドで失敗してください。ブロックを回避するために別のモデルへルーティングしないでください。
これは、AI APIリトライ戦略、モデルフォールバックチェックリスト、およびAI APIロードバランシングとフェイルオーバーのガイドと連携します。ブレーカは、それらのプレイブックと同じ障害分類を共有する必要があります。
サーキットブレーカーのレビューに必要な可観測性フィールド
リクエストが成功したのが、ゲートウェイが壊れたルートを静かにスキップしたおかげにすぎない場合でも、そのインシデントは可視化される必要があります。Cloudflare の AI Gateway ドキュメントは、AI ゲートウェイの可観測性パターンの公開例を示しています。リクエストログには、プロバイダー、ステータス、トークン、コスト、所要時間を含めることができ、カスタムメタデータで後から絞り込みできるようにリクエストへタグ付けできます。あなたのゲートウェイログも、ブレーカーの判断に対して同等レベルのルート証跡を提供すべきです。
| フィールド | 運用担当者がそれを必要とする理由 |
|---|---|
| ブレーカーポリシーの ID とバージョン | どのルールがルートを開いた、閉じた、またはバイパスしたのかを示します。 |
| 判断時点でのブレーカー状態 | ルートが closed、open、half-open、または fail-closed だったかを説明します。 |
| 要求されたモデル、選択されたモデル、プロバイダー、アカウント、グループ、エンドポイントファミリー | ユーザーの意図とゲートウェイのルート判断を切り分けます。 |
| 試行ごとのエラークラス | 上流の障害と、認証、クォータ、無効なリクエスト、ポリシー、ツールのエラーを区別します。 |
| レイテンシー、タイムアウト、再試行回数、プローブ結果 | ルートが遅く失敗したのか、素早く失敗したのか、あるいは half-open のプロービング中に回復したのかを示します。 |
| 部分出力フラグとツール副作用ステータス | 隠れた混在出力や重複アクションのインシデントを防ぎます。 |
| 使用量、コスト、クォータ所有者、最終的な処理結果 | 信頼性回復を支出、予算、説明責任に結びつけます。 |
関連するAI API 可観測性ログの記事では、インシデントログについてさらに詳しく説明しています。サーキットブレーカーでは、ルート状態と、リクエストがブロック、プローブ、ルーティング、キューイング、または fail closed になった正確な理由を優先してください。
サーキットブレーカーポリシーのためのFlatkeyロールアウト計画
Flatkeyまたは任意のOpenAI互換ゲートウェイを通じた顧客トラフィックに LLM API gateway circuit breaker を依存する前に、この段階的なアプローチを使用してください。
- ステージングキーを作成する: ブレーカーテストを本番の顧客トラフィックから分離します。
- ベースルートを確認する: OpenAI互換クライアントを
https://router.flatkey.ai/v1に向け、モデル、エンドポイントファミリー、使用状況行、ダッシュボードの表示を確認します。 - ルートカタログをスナップショットする: ルートと価格の前提を監査可能にするため、ロールアウト日当日にFlatkeyの価格ページと価格APIレスポンスを保存します。
- エラー分類を定義する: どのエラーをルートの健全性に含め、どのエラーをブレーカーが検知する前にクローズするかを決定します。
- 1つのワークフローから始める: 拡張する前に、1つのモデルルート、1つのエンドポイントファミリー、1つのトラフィッククラスにブレーカーを適用します。
- 失敗を強制するテストを行う: プロバイダーのタイムアウト、500、503、リクエストレート429、クォータ枯渇、認証失敗、形式不正のリクエスト、部分ストリーム、ツールの副作用をシミュレートします。
- オープン状態の動作を確認する: フォールバック、キュー、劣化、またはフェイルクローズの動作が承認マトリクスと一致することを確認します。
- ログと請求を確認する: 各テスト後に、ブレーカー状態、選択されたルート、使用量、コスト、クォータ所有者が表示されることを確認します。
- ロールバックを設定する: ポリシーが広範囲に開きすぎる、アプリ所有のエラーを隠す、または予期しない支出を発生させる場合は、ポリシーを無効にします。
サーキットブレーカーポリシーテンプレート
このテンプレートは Flatkey API 契約ではありません。エンジニアリング、プロダクト、財務、セキュリティの各責任者向けのレビュー成果物として扱ってください。
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}よくある質問
LLM API ゲートウェイのサーキットブレーカーとは何ですか?
LLM API ゲートウェイのサーキットブレーカーは、繰り返し再試行可能な失敗の後に、正常なトラフィックが不健全なモデル、プロバイダー、アカウント、またはエンドポイントファミリーに到達するのを停止するルート健全性ポリシーです。クールダウン期間中は開放され、限定的なハーフオープンのプローブを許可し、ルートが再び正常に見える場合にのみ閉じます。
どの LLM API エラーでサーキットブレーカーを開くべきですか?
プロバイダー側の 5xx エラー、過負荷、利用不可応答、接続失敗、そして上流のタイムアウトの繰り返しが典型的な候補です。認証エラー、IP 許可リストの失敗、未対応リージョン、クォータ超過、不正なリクエスト、ポリシーブロック、ツールの副作用は、通常、プロバイダー健全性ブレーカーを開く代わりに、クローズドのまま失敗させるべきです。
サーキットブレーカーはリトライやフォールバックとどう違いますか?
リトライは、1 回のリクエストを再試行すべきかどうかを決定します。フォールバックは、別の承認済みルートがそのリクエストを処理できるかどうかを決定します。サーキットブレーカーは、ルートが不健全に見えている間に、そのルートがそもそも通常のトラフィックを受けるべきかどうかを決定します。
サーキットブレーカーはストリーミング LLM 応答にも適用すべきですか?
はい、ただし境界はより厳密にします。ブレーカーは最初の可視トークンの前にルートを保護できます。部分出力やツールの副作用が発生した後は、ワークフローが冪等な復旧向けに明示的に設計されていない限り、アプリは黙って再実行したりフォールバックしたりすべきではありません。
ブレーカーを有効化する前の最終確認
LLM APIゲートウェイのサーキットブレーカーを有効にする前に、1つだけ確認してください。このルートがプロバイダー障害時に開いた場合、チームは何が失敗したのか、なぜ通常トラフィックが停止したのか、トラフィックが次にどこへ行ったのか、それにどれだけのコストがかかったのか、そしてポリシーをどう閉じるかロールバックするかを説明できますか？
答えが「いいえ」なら、ブレーカーはステージングに置いたままにしてください。答えが「はい」なら、レビューのループの一部として、Flatkeyの集中型モデルアクセス、ルーティング、使用状況の可視化、請求、クォータ制御を活用してください。1つのOpenAI互換ゲートウェイの背後にあるルートを検証する準備ができたら、キーを取得して、1つのワークフロー、1つのモデルルート、1つのブレーカーポリシーから始めてください。
