Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

モデルルーティングを構成する

このページでは、OpenAPI 3.x 仕様を使用して API Gateway でモデルルーティングを構成、デプロイ、テストする方法について説明します。

始める前に

モデルルーティングを構成する前に、環境が次の前提条件を満たしていることを確認してください。

IAM 権限を確認する: API Gateway 管理プレーンと Gemini Enterprise Agent Platform Model Garden にアクセスできることを確認します。API 構成とゲートウェイを作成するには、API Gateway 管理者（roles/apigateway.admin）ロールが必要です。また、ゲートウェイで使用するサービスアカウント（デフォルトの Compute Engine サービスアカウント、または API 構成の作成時に指定したユーザー管理のサービスアカウント）には、ターゲットモデルにアクセスするための Agent Platform ユーザー（roles/aiplatform.user）ロールが付与されている必要があります。
モデルの可用性とエンドポイントアクセスを確認する: ルーティング可能なモデルが、Agent Platform Model Garden の Model as a Service（MaaS）用の事前デプロイされたオープンモデルであることを確認します。単一のルーターで参照されるすべてのモデルは、まったく同じホスト名を共有する必要があります。そのルーター内で参照されるすべてのモデルに対して、グローバルエンドポイント（aiplatform.googleapis.com）または単一のリージョンエンドポイント（us-central1-aiplatform.googleapis.com など）を選択します。
ゲートウェイのデプロイの適格性を確認する: モデルルーティングなしでデプロイされた既存のゲートウェイを更新してモデルルーティングを有効にすることはできません。また、モデルルーティングでデプロイされたゲートウェイを更新してモデルルーティングを無効にしたり削除したりすることもできません。ルーティングモードを切り替えるには、新しい API 構成とゲートウェイインスタンスを作成してデプロイする必要があります。
VPC Service Controls とエンドポイントの互換性を確認する: モデルルーティングゲートウェイは、VPC Service Controls または Private Service Connect（PSC）のエンドポイント構成をサポートしていません。ターゲットプロジェクトと API Gateway インスタンスが VPC Service Controls の境界によって制限されていないこと、モデルがパブリックリージョンまたはグローバルエンドポイントを使用していることを確認します。

構成の検証

API 構成をデプロイすると、API Gateway 管理プレーンが OpenAPI 仕様を検証します。管理プレーンは、デプロイ中に無効な構成を情報検証エラーで拒否します。検証プロセスでは、次のルールが適用されます。

構造とロケーションの確認

x-google-api-management 拡張機能とそれに関連付けられたブロック（backends、ai.models.routing.routers、個々のルーター、rules）は、整形式である必要があります。キーは、想定されるデータ型（マップ、リスト、文字列）と一致する必要があります。管理プレーンは、型の不一致を expected map/list/string エラーで拒否します。
モデルルーティングが有効になっている場合、x-google-api-management 拡張機能には有効な backends ブロックが含まれている必要があります。
x-google-model-router 拡張機能は、OpenAPI 3.x 仕様でのみサポートされています（OpenAPI 2.0 / Swagger ではサポートされていません）。
x-google-model-router 拡張機能は、オペレーションレベルでのみ指定できます。管理プレーンは、パスレベルまたはルート（最上位）レベルに配置された x-google-model-router 定義を明示的に拒否します。
オペレーションが x-google-model-router を参照する場合は常に、ai.models.routing.routers ブロックを x-google-api-management 内で定義する必要があります。
同じ API オペレーションに x-google-model-router と x-google-backend の両方を指定することはできません。
OpenAPI 仕様に、モデルルーティングオペレーションとモデルルーティング以外のオペレーションを混在させることはできません。同じ API 仕様内の他のオペレーションで x-google-model-router を使用しながら、一部のオペレーションで標準のルーティング拡張機能（x-google-backend など）を指定することはできません。

HTTP メソッドの確認

x-google-model-router 拡張機能は、POST HTTP メソッドを使用するオペレーションにのみ適用できます。管理プレーンは、他の HTTP メソッド（GET、PUT、DELETE など）でのモデルルーティングを拒否します。

バックエンドの有効性

x-google-api-management.backends で定義されたすべてのバックエンドに、空でない address フィールドを含める必要があります。
バックエンド address は、http または https スキームを使用する有効な URL である必要があります。パブリックエンドポイントまたはリモートエンドポイントを介して転送されるプロンプトペイロードと認証情報を保護するには、address フィールドを定義するときに常に https スキームを指定します。
x-google-api-management.backends で定義され、モデルルーターによって参照されるすべてのバックエンドで、pathTranslation: CONSTANT_ADDRESS を使用する必要があります。モデルルーティングバックエンドで pathTranslation: APPEND_PATH_TO_ADDRESS を使用する構成は、モデルルーターのランタイムパスでパス変換が無視されるため、管理プレーンによって拒否されます。
モデルルーティングバックエンドは、VPC Service Controls または Private Service Connect（PSC）のエンドポイント構成をサポートしていません。すべてのバックエンド address フィールドは、パブリックリージョンまたはグローバル MaaS オープンモデルエンドポイントを指している必要があります。

注意: 構成の検証ではドメインの許可リストが適用されないため、すべてのバックエンド address フィールドが信頼できる Agent Platform エンドポイント（aiplatform.googleapis.com など）のみを指していることを確認してください。

ルーター参照の解決

オペレーションの x-google-model-router で参照されるルーター名は、ai.models.routing.routers で定義された有効なルーターキーと一致する必要があります。
ルーターの defaultModel で参照される backend は、x-google-api-management.backends で定義された有効なバックエンドと一致する必要があります。
ルーター内の各ルールで参照される backend は、x-google-api-management.backends で定義された有効なバックエンドと一致する必要があります。

ルーターの内容

各ルーターで defaultModel を定義する必要があります。
defaultModel には有効な backend フィールドを含める必要があります。
defaultModel には、空でない targetModel フィールドを含める必要があります。
rules の各エントリには、空でない model フィールドを含める必要があります。文字列値 default は予約済みであり、ルールの model 値として使用できません。
rules の各エントリには、空でない targetModel フィールドを含める必要があります。
単一のルーター内のすべてのルールで定義された model 値は一意である必要があります。管理プレーンは、同じルーター内の重複する model 値を拒否します。

バックエンドのホストとスキームの一貫性

単一のルーターで参照されるすべてのバックエンド（defaultModel.backend とすべてのルールの backend を含む）は、同一のホスト名と URL スキームを共有する必要があります。管理プレーンは、同じルーター内で異なるホスト名または一貫性のないスキーム（http と https）を使用する構成を拒否し、ルーターがすべてのリクエストを一貫したアップストリームサービスエンドポイントにディスパッチするようにします。

ターゲットモデルの検証

targetModel 文字列（google、openai、anthropic）の <provider> 部分と <provider>/<model> 識別子形式は、構成の作成（デプロイ）時に検証されます。管理プレーンは、targetModel としてフォーマットされていない、またはプロバイダが google、openai、anthropic ではない <provider>/<model> を、デプロイ時に InvalidArgument: unsupported publisher エラーで拒否します。

ステップ 1: ターゲットモデルを特定する

ターゲットの基盤モデルと、対応する Agent Platform エンドポイント URL を特定します。ルーター内のルーティング可能なすべてのモデルは、単一のホスト名を共有する必要があります（MaaS オープンモデルの場合、このホスト名は aiplatform.googleapis.com です）。

エンドポイント URL パスは、モデルプロバイダによって異なります。

Google Gemini: :generateContent メソッドを使用します。
Anthropic Claude: :rawPredict メソッドを使用します。
OpenAI: /endpoints/openapi/chat/completions エンドポイントパスを使用します。

次の表に、このセクションの後半の OpenAPI 仕様の例で使用されている MaaS エンドポイントを示します。

モデル	エンドポイント URL
`google/gemini-3.5-flash-lite`	`https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent`
`anthropic/claude-opus-4-7`	`https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/publishers/anthropic/models/claude-opus-4-7:rawPredict`
`openai/gpt-oss-120b-maas`	`https://aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/endpoints/openapi/chat/completions`

YOUR_PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

ステップ 2: OpenAPI 3.x 仕様を構成する

OpenAPI 3.x 仕様を作成または更新して、バックエンドエンドポイントとモデルルーティング構成を定義します。

次の例は、2 つの異なるモデルルーターを定義する OpenAPI 3.0.3 仕様を示しています。水平スクロールを防ぐため、長いバックエンドアドレス URL では YAML の二重引用符付き複数行文字列の継続（``）を使用します。

openapi: 3.0.3

info:
  title: OpenAPI 3.x spec using Model Routing
  description: Using Model Routing in an OAS 3.x spec
  version: 1.0.0

x-google-api-management:
  backends:
    gemini-35-flashlite:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/google/\
        models/gemini-3.5-flash-lite:generateContent"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    anthropic-claude-opus-47:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/publishers/anthropic/\
        models/claude-opus-4-7:rawPredict"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

    openai-gpt-oss-120b:
      address: "https://aiplatform.googleapis.com/v1/projects/\
        YOUR_PROJECT_ID/locations/global/endpoints/openapi/\
        chat/completions"
      deadline: 60.0
      pathTranslation: CONSTANT_ADDRESS

  ai:
    models:
      routing:
        routers:
          # Router 1: route between Gemini (default) and Claude.
          gemini-claude-router:
            defaultModel:
              backend: gemini-35-flashlite
              targetModel: google/gemini-3.5-flash-lite
            rules:
              - model: "claude-opus-4-7"
                backend: anthropic-claude-opus-47
                targetModel: anthropic/claude-opus-4-7

          # Router 2: route between OpenAI GPT (default) and Gemini.
          openai-gemini-router:
            defaultModel:
              backend: openai-gpt-oss-120b
              targetModel: openai/gpt-oss-120b-maas
            rules:
              - model: "gemini-3.5-flash-lite"
                backend: gemini-35-flashlite
                targetModel: google/gemini-3.5-flash-lite

servers:
  - url: "https://my-gateway-url.com"

paths:
  /v1/chat/gemini-claude:
    post:
      summary: "Endpoint:defaults to Gemini & Claude as an option."
      operationId: "chatGeminiClaude"
      x-google-model-router: gemini-claude-router
      responses:
        '200':
          description: "OK"

  /v1/chat/openai-gemini:
    post:
      summary: "Endpoint:defaults to OpenAI & Gemini as an option."
      operationId: "chatOpenAIGemini"
      x-google-model-router: openai-gemini-router
      responses:
        '200':
          description: "OK"

構成プロパティ

backends: x-google-api-management の backends オブジェクトは、ルーティング可能なすべてのモデルエンドポイントを定義します。各バックエンド名は、宛先 address を含むシンボリックモデル名（gemini-35-flashlite など）を表します。backends フィールドは、既存の Google OpenAPI 拡張機能です。
ai.models.routing: モデルルーティング構成は、x-google-api-management の ai.models.routing にあり、名前付きルーターのマップが含まれています。各マップエントリは 1 つのモデルルーターを定義します。キーはルーターの名前（gemini-claude-router など）を表し、値には次のものが含まれます。
- defaultModel: 受信リクエストペイロードが明示的なルールと一致しない場合に使用される、必須のフォールバックモデルの宛先。ルールエントリとまったく同じ構造ですが、model 一致フィールドは省略されています。OpenAI 互換のルートの場合、リクエストが defaultModel にフォールバックすると、targetModel の値は、Agent Platform に送信されるリクエスト本文の送信 model 属性として転送されます。
- rules: 各要素がクライアントペイロードモデル文字列を宛先バックエンドとターゲットモデルにマッピングする、省略可能な配列。
ルールのプロパ 1 ティ: rules（および defaultModel）内の各エントリは、次のプロパティを定義します:
- model （ルールのみ）: クライアントの受信 JSON プロンプトペイロード内の model 属性と照合される文字列値。ルーターは、受信ペイロードの model 値をこの文字列と比較します。一致するルールがない場合、ルーターは defaultModel を選択します。OpenAI 互換のルート（宛先バックエンドが /openapi/chat/completions の場合）では、この文字列は、Agent Platform に送信されるリクエスト本文の送信 model 属性として直接転送されます。したがって、OpenAI 互換のルートの場合、model セレクタ自体が有効なパブリッシャーモデル識別子（たとえば、openai/gpt-oss-120b-maas）である必要があります。gpt-oss などのエイリアスを使用すると、Agent Platform から 400 Malformed publisher model エラーが返されます。
- backend: ゲートウェイがプロンプトを送信する x-google-api-management.backends で定義されたシンボリックバックエンド名。
- targetModel: <provider>/<model-id> としてフォーマットされたターゲットモデル識別子。モデルルーターは、この文字列を使用して、宛先モデルのリクエストとレスポンスを変換します。<provider> 接頭辞は、google、openai、anthropic と完全に一致する必要があります。<model-id> は、有効な Agent Platform Model Garden パブリッシャーモデル識別子である必要があります。ゲートウェイは、クライアントに返されるレスポンスの model フィールド内でこの文字列をエコーバックします。値の例:
  - google/gemini-3.5-flash-lite
  - google/gemini-2.5-pro
  - openai/gpt-oss-120b-maas
  - anthropic/claude-opus-4-7
x-google-model-router: モデルルーターを API オペレーションパスに接続するには、x-google-model-router 属性を使用してルーター名を指定します。前の例では、/v1/chat/gemini-claude に送信された POST リクエストは gemini-claude-router を呼び出し、JSON ペイロードで指定されたモデル名に基づいてプロンプトをルーティングします。

ステップ 3: API 構成を作成してデプロイする

作成した OpenAPI 3.x 仕様を使用して API 構成を作成し、ゲートウェイに API をデプロイするの説明に従って、API Gateway インスタンスに構成をデプロイします。

API Gateway 管理プレーンは、モデルルーティング構成を処理し、ルーティングレイヤを有効にします。ゲートウェイのデプロイが完了すると、ゲートウェイは OpenAI 互換の JSON ペイロードとしてフォーマットされたプロンプトリクエストを受信する準備が整います。

ステップ 4: ルーティング動作をテストする

ゲートウェイをテストする前に、ゲートウェイが ACTIVE 状態になるまで待ってから、その URL を取得します。

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GATEWAY_LOCATION \
  --project=PROJECT_ID \
  --format='value(defaultHostname)'

モデルルーティングの公開プレビューの開始時、モデルルーティングゲートウェイは run.app ホスト名を使用していました。2026 年 9 月 3 日以降、新しいモデルルーティングゲートウェイでは、gateway.dev 形式の https://GATEWAY_ID-PROJECT_NUMBER.REGION.gateway.dev デフォルトホスト名（https://my-gateway-123456789012.us-central1.gateway.dev など）を使用する場合があります。デフォルトのホスト名は不変で、作成時に割り当てられます。run.app ホスト名と gateway.dev ホスト名のどちらの形式が割り当てられても、ゲートウェイはその形式を永続的に保持します。

curl を使用して OpenAI 互換のプロンプトリクエストをゲートウェイ URL（https://GATEWAY_URL）に送信し、ゲートウェイのルーティング動作をテストします。次の例では、$TOKEN は、認証方法の選択で説明されているいずれかの方法で取得した有効な認証トークンを表します。

明示的なルールルーティングをテストする

Claude モデル anthropic/claude-opus-4-7 をリクエストするプロンプトを送信します。

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain the concept of recursion in one sentence."
      }
    ]
  }'

リクエストを /v1/chat/gemini-claude に送信すると、gemini-claude-router が呼び出されます。JSON ペイロード内の属性 "model": "claude-opus-4-7" は gemini-claude-router の明示的なルールと一致し、ゲートウェイにリクエストを anthropic-claude-opus-47 バックエンドにルーティングするように指示します。

デフォルトモデルのフォールバックをテストする

一致しないモデル名を指定してプロンプトを送信し、フォールバックルーティングをテストします。

curl https://GATEWAY_URL/v1/chat/gemini-claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "unrecognized-model",
    "messages": [
      {
        "role": "user",
        "content": "Write a short poem about the ocean."
      }
    ],
    "stream": true
  }'

リクエストを /v1/chat/gemini-claude に送信すると、gemini-claude-router が呼び出されます。属性 "model": "unrecognized-model" は明示的なルールと一致しないため、ゲートウェイはリクエストをルーターの構成済み defaultModel（gemini-35-flashlite バックエンド）にディスパッチします。

代替ルーターパスをテストする

セカンダリルーターエンドポイントを介して Gemini をリクエストするプロンプトを送信します。

curl https://GATEWAY_URL/v1/chat/openai-gemini \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {
        "role": "user",
        "content": "List the three largest cities in the world."
      }
    ]
  }'

リクエストを /v1/chat/openai-gemini に送信すると、openai-gemini-router が呼び出されます。属性 "model": "gemini-3.5-flash-lite" はそのルーターの明示的なルールと一致し、ゲートウェイにリクエストを gemini-35-flashlite バックエンドにルーティングするように指示します。単一のバックエンドは複数のルーターから参照できます。この構成では、gemini-35-flashlite は openai-gemini-router の明示的なルールターゲットとして、gemini-claude-router の代替 defaultModel として機能します。

オブザーバビリティ

モデルルーターは、ゲートウェイがトラフィックを処理していることを確認し、Cloud Logging を使用してリクエストごとのメタデータを検査し、Cloud Monitoring を使用して障害を診断できるようにインストルメント化されています。

Cloud Logging

ゲートウェイを介してルーティングされるすべてのリクエストは、 Google Cloud プロジェクトの次の場所にある標準の API Gateway リクエストログにエントリを生成します。

projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests

各ログエントリには次のフィールドが含まれています。

httpRequest.requestUrl、httpRequest.status、httpRequest.latency
api、apiConfig、apiMethod
backendRequest.hostname: リクエストがプロキシされた Agent Platform バックエンドのホスト名。
responseDetails: モデルルーターの障害時にブランド化されたエラーカテゴリが入力されます（モデルルーターの障害のトラブルシューティングを参照）。

特定のゲートウェイに送信された最近のリクエストを見つけるには、次の Cloud Logging クエリフィルタを使用します。

(resource.type="apigateway.googleapis.com/Gateway" OR resource.type="api")
logName="projects/YOUR_PROJECT_ID/logs/apigateway.googleapis.com%2Frequests"

注: 公開プレビュー版では、特定のリクエストを処理した特定のターゲットモデルのリクエストごとの属性は使用できません。単一のルーターで参照されるすべてのバックエンドは同一のホスト名（aiplatform.googleapis.com など）を共有するため、backendRequest.hostname フィールドだけでは選択したモデルを識別できません。回避策として、テストエンドポイントごとに 1 つのルールを持つルーターをデプロイして、ルーター構成自体からターゲットを明確にすることができます。また、Gemini、Claude、OpenAI モデルのレスポンスには区別可能なペイロード形状とモデル固有のフィールドがあるため、レスポンス本文を検査することもできます。リクエストごとの構造化されたルーティング決定ログは、今後のリリースで追加される予定です。

Cloud Monitoring

標準の API Gateway 指標 apigateway.googleapis.com/proxy/request_count（ベータ版）は、次の項目で分類されたゲートウェイトラフィック量を報告します。

response_code_class: 2xx、3xx、4xx、5xx のいずれか。
api_config: ゲートウェイが使用している API 構成名。

この指標を使用すると、全体的なトラフィック量とエラー率を確認できます。モデルルーター固有の指標（ルーター別またはターゲットモデル別の内訳など）は、今後のリリースで追加される予定です。

集計されたリクエストレイテンシをトラッキングするには、リクエストログの httpRequest.latency フィールドからログベースの指標を作成します。

モデルルーターの障害のトラブルシューティング

モデルルーターを介してルーティングされたリクエストが失敗した場合、対応するリクエストログエントリの responseDetails フィールドは、モデルルーターレイヤ内で障害が発生したかどうかを示します。モデルルーターには、次の 4 つのブランドカテゴリが表示されます。

`responseDetails` の値	意味	一般的な解決策
`model_router_application_error`	リクエストをルーティングできませんでした。通常、これは、ルールがない、ルールと一致しない `model` 値を含むペイロード（`defaultModel` が構成されていない）、または不正な形式のリクエストペイロードを示します。	お客様側: ペイロードの `model` パラメータがルーター構成の `rule.model` 文字列のいずれかと一致しているか、`defaultModel` フォールバックが定義されていることを確認します。リクエスト本文が有効な OpenAI 互換の JSON であり、`model` 属性が明示的に含まれていることを確認します（公開プレビュー版では、リクエストペイロードに `model` 属性がない場合、拒否されずに誤って処理されます）。
`model_router_timeout`	モデルルーターがリクエストごとのタイムアウトを超過しました。リクエストが異常に大きいか複雑であるか、容量のボトルネックが発生している可能性があります。	バックエンド全体でリクエストの複雑さとタイムアウト設定を確認します。通常のペイロードで問題が解決しない場合は、Google Cloud サポートにリクエストのタイムスタンプとログサンプルを添えてお問い合わせください。
`model_router_upstream_error`	アップストリームターゲットモデルが HTTP エラーをゲートウェイに返しました。	アップストリームサービス側: ターゲット Agent Platform サービスエンドポイントのステータスコードとペイロードを確認します。有効なリクエストで予期しない動作が発生した場合は、サポートケースを開いてください。
`model_router_unavailable`	転送または接続の失敗により、ゲートウェイからモデルルーターに到達できませんでした。	プラットフォーム側: Google Cloud サポートにサポートケースを開いてください。

次のステップ

モデルルーティングのアーキテクチャとコンセプトを確認する
OpenAPI 3.x 拡張機能を調べる

モデル ルーティングを構成する

始める前に

構成の検証

構造とロケーションの確認

HTTP メソッドの確認

バックエンドの有効性

ルーター参照の解決

ルーターの内容

バックエンドのホストとスキームの一貫性

ターゲット モデルの検証

ステップ 1: ターゲット モデルを特定する

ステップ 2: OpenAPI 3.x 仕様を構成する

構成プロパティ

ステップ 3: API 構成を作成してデプロイする

ステップ 4: ルーティング動作をテストする

明示的なルール ルーティングをテストする

デフォルト モデルのフォールバックをテストする

代替ルーター パスをテストする

オブザーバビリティ

Cloud Logging

Cloud Monitoring

モデル ルーターの障害のトラブルシューティング

次のステップ

モデルルーティングを構成する

ターゲットモデルの検証

ステップ 1: ターゲットモデルを特定する

明示的なルールルーティングをテストする

デフォルトモデルのフォールバックをテストする

代替ルーターパスをテストする

モデルルーターの障害のトラブルシューティング