> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ルーティングとフォールバック

> Gateway がプロバイダーを選択し、リクエストの信頼性を保つ仕組みです。

Phaseo Gateway は、選択したモデルを提供できるプロバイダーへ各リクエストをルーティングします。プロバイダーの応答が遅い場合、レート制限に達した場合、またはエラーを返した場合、Gateway はフォールバックを試し、リクエストの完了を目指します。

## ルーティングモードを選ぶ

本番環境の要件で明らかに優先すべきものがない場合は、`balanced` から始めてください。

| モード | 使用する場面 |
| - | - |
| `balanced` | 価格、レイテンシー、スループット、可用性の実用的なバランスを取りたい場合。 |
| `price` | 応答時間の短縮より、プロバイダーのコスト削減を優先する場合。 |
| `latency` | 応答がすぐに始まることを最優先する場合。 |
| `throughput` | トークン生成速度を持続的に高く保つことを最優先する場合。 |

**ダッシュボード -> 設定 -> ルーティング** でワークスペースの既定値を設定します。ワークフローで、ワークスペースの既定値よりも対象を絞ったプロバイダーまたはモデルのポリシーが必要な場合は、プリセットを使用してください。

### モデルのルーティングサフィックス

リクエストの最適化モードをモデル ID 自体で決めたい場合は、ルーティングサフィックスを追加します。

| サフィックス | ルーティングモード |
| - | - |
| `:nitro` | `throughput` |
| `:cheap` | `price` |
| `:fast` | `latency` |

たとえば `openai/gpt-5-mini:nitro` はスループット優先でルーティングします。認識されたサフィックスは、リクエストの `routing.mode` や `provider.sort`、プリセットおよびワークスペースのルーティングモードより優先されます。プロバイダー許可リスト、リージョン要件、ガードレール、価格上限などの制約は引き続き適用されます。

## ルーティングの概要

* モデル ID を指定してリクエストを送信します。
* Gateway がプロバイダーの稼働状況、レイテンシー、機能の対応状況を評価します。
* プロバイダーが選択され、リクエストが実行されます。

ルーティングのデバッグでは、アクティビティログとレスポンスのメタデータでリクエストの結果を確認してください。

## 自動ルーターでモデルを選択する

自動ルーティングは現在 Alpha 機能で、一部のワークスペースで利用できます。

ワークロードに応じてモデルを変更するには `phaseo/auto` を使用します。Phaseo は、本番利用に適したすべてのテキストモデルから開始し、ワークスペースの制約を適用して、ワークロードに合わせた候補一覧を作成します。

1. **ダッシュボード -> 設定 -> ルーティング -> 自動ルーティング** を開きます。
2. バランスの取れた性能、品質、コスト、レイテンシーのいずれを最適化するかを選びます。
3. 「Economy」「Standard」「Premium」または制限なしの支出プロファイルを選択します。各プロファイルはスコアリング前に、入力と出力の価格に固定上限を適用します。
4. 必要に応じて、`anthropic/*`、`openai/gpt-5.*` などのパターンや完全一致するモデル ID で対象モデルを絞り込みます。
5. 再試行可能なエラーの後、ランキングの次のモデルを Phaseo が試すかどうかを選びます。
6. 設定を保存します。

各リクエストにワークスペースのルーティングポリシーをコピーせずに、アプリケーションからオプトインできます。

```json theme={null}
{
  "model": "phaseo/auto",
  "input": "Review this TypeScript function for correctness."
}
```

リクエストからワークスペースの目的、支出プロファイル、モデルパターンを変更することはできません。固定モデルを指定したリクエストは引き続き自動ルーターを経由しません。

目的に応じて、モデル品質、プロバイダーの信頼性、レイテンシー、価格の相対的な重みが変わります。

| 目的 | 使用する場面 |
| - | - |
| `balanced` | 4 つの指標を総合した実用的な既定値が必要な場合。 |
| `quality` | 関連するベンチマークの性能を最優先する場合。 |
| `cost` | 入力と出力の推定トークン価格の低さを最優先する場合。 |
| `latency` | プロバイダーの最近のレイテンシーの低さを最優先する場合。 |

支出プロファイルは、Standard ティアのテキストトークン 100 万個あたりの価格上限を USD で指定します。

| 支出プロファイル | 入力価格の上限 | 出力価格の上限 |
| - | -: | -: |
| Economy | \$0.10 | \$0.50 |
| Standard | \$0.30 | \$1.50 |
| Premium | \$1 | \$5 |
| 任意の価格 | 上限なし | 上限なし |

カスタム上限では、入力と出力の上限価格を直接指定します。Standard テキスト料金が不明なモデルは、管理対象の候補には含まれません。

各 `phaseo/auto` リクエストで、Phaseo は固定された低コストの分類モデルに通常の Gateway 子リクエストを作成します。子リクエストは同じワークスペースと課金 ID を使用し、リクエストログには個別に表示されます。また、`purpose=auto_routing_classifier` と親リクエスト ID のラベルが付きます。分類モデルは、ワークロードの種類の構成、複雑さのスコア、信頼度を構造化して返しますが、モデルを直接選択することはありません。

ツールや構造化出力などの確定したリクエスト情報は、信頼できるメタデータとして含まれます。分類リクエストが失敗、タイムアウト、または無効なデータを返した場合、Phaseo は生成リクエスト全体を失敗させず、コード、推論、ツール利用、構造化出力、翻訳、要約、一般用途のいずれかを判定するローカルの決定的な分類器にフォールバックします。

分類器の複雑さは、信頼できる許容可能な回答を生成するために必要と考えられる最小限のモデル能力を示します。Phaseo は能力の余裕を加え、ベンチマークとの適合度をワークスペースの目的、価格、レイテンシー、プロバイダーの稼働状況と信頼性に組み合わせて評価します。分類リクエストと選択された生成リクエストは、通常の Gateway パイプラインで個別に課金されます。

スコアリングの前に、許可リスト内のすべてのモデルは、通常のエンドポイント、ワークスペースのモデル、プロバイダー、プライバシー、ガードレール、サーキットブレーカーの各チェックを通過する必要があります。その後、ルーターはプロバイダー自身の申告に依存しないPhaseoカタログの関連ベンチマークと、Phaseoでのプロバイダーの現在の稼働状況、レイテンシー、価格を組み合わせます。ベンチマークまたは運用データが不足している場合は中立として扱われ、許可リストが拡張されることはありません。

レスポンスの `model` フィールドに選択されたモデルが示されます。リクエストの詳細には、ワークロード、目的、選択されたモデル、フォールバックの順序、候補と要素ごとのスコア、ベンチマーク ID、除外項目、アルゴリズムのバージョンが表示されます。ルーティングトレースにプロンプトやレスポンスの内容は含まれません。

ワークスペースでモデルのフォールバックが有効な場合、`429`、`500`、`502`、`503`、`504` ではランキングの次のモデルを再試行します。各フォールバックでポリシーとプロバイダー選択の全工程を再度実行します。クライアントエラーではモデルを切り替えません。

関連付けられた動的ルートで固定モデルが選択されている場合は、そのモデルが優先されます。その際、リクエストの詳細にはオーバーライドが記録され、自動ルーターのモデルフォールバックはそのリクエストで無効になります。

<Warning>
  支出プロファイルとモデルパターンは対象の適格性を制御するもので、品質を保証するものではありません。実際のワークロードで選択されたモデルの組み合わせを検証してください。
</Warning>

## ルーティングの判断理由を確認する

**ダッシュボード -> 設定 -> 使用状況 -> リクエストログ** を開き、リクエストを選択して、**プロバイダーレスポンス** の **ルーティングの可観測性** を展開します。

リクエストログには次の情報が表示されます。

* ランク付けされたすべてのプロバイダーと最終スコア
* Phaseo が選択したプロバイダーと、試行したプロバイダー
* ランク付け前に除外されたプロバイダーとその理由
* ロールアウトまたはルーティングの状態により順位を下げられたプロバイダー
* 各プロバイダーのスコアに使われた入力値、重み、寄与度、倍率

スコア要素と記録されたコンテキストは区別されます。スコア要素は、現在のルーティングモードの最終スコアを変化させます。記録されたコンテキストは判断理由の説明に役立ちますが、必ずしもスコアに影響するとは限りません。

`balanced` ルーティングでは、適格なプロバイダーを信頼性、レイテンシー、テールレイテンシー、スループット、価格、トークン適合度に基づいてスコアリングします。表示される計算では、記録されたすべての指標を同等に扱うのではなく、各要素が最終スコアにどう寄与したかが示されます。

### 信頼性とプロバイダーの稼働率

信頼性サンプルは、スコアに使用する値です。プロバイダーの結果から計算され、成功率は補足情報として表示されます。

次の結果はプロバイダーの稼働率を低下させます。

* 認証の失敗（`401`）
* 支払いの失敗（`402`）
* モデルが見つからない応答（`404`）
* サーバーエラー（`500` 以上）
* レスポンスストリーム開始後のエラー
* HTTP レスポンスは成功したものの、エラー理由で終了したケース

次の結果はプロバイダーの稼働率を低下させません。

* 不正なリクエスト（`400`）
* 地域制限（`403`）
* ペイロードが大きすぎる場合（`413`）
* レート制限（`429`）

地域制限とレート制限は、プロバイダー自体が利用不能であることを示すものではないため、別に記録されます。

### トレースの利用可否とプライバシー

ルーティングの可観測性を有効にした後に行われたリクエストでは、完全なルーティングトレースを利用できます。それ以前のリクエストには一部のトレースしか表示されないか、ルーティングの詳細が表示されないことがあります。

ルーティングトレースには上限があり、内容は含まれません。プロバイダーの選択を説明するための数値や状態は含みますが、プロンプト、メッセージ、生成内容をトレースへコピーすることはありません。

## モデル ID でプロバイダーを指定する

リクエストで特定のプロバイダーとモデルの組み合わせを使用するには、`<provider-id>:<canonical-model-id>` を指定します。

```json theme={null}
{
  "model": "baseten:thinking-machines/inkling-small",
  "input": "Hello"
}
```

修飾子を指定すると、そのリクエストでは他プロバイダーへのフォールバックが無効になります。`baseten:google/gemma-4-26b-a4b:free` などの ID も含め、サフィックスは正規のモデル ID の一部として残ります。

完全な構文、無料ルートの検証、ルーティングの優先順位、エイリアス、エラーコード、リクエスト例については、[プロバイダー修飾モデル ID](./provider-qualified-models.mdx)を参照してください。

## ルーティングとフォールバックを制御する

現在の公開ルーティングおよびフォールバック制御は、意図的に明示されています。

### プリセットでフォールバック候補を絞り込む

**ダッシュボード -> 設定 -> プリセット** では、次を定義できます。

* 許可するモデル
* プロバイダーの許可リスト
* プロバイダーの除外リスト
* プロンプトとパラメーターの既定の動作

これらの制約はプロバイダー選択前に適用されます。プリセットを使って、再試行とフェイルオーバーの対象となるプロバイダーを意図的に絞り込めます。

### ルーティングモードでプロバイダーの順位を変更する

**ダッシュボード -> 設定 -> ルーティング** では、互換性のあるプロバイダーの順位付け方法をワークスペースごとに調整できます。

* `balanced`
* `price`
* `latency`
* `throughput`

同じページにベータおよび Alpha チャンネルの切り替えもあります。追跡できないルーティングの副作用としてプレビュー トラフィックが発生するのではなく、意図して導入できます。

### BYOK のフォールバックを明示する

**ダッシュボード -> 設定 -> BYOK** では、BYOK リクエストが失敗した場合に Phaseo クレジットへフォールバックできるかをチームで選択できます。「自分のキーで失敗した場合もリクエストを完了させるか」という一般的な判断に対する、現在の公開設定です。

### 動的ルートで API キーにポリシーを割り当てる

異なる API キーやリクエストクラスに別々のプロバイダー動作が必要な場合は、**ダッシュボード -> 設定 -> ルーティング** で動的ルートを作成します。ルートでは次のことができます。

* ネストされたリクエスト本文のフィールド、リクエストヘッダー、カスタムメタデータ、エンドポイント、モデル、セッション ID による分岐
* A/B テストや段階的なロールアウトに合わせた割合でのトラフィック分割
* 認証済みキーの使用量バケットに基づく日次、週次、月次のリクエスト数とコストの上限適用
* 別モデルの呼び出しと、そのルーティングモード、プロバイダーの優先設定、フォールバックポリシーの選択
* キャッシュおよびセッションを考慮したプロバイダーアフィニティの有効化
* 1 つ以上の推論 API キーへの関連付け

条件ノードには true と false の出力があります。レートおよび予算ノードには、上限内と超過の出力があります。割合の選択はセッションまたはプロンプトキャッシュキーごとに決定的に行われるため、段階的なロールアウト中に同じキャッシュ済み会話がランダムに別の分岐へ移ることはありません。

保存すると変更できないドラフトバージョンが作成されます。選択したバージョンをデプロイすると、そのスナップショットが Gateway にコピーされ、関連するキーのポリシーキャッシュが無効になります。ロールバック用に以前のバージョンも残ります。プロバイダーの稼働状況に関する運用上の推奨事項は、フローエディターとは別に **Insights** に表示されます。

カスタムメタデータは、OpenAI 互換のテキスト推論インターフェイスで利用できます。

```json theme={null}
{
  "model": "openai/gpt-5-mini",
  "metadata": {
	    "customer_plan": "pro",
	    "workspace": "acme"
  }
}
```

## フォールバックの動作

プロバイダーがエラーやレート制限を返した場合、Gateway は再試行するか、同じモデルをサポートする別のプロバイダーへルーティングできます。`429` および `5xx` のレスポンスには、指数バックオフも引き続き適用してください。

動的ルートのモデルノードには、フォールバックモデルの順序付きリストも設定できます。Phaseo はまず選択されたモデルで適格なプロバイダーへの試行をすべて行います。その結果が再試行可能なレスポンス（`429`、`500`、`502`、`503`、`504`）の場合、Gateway は順番に各フォールバックモデルについてポリシーとプロバイダー選択の全工程を再実行します。クライアントエラーは直ちに返され、モデルは切り替わりません。

各フォールバックは、ワークスペースのモデル制限、ガードレール、プロバイダーポリシー、価格、機能の対応状況を個別に確認されます。1 つのルートに最大 8 個のフォールバックモデルを保存できます。

詳しくは次を参照してください。

* [レート制限](../api-reference/limits.mdx)
* [エラー処理](../api-reference/errors.mdx)

## キャッシュおよびセッションを考慮したアフィニティ

テキスト生成エンドポイントでは、キャッシュを考慮したルーティングが既定で有効です。プロバイダーからプロンプトキャッシュの実際の読み取りが報告されると、アクティブなルート、プリセット、ガードレール、リクエストポリシーで許可され、プロバイダーの稼働状態に問題がない限り、一致するコンテキストを 15 分間そのプロバイダーに固定します。

`session_id` がある場合、キャッシュアフィニティは最初のコンテキストだけでなくセッションに紐付きます。Phaseo は次のキャッシュ読み取りを検知するとアフィニティを更新し、セッションのアクティビティが続く間は最大 24 時間保持します。サーキットブレーカーとポリシーフィルターは常にアフィニティより優先されます。

ワークスペースや動的ルートの既定値を変更せずに、1 件のリクエストだけ無効にできます。

```json theme={null}
{
  "model": "openai/gpt-5",
  "session_id": "support-session-42",
  "provider": {
    "cache_aware_routing": false
  }
}
```

コンテキストのキャッシュアフィニティを維持しつつ、1 件のリクエストでセッション ID を無視するには、次を使用します。

```json theme={null}
{
  "model": "openai/gpt-5",
  "session_id": "support-session-42",
  "routing": {
    "session_affinity": false
  }
}
```

## BYOK に関する注意点

Phaseo のルーティングと可観測性を利用しながら、選択されたプロバイダーによるモデル利用料を自分のアカウントに請求させる場合は BYOK を使用します。

* UTC の各月で完了した最初の 250,000 件の BYOK リクエストには、Phaseo のサービス料がかかりません。
* その無料枠を超えると、Phaseo はプロバイダー相当額の 2.5% を請求します。
* Phaseo クレジットを最低 1 ドル分維持してください。管理フォールバックと無料枠超過後の手数料の徴収に使われます。プロバイダー料金は引き続きプロバイダーのアカウントへ直接請求されます。
* プロバイダーのクォータ、データポリシー、モデルへのアクセス、アカウント制限は引き続き適用されます。

プロバイダーの認証情報は保存前に AES-256-GCM で暗号化され、ワークスペースとプロバイダーに紐付けられます。各キーの使用範囲を、必要とするモデルと Phaseo API キーに限定してください。リクエストで Phaseo クレジットを絶対に使わない場合は、管理フォールバックを無効にします。

## ログに記録する情報

本番ワークロードでは、デバッグ時に障害を関連付けてルーティングの動作を確認できるよう、リクエスト ID、レスポンスのステータスコード、モデル ID を記録します。

## 関連ガイド

* [プリセット](./presets.mdx)
* [機能パリティマトリクス](../migration-guides/feature-parity-matrix.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.