スケジューリングの仕組み
このページでは内部メカニズムについて説明します。理解していなくても通常使用は可能ですが、「なぜこの認証情報が使われたのか」を調べる際に非常に役立ちます。
1回のリクエストの完全なパス§
リクエストが受信された後、ゲートウェイは次のことを順に行う：
- 認証 — AccessKeyが有効で、無効化されていないことを確認します。
- プロトコルチェック — AccessKeyが現在のプロトコルを許可していることを確認します。
- グループの絞り込み——アクセスキーで許可されたグループから、要求されたモデルを提供できるものを探します。
- 認証情報を選択 — グループの優先度で層を選び、ルーティング戦略と重みに従って利用可能な認証情報を選択します。
- 転送 — 必要に応じてプロトコルを変換し、アップストリームへ送信します。
- 失敗した場合は再試行 — 成功するかリトライ回数を使い切るまで認証情報を切り替えます。
ルート検査は AccessKey、Group、認証情報が候補になれない理由を示します。その reason_code はクライアント応答の code やリクエストログの error_code とは異なります。最後の節を参照してください。
候補グループ§
候補Groupは同時に以下を満たす必要があります：
- このAccessKeyの認可範囲内にあり
- 有効状態にあります
- リクエストされたモデルが公開されている
- 有効な重みが 0 より大きい
グループの優先度は既定で 0 で、負の値も指定できます。値が大きいほど優先されます。上記の条件を満たし、利用可能な認証情報があるグループのうち、最も優先度の高い層を先に選びます。高い層が利用できない場合は、低い利用可能な層を直接使用します。
利用可能な認証情報§
続いて、これらのグループ内の認証情報を絞り込みます：
- 状態は利用可能（無効化・クールダウン中・ブラックリスト登録ではない）
- サブスクリプションアカウントは認証状態が正常である必要があります
- 有効な重みが 0 より大きい
同じ優先度の層では、まずルーティング戦略で絞り込み、「グループの重み × 認証情報の重み」で重み付きラウンドロビンを行います。ソフトアフィニティによる再利用は、その層で許可された候補に限られます。実際のトラフィックが重みの比率と厳密に一致する保証はありません。
ウェイト§
グループと認証情報の重みはどちらも既定で 50、設定範囲は 1–100 です。同じ層の候補では、値が大きいほど相対的なトラフィック配分が増えます。成功率からの自動計算は行いません。
現在、管理画面と管理 API はどちらも手動の重み 0 を受け付けません。一時的にトラフィックを止める場合は、該当する Group または認証情報を無効にしてください。設定と過去の統計は保持されます。
セッションアフィニティ§
有効にすると、アクセスキー、クライアントプロトコル、リクエスト内の指示または最初のユーザー入力のプレフィックスからソフトアフィニティキーを生成します。同じ安定したプレフィックスを持つ後続リクエストは、現在の優先度とルーティング戦略で許可された候補の中で、以前成功した認証情報を優先して再利用します。
Chat CompletionsとResponsesは、有効なprompt_cache_keyでもソフトアフィニティを利用できます。アフィニティのヒットは上流キャッシュのヒットを保証しません。Responsesの応答IDによる継続は独立した機能です。制限はプロトコルページを参照してください。
アフィニティレコードには TTL と容量上限（デフォルト10,000）があり、古いものから削除されます。親和性は絶対ではありません。記憶した認証情報がクールダウン中またはブラックリスト済みなら、別の利用可能な認証情報を選びます。
設定は実行時設定を参照してください。
失敗後§
別の接続先へのリトライが安全な場合、同じ層の認証情報を使い切る前に、次に低い優先度の利用可能な層へ移ります。低い層がなければ、現在の層の別の認証情報を試します。一度下がると、そのリクエストは高い層に戻りません。グループや層を切り替えても、グローバルのリトライ回数を共有します。
以下は組み込みの既定動作です。カスタム処理については、上流エラールールを参照してください：
- 再試行されます — アップストリームのレート制限、サーバーエラー、ネットワークタイムアウトなど、認証情報を変更すれば解決する問題です。
- 再試行しない——明確なパラメーターエラー、コンテキスト上限、コンテンツポリシーの拒否。認証情報を変えても改善しません。
明確なモデル・機能の拒否では、安全な範囲で候補を切り替えられます。出力済み、または実行結果が不明な場合は無条件に再送しません。応答IDによる継続では別の認証情報を使いません。
ストリーミング応答をクライアントへ確定送信した後は、候補を切り替えられません。空応答の再試行を有効にすると、まだ内容を出力していない先行イベントを一時的に保持する場合があり、上流チャンクの受信とクライアントへの出力は同じではありません。適用範囲と課金上の制限は実行時設定を参照してください。
クールダウンとブラックリスト§
二段階の保護機構で、問題のある認証情報がリクエストを繰り返し遅延させるのを防ぎます：
- クールダウン — エラー後は認証情報を一時的にスキップし、クールダウン終了時に自動復帰します。アップストリームのレート制限では通常の動作です。
- ブラックリスト——連続失敗がしきい値を超えると除外します。APIキーは検証成功後に自動復帰できますが、サブスクリプション認証情報は手動対応が必要です。
モデル単位のレート制限は、その認証情報の該当モデルだけをクールダウンし、他モデルは候補に残ります。認証情報全体の制限は引き続き全体に適用されます。認証情報の復帰操作でモデルのクールダウンも解除されます。
サブスクリプションの利用枠が回復すると、組み込みの利用枠クールダウンを早期に解除できます。利用枠リセットの成功も回復を引き起こします。原因が記録されていない過去のクールダウンは元の期限を維持し、認証情報の明示的な復旧操作で解除できます。
クールダウンは問題が一時的だと想定した一時的な回避です。ブラックリストは、キーの失効や未払いなど、認証情報を無効と判断することを意味します。
1回成功すると連続失敗カウントがリセットされます。一時的な失敗はブラックリスト判定まで累積しません。
しきい値は実行時設定で設定し、現在の状態は監視とトラブルシュートの「健全性」タブで確認します。
ルーティング失敗の原因コード§
ルート検査は AccessKey、Group、認証情報ごとに階層化された reason_code を返します。完全な理由、階層、対処方法はエラーリファレンスに集約します。