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