429 と 5xx のレスポンスを指数バックオフで再試行してください。
プロバイダーのランク付け方法を選ぶ
ワークスペースの既定値は、ダッシュボード -> 設定 -> ルーティング、
phaseo settings update --routing-mode <mode>、または PATCH /v1/settings の routing_mode で設定します。1 つのリクエストだけなら、provider.sort または routing.mode を送るか、モデル ID にサフィックスを付けます。
サフィックスは
routing.mode、provider.sort、プリセットとワークスペースのモードより優先されます。許可リスト、リージョン、ガードレール、価格の上限は引き続き適用されます。
ルーティングの設定ページにはベータとアルファのチャンネルの切り替えもあるため、プレビュー版のプロバイダーにトラフィックが送られるのはオプトインした場合だけです。
balanced モードがプロバイダーをランク付けする方法
テキストリクエスト(Chat Completions、Responses、Messages)では、balanced は各プロバイダーの成功した回答あたりのコストを見積もります。
- トークン: モデルの計測済みのプロンプトと出力のサイズ、プロバイダーの計測済みのキャッシュヒット率をもとにした、そのプロバイダーでのこのモデルの一般的なリクエストのコストです。
- 待ち時間: 最初のトークンまでの時間と完全なレスポンスまでの時間を、モデルの一般的な秒あたりの価格でドルに換算したものです。
- 失敗: 合計をプロバイダーの最近の成功率で割り、プロバイダーのエラーに対するペナルティと、レート制限に対するより小さいペナルティを加えます。
リクエスト単位のモデルフォールバック
フォールバックのモデルをmodels に列挙します。Phaseo はまず model を試し、次に各エントリを順に試します。
429、500、502、503、504 で終わった後だけです。Phaseo の予算や無料モデルのクォータによる 429 も、別のモデルなら残りの制限に収まる可能性があるため、次に進みます。提供終了したモデルなど、どのプロバイダーも提供しなくなったモデルも同様です。
次に進まない場合。 400、401、402、403、404、408、413、422 などのクライアントエラーはすぐに返されます。認証や API キーのレート制限など、最初のモデルが実行される前の失敗も同様です。
リストのルール:
modelは必須です。modelsだけを送ると400が返ります。modelsには 1〜25 個のエントリを指定します。重複やmodelと同じものは無視されます。- エントリには、モデル ID、プロバイダー指定の ID、
@supportのようなプリセットを使えます。 - 各試行は、それぞれ独立したリクエストとして検証されます(エンドポイント、パラメーター、ワークスペースのモデル、ガードレール、プリセット、料金、BYOK)。リクエストを処理できないフォールバックはスキップされて記録され、本来返されるはずのエラーを置き換えることはありません。すでに行った試行と同じ試行もスキップされます。
model フィールドには回答したモデルが示され、そのルーティングのトレースには、元のリクエスト ID、フォールバックの順序、それまでの各試行が一覧表示されます。
ストリーミング、動画、音楽。 ストリームがフォールバックするのは最初のバイトの前だけで、それ以降のエラーはストリーム内で届きます。動画と音楽がフォールバックするのは、ジョブの送信中だけです。
他のルーティング設定との組み合わせ。 割り当てられた動的ルートのフォールバックは models より優先され、ルートが選んだ固定のモデルは各試行に引き続き適用されます。プリセットは、それが使われる各試行に独自の制約を適用します。phaseo/auto は独自のフォールバックを管理するため、models と組み合わせることはできません。
マルチパートのエンドポイントは、繰り返しの
models フィールド、models[] フィールド、または 1 つの JSON 配列の文字列を受け付けます。レート制限とエラーも参照してください。
1 つのプロバイダーに固定する
モデル ID の前にプロバイダーを付けると、そのプロバイダーだけを使います。baseten:google/gemma-4-26b-a4b:free のように、サフィックスはモデル ID の一部として残ります。構文とエラーの詳細はプロバイダー指定のモデル ID を参照してください。
使うプロバイダーを制限する
API キーにルーティングルールを割り当てる
動的ルートは、1 つ以上の推論 API キーに割り当てるルールのフローです。次のことができます。- リクエスト本文のフィールド、ヘッダー、カスタムの
metadata、エンドポイント、モデル、セッション ID で分岐する - A/B テストや段階的な展開のために、トラフィックを割合で分割する
- キーごとに日、週、月のリクエスト数やコストに上限を設ける
- モデル、ルーティングモード、プロバイダーの優先設定、フォールバックのモデル(最大 8 個)を切り替える
- キャッシュとセッションを考慮したプロバイダーアフィニティを有効にする
/v1/routing/dynamic-routes API を利用します。
OpenAI 互換のテキストエンドポイントでは、カスタムのメタデータをリクエスト本文に入れます。
会話を 1 つのプロバイダーに留める
テキスト生成では、キャッシュを考慮したルーティングが既定で有効です。prompt_cache_key または session_id を送るリクエストや、cache_control(トップレベル、provider_options.anthropic 内、またはメッセージブロックやツールの cache_control か prompt_cache_breakpoint の印)でキャッシュをオプトインしたリクエストは、最初に成功したリクエストを処理したプロバイダーとルートに固定されます。その他のリクエストは、同じ冒頭のコンテキストについてプロバイダーがキャッシュの読み取りまたは書き込みを報告し、そのプロバイダーのキャッシュされた入力が通常の入力より安い場合に、15 分間固定されます。
1 つのリクエストで無効にするには
provider.cache_aware_routing: false を、キャッシュのアフィニティを保ったままセッションを無視するには routing.session_affinity: false を使います。
ルーティングの判断を説明する
ダッシュボード -> 設定 -> 使用量 -> リクエストログ を開き、リクエストを選択して、プロバイダーの応答 の下にある ルーティングの可観測性 を展開します。次の内容が表示されます。- ランク付けされたすべてのプロバイダーと最終スコア、選択されたものと試行されたもの
- ランク付けの前に除外されたプロバイダーとその理由
- 展開状況やルーティングのステータスによって順位を下げられたプロバイダー
- 各スコアの入力、重み、寄与、倍率
プロバイダーの稼働率に影響するもの
地理的な制限とレート制限は、プロバイダーが停止していることを意味しないため、別に追跡されます。本番環境では、失敗をこれらのトレースと照合できるよう、リクエスト ID、ステータスコード、モデル ID を記録してください。
提供終了したモデル
提供終了したモデルは、いずれかのプロバイダーが提供している間は動作し続けます。その後は、ワークスペースが提供終了モデルのルーティングで代替モデルに送る設定をしていない限り、リクエストは410 model_retired で失敗します。自分の models リストは常に最初に試されます。モデルの非推奨化と提供終了を参照してください。
BYOK に関する考慮事項
では、Phaseo がリクエストをルーティングして記録し、モデルの使用量はプロバイダーが請求します。
各キーは、それを必要とするモデルと API キーに範囲を限定してください。失敗した BYOK リクエストが Phaseo のクレジットで再試行されないようにするには、ダッシュボード -> 設定 -> BYOK でフォールバックを無効にするか、
PATCH /v1/settings で byok_fallback_enabled を管理キーで設定します。キーは同じ画面か、管理キーを使った POST /v1/byok で追加します。