View a markdown version of this page

モデルのルーティングとフォールバック - Amazon Bedrock AgentCore

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

モデルのルーティングとフォールバック

ゲートウェイを介して推論トラフィックをルーティングすると、リクエストされたモデルを提供するターゲットがスロットリング、容量不足、または到達不能になると、リクエストが失敗する可能性があります。モデルフォールバックでは、順序付けられた代替送信先のチェーンを定義し、プライマリが失敗するとゲートウェイは自動的に次の送信先を試行します。フォールバックを使用すると、呼び出し元のクライアントがそれぞれ独自のフォールバックロジックを実装しなくても、可用性が向上し、コストとモデルカバレッジをより細かく制御できます。

ゲートウェイルールでモデルルーティングとフォールバックの両方を設定し、推論ターゲットに適用されます。このトピックはルーティングルールで始まり、それにフォールバックチェーンを追加します。

ターゲットにモデルをルーティングする

フォールバックなしで、モデルを特定のターゲットにルーティングするルールから始めます。routeToTarget ルールを使用して、一致するモデルのゲートウェイのデフォルトのモデルベースのルーティングを上書きします。matchModels 条件は、ルールが適用されるリクエストを指定し、 を使用するrouteToTargetアクションは、一致したリクエストを処理するターゲットstaticRouteを指定します。複数のターゲットが同じモデルに一致する場合、デフォルトのルーティングは任意のターゲットにリクエストを送信できます。ルールはそれを選択したターゲットに固定します。

次の AWS CLI コマンドは、bedrock-mantleターゲットgpt-5.5にルーティングするルールを作成します。

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Route gpt-5.5 to bedrock-mantle" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle" } } } ]'

staticRoute は提供された を固定することもできます。そのためmodel、ターゲットは呼び出し元がリクエストしたモデルとは異なるモデルを提供します。 はリクエストされたモデルの提供modelを省略します。完全matchModelsおよびrouteToTargetリファレンスについては、「ゲートウェイにルールを追加する」を参照してください。

フォールバックチェーンを追加する

そのルートを保護するには、 routeToTarget アクションに fallback ブロックを追加します。ブロックは、代替送信先と送信先を離れるための条件の順序付きリストを宣言します。送信先はターゲットであり、オプションで特定のモデルを使用します。

  • プライマリ – staticRoute (または各weightedRouteレッグ)。オプションで をピン留めするためmodel、提供されるモデルはリクエストされたモデルとは異なる場合があります。 は省略modelして、そのターゲットでリクエストされたモデルを提供します。プライマリ自身の休暇条件は fallbackブロックに配置されます。

  • targetFallback – プライマリが失敗したときに順番に試す 1~2 の代替送信先の順序付きリスト。各エントリは targetNameとオプションの に名前を付けmodel、独自のオプションの休暇条件を保持します。

  • triggerOn – ゲートウェイが送信先を離れ、次の送信先を試行する条件。どちらも一致しないレスポンスは、変更されずに発信者に返されます。

  • firstByteTimeoutMilliseconds – 送信先をあきらめて次の送信先に移動するまで、送信先の最初の応答バイトを待機する時間。これにより、プロバイダーがクリーンエラーを返す代わりに停止すると、フォールバックが機能します。

  • circuitBreaker – このルートのサーキットブレーカーをオンまたはオフにします (ENABLEDデフォルトでは )。サーキットブレーカーは、現在失敗している送信先をスキップして、リクエストが正常な送信先に直接送信されるようにします。詳細については、「回路ブレーカー」を参照してください。

ゲートウェイはチェーンを順番に歩きます。サーキットブレーカーをチェックする送信先ごとに、 は送信先を 1 回試行し、発信者にレスポンスを返すか、トリガーが起動すると次の送信先に進みます。すべての送信先が失敗すると、発信者は最後のエラーを受け取ります。

ストリーミングレスポンスが開始されると、ゲートウェイはフォールバックできなくなります。発信者は部分的なレスポンスとエラーを受け取り、再試行する必要があります。

次の AWS CLI コマンドは、 gpt-5.5にルーティングbedrock-mantleし、フォールバックチェーンを追加するルールを作成します。bedrock-mantle 最初に gpt-5.5を試行します。これが失敗した場合、 gpt-5.5で試行されますopenai。どちらの もリクエストを処理できない場合にのみ、 gpt-5.4で にデグレードしますbedrock-mantle。プライマリは5XX、 429と 、接続エラーまたは 1 バイト目のタイムアウト、ルーティング不可能なターゲット、5 秒の 1 バイト目のタイムアウトにフォールバックします。2 つのフォールバック送信先は、サービスのデフォルトを使用します。

aws bedrock-agentcore-control create-gateway-rule \ --gateway-identifier my-gateway-abc1234567 \ --priority 100 \ --description "Prefer gpt-5.5 on bedrock-mantle, fall back to OpenAI, then degrade to gpt-5.4" \ --conditions '[ { "matchModels": { "anyOf": [ {"value": "gpt-5.5"} ] } } ]' \ --actions '[ { "routeToTarget": { "staticRoute": { "targetName": "bedrock-mantle", "model": "gpt-5.5", "fallback": { "circuitBreaker": {"mode": "ENABLED"}, "triggerOn": { "statusCodes": ["5XX", "429"], "errors": ["CONNECTION_ERROR", "FIRST_BYTE_TIMEOUT", "UNROUTABLE"] }, "firstByteTimeoutMilliseconds": 5000, "targetFallback": [ {"targetName": "openai"}, {"targetName": "bedrock-mantle", "model": "gpt-5.4"} ] } } } } ]'
注記

この例のターゲット名とモデル名は例示です。ゲートウェイで設定されたターゲット名と、ターゲットが提供するモデル IDs を使用します。ルールが参照する推論ターゲットを作成するには、「推論ターゲット」を参照してください。モデルプロバイダーは、時間の経過とともにモデルを廃止または削除することがあります。

フォールバックトリガー

triggerOn オブジェクトは、フォールバックを引き起こす条件を一覧表示します。fallback ブロック (プライマリの場合) と各targetFallbackエントリ (その送信先の場合) に設定できます。これには 2 つのフィールドがあります。

statusCodes

1~10 個の HTTP エラーステータスコードまたはクラスパターン。各値は、4xx および 5xx の範囲、  たとえば NXX、429、 にバインドされた 形式の正確なコード503またはクラスです5XX。フォールバックはエラーレスポンスにのみ適用2xxされ、3xxレスポンスがフォールバック対象になることはありません。

エラー

次の値から 1~3 の接続レベルまたはルーティング条件。

  • CONNECTION_ERROR — ゲートウェイは送信先への接続を確立できませんでした (接続が拒否、リセット、またはタイムアウト)。試行がプロバイダーに到達したことがありません。

  • FIRST_BYTE_TIMEOUT — 送信先は接続を受け入れましたが、 内で最初の応答バイトを返しませんでしたfirstByteTimeoutMilliseconds。

  • UNROUTABLE — ゲートウェイがサービングターゲットにルーティングできませんでした (ターゲットが見つからないか、リクエストの API パスをサポートしていません)。これは決定論的なゲートウェイ側の条件です。チェーンを進めますが、サーキットブレーカーに供給しません。

回路ブレーカー

サーキットブレーカーは現在失敗している送信先をスキップするため、リクエストは失敗した試行を最初に支払うのではなく、正常な送信先に直接送信されます。これにより、停止中のレイテンシーとコストの両方が削減されます。ブレーカーはデフォルトでオンになっています。オフにするには、 circuitBreaker.modeを に設定しますDISABLED 。 たとえば、コストの高いセカンダリにすばやく失敗するのではなく、より安価なプライマリを使用し続けます。ブレーカーをオフにしても、チェーンは宣言した順序で進みます。

ブレーカーは 3 つの状態を自動的に通過します。次の表は、各状態がリクエストにどのように影響するか、および請求される内容を示しています。ゲートウェイが行う各アウトバウンド試行は、1 つのゲートウェイ呼び出しとして請求されます (「オブザーバビリティと請求」を参照)。

ブレーカーの状態 リクエストの処理 料金

クローズ (正常)

ゲートウェイはリクエストをプライマリに送信します。プライマリがフォールバックトリガー (500レスポンスなど) を返した場合、ゲートウェイはチェーン内の次の宛先にフォールバックします。

すべての試行は、フォールバック前に失敗したプライマリ試行を含め、ゲートウェイ呼び出しとして請求されます。

Open (失敗)

ゲートウェイはプライマリをスキップし、リクエストをチェーン内の次の宛先に直接送信するため、リクエストは失敗した試行を回避し、より高速に返します。

ゲートウェイはスキップされたプライマリに課金しません。ゲートウェイが試みる各送信先は、ゲートウェイ呼び出しとして請求されます。

半開き (復旧)

ゲートウェイでは、リクエストのごく一部をプライマリに渡し、復旧したかどうかを確認できます。残りはプライマリをスキップして次の送信先に移動します。を通じて許可されたリクエストが成功すると、ブレーカーは閉じ、すべてのトラフィックがプライマリに戻ります。失敗した場合、ブレーカーは開いたままになります。

プライマリへのリクエストは、その試行のゲートウェイ呼び出しとして請求されます。その他のリクエストは、オープン状態の として請求されます。

加重ルートを使用したフォールバック

プライマリが の場合weightedRoute、各レッグにフォールバックを設定します。各トラフィック分割エントリには独自のオプションfallbackブロックがあり、それweightedRoute自体にはルートレベルのフォールバックはありません。レッグがないと、失敗するとエラーが発信者にfallback返されます。サーキットブレーカーは送信先ごとであり、重みに依存しません。

フォールバックチェーンの検証ルール

  • ルール内のすべての送信先は異なる必要があります。プライマリと各フォールバック送信先は、ターゲットとモデルの異なる組み合わせに名前を付ける必要があります。ゲートウェイは、同じルールを繰り返すルールを拒否します。

  • fallback ブロックには少なくとも 1 つのtargetFallbackエントリがリストされている必要があります。

  • matchModels 条件には少なくとも 1 つのエントリがリストされているvalue必要があり、各エントリを空白にすることはできません。

  • フォールバックは推論ターゲットに適用されます。

オブザーバビリティと請求

ゲートウェイは、配信するルーティングログにフォールバックとルーティングの決定を記録します。これらのログは、実際に各リクエストを処理した送信先を属性し、サーキットブレーカーが送信先をスキップしたタイミングを書き留めるため、ルーティングを確認し、送信先がスキップされている理由を確認できます。

重要

ゲートウェイが行う各アウトバウンド試行は、ゲートウェイ呼び出しとしてカウントされ、ゲートウェイレートで請求されます。したがって、複数の送信先にフォールバックするリクエストは、試行ごとに 1 つのゲートウェイ呼び出しとしてカウントされ、サーキットブレーカーは、すでに失敗している送信先をスキップすることでこのコストを削減します。各試行のモデルと推論コストは、ゲートウェイではなく Amazon Bedrock またはモデルプロバイダーによって個別に請求されます。

呼び出し元のクライアントの観点からは、フォールバックは透過的です。クライアントは 1 つのリクエストを送信し、どの送信先からでも 1 つのレスポンスを受け取ります。ゲートウェイは、使用された送信先の発信者向けインジケータを追加しません。