フォールバック

フォールバック：最初に選んだモデルが応答できない場合に、別のモデルを順に試す仕組みです。 APIキーまたはルールに候補を設定すると、ロリポップ！AIゲートウェイが同じリクエストを次の候補へ送ります。

候補と順序を設定する

ダッシュボードからAPIキーまたはルールのモデル設定を開き、フォールバックモデルを試す順に選びます。リクエストの model に個別のモデルIDを指定した場合は、そのモデルを最初に試し、設定したフォールバックモデルを続けます。

model: "auto" を指定した場合は、自動選択の候補が評価対象になります。フォールバックモデルの一覧は自動選択候補へ追加されないため、auto で試したいモデルは自動選択の候補にも含めてください。

設定後も、クライアントから送るリクエストは通常と同じです。

Shell


curl -i "$AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<最初に試すモデルID>",
    "messages": [
      { "role": "user", "content": "こんにちは。" }
    ]
  }'

リクエストボディに fallbacks や num_retries を指定することはできません。

次の候補を試す条件

モデルへの接続失敗、タイムアウト、またはモデル側のエラーが発生した場合は、設定に従って次の候補を試します。一方、APIキーの認証、組織やプロジェクトの状態、モデルの許可、予算、本サービスで判定したレート制限、ガードレールで拒否されたリクエストは、モデルを変えても条件が変わらないためフォールバックしません。

候補をすべて試しても応答できない場合は、エラーを返します。同じエラーを受け取ってアプリケーション側でも再実行する場合は、待ち時間と試行回数を設けてください。

応答したモデルを確認する

フォールバック後のレスポンスでは、model に実際に応答したモデルの公開名が入ります。次のヘッダーでも結果を確認できます。

ヘッダー	内容
`X-AIGateway-Requested-Model`	リクエストの `model` に指定した値
`X-AIGateway-Served-Model`	実際に応答したモデル
`X-AIGateway-Fallback-Count`	最初の候補から切り替えた回数

たとえば、2番目の候補が応答した場合は次のようになります。

HTTP


X-AIGateway-Requested-Model: <最初に指定したモデルID>
X-AIGateway-Served-Model: <実際に応答したモデルID>
X-AIGateway-Fallback-Count: 1

使用状況では、フォールバックが発生したリクエスト数を確認できます。

キャッシュとツールを使う場合

フォールバック候補は、同じリクエストのフィールドを受け取ります。プロンプトキャッシュ、ツール、画像などモデルごとに対応状況が異なる機能を使う場合は、すべての候補がそのリクエストを扱えることを確認してください。