スケジューリングの仕組み
このページでは内部メカニズムについて説明します。理解していなくても通常使用は可能ですが、「なぜこの認証情報が使われたのか」を調べる際に非常に役立ちます。
1回のリクエストの完全なパス§
リクエストが受信された後、ゲートウェイは次のことを順に行う：
- 認証 — AccessKeyが有効で、無効化されていないことを確認します。
- プロトコルチェック — AccessKeyが現在のプロトコルを許可していることを確認します。
- Groupを選ぶ — AccessKeyに認可されたGroupから、リクエストモデルを公開するものを探します。
- 認証情報を選択 — Groupの認証情報プールから利用可能なものを選びます。
- 転送 — 必要に応じてプロトコルを変換し、アップストリームへ送信します。
- 失敗した場合は再試行 — 成功するかリトライ回数を使い切るまで認証情報を切り替えます。
いずれかの段階で対象を選べない場合、リクエストは原因コードとともに失敗します。原因コードはルートチェックとリクエストログで確認できます。最後の節を参照してください。
まず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回成功すると連続失敗カウントがリセットされます。一時的な失敗はブラックリスト判定まで累積しません。
しきい値は実行時設定で設定し、現在の状態は監視とトラブルシュートの「健全性」タブで確認します。
ルーティング失敗の原因コード§
ルーティングチェックとリクエストログで具体的な原因コードを確認できます。対照表：
| 原因コード | 意味 | 対処方法 |
|---|---|---|
| access_key_disabled | AccessKeyが無効化されている | AccessKeyのページで有効化する |
| access_key_expired | AccessKeyの有効期限が切れています | 新しいキーを作成するか、有効期限を延長する |
| protocol_filtered | このキーではこのプロトコルが選択されていません | キーで対応するプロトコルを追加選択 |
| model_filtered | リクエストされたモデルが許可範囲外である | キーのモデル制限をチェック |
| model_required_by_filter | キーがモデルを制限しているが、リクエストにモデル名がない | リクエストでモデルを明示するか、キーのモデル制限を外してください |
| operation_unsupported | チャネルがそのプロトコルでのこの操作に対応していない | その機能に対応した Group に切り替えてください（プロトコルと変換の境界を参照） |
| native_route_required | リクエストがネイティブルートを要求しているが、この Group は変換でしか提供できない | クライアントと同じプロトコルの Group を使ってください |
| no_route_target | ルーティング可能な宛先が見つかりません | 少なくとも1つのGroupにキーが認可されていることを確認 |
| group_disabled | Groupが無効化されています | このGroupを有効化してください |
| group_filtered | このGroupはこのAccessKeyの認可範囲に含まれていません | キーにそのGroupを追加してください |
| no_available_group | このモデルを提供できるGroupがありません | いずれかのGroupでモデルが公開されていることを確認してください |
| no_credentials | Groupに認証情報がありません | Groupに認証情報を追加してください |
| group_weight_zero | 旧設定の Group の重みが 0 になっている | 自動の重み、または 1～100 の手動の重みに変更する |
| credential_disabled | 認証情報が無効化されています | 有効化するか、別の認証情報を使用してください |
| credential_auth_unavailable | サブスクリプションアカウントの認可が期限切れです | 再認可してください。サブスクリプションアカウントページを参照してください |
| credential_blacklisted | 認証情報がブラックリストに登録されています | 認証情報自体が有効か確認してから復帰させてください |
| credential_cooldown | 認証情報がクールダウン中です | 自動復帰を待つか、認証情報を追加して負荷を分散してください |
| credential_weight_zero | 旧構成に残った認証情報の重み 0 | 自動の重み、または 1～100 の手動の重みに変更する |
| credential_not_allowed | このリクエストではこの認証情報が既に除外されています | 正常な動作です。リトライで直前に失敗したものを再び選ぶことはありません |
| no_available_credential | すべての認証情報が利用できません | 健全性ページを確認してください。多くは一斉のレート制限またはキーの失効です |
原因コードを確認したら、ルーティングチェックで条件を変えて再確認できます。実際のリクエストを送らずに変更の反映を検証できます。