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

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

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

始める前に

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

IAM 権限を確認する: API Gateway 管理プレーンと Vertex AI Model Garden にアクセスできることを確認します。API 構成とゲートウェイを作成するには、API Gateway 管理者（roles/apigateway.admin）ロールが必要です。また、API ゲートウェイで使用されるサービスアカウント（デフォルトの Compute Engine サービスアカウント、または API 構成の作成時に指定されたユーザー管理のサービスアカウント）には、ターゲットモデルにアクセスするための Vertex AI ユーザー（roles/aiplatform.user）ロールが付与されている必要があります。
モデルの可用性とエンドポイントアクセスを確認する: ルーティング可能なモデルが、Vertex AI 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 フィールドが信頼できる Vertex AI エンドポイント（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 フィールドを含める必要があります。
1 つのルーター内のすべてのルールで定義された model 値は一意である必要があります。管理プレーンは、同じルーター内の重複する model 値を拒否します。

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

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

ターゲットモデルの検証

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

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

ターゲットの基盤モデルと、対応する Vertex AI エンドポイント 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 の値は、Vertex AI に送信されるリクエスト本文の送信 model 属性として転送されます。
- rules: 省略可能な配列。各要素は、クライアントペイロードモデル文字列を宛先バックエンドとターゲットモデルにマッピングします。
ルールのプロパティ: rules（および defaultModel）内の各エントリは、次のプロパティを定義します。
- model（ルールのみ）: クライアントの受信 JSON プロンプトペイロード内の model 属性と照合される文字列値。ルーターは、受信ペイロードの model 値をこの文字列と比較します。ルールが一致しない場合、ルーターは defaultModel を選択します。OpenAI 互換のルート（宛先バックエンドが /openapi/chat/completions の場合）、この文字列は、Vertex AI に送信されるリクエスト本文の送信 model 属性として直接転送されます。したがって、OpenAI 互換ルートの場合、model セレクタ自体が有効なパブリッシャーモデル識別子（openai/gpt-oss-120b-maas など）である必要があります。gpt-oss などのエイリアスを使用すると、Vertex AI から 400 Malformed publisher model エラーが返されます。
- backend: x-google-api-management.backends で定義されたシンボリックバックエンド名。ゲートウェイがプロンプトを送信します。
- targetModel: <provider>/<model-id> 形式のターゲットモデル識別子。モデルルーターは、この文字列を使用して、宛先モデルのリクエストとレスポンスを変換します。<provider> 接頭辞は、google、openai、anthropic のいずれかにする必要があります。<model-id> は、有効な Vertex AI 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 ホスト名を返します。ホスト名を取得するのは、ゲートウェイが ACTIVE になってからのみです。ゲートウェイの作成中にレポートされる値は最終的な URL ではありません。

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 バックエンドにリクエストをルーティングするように指示します。1 つのバックエンドを複数のルーターで参照できます。この構成では、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: リクエストがプロキシされた Vertex AI バックエンドのホスト名。
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 エラーを返しました。	アップストリームサービス側: ターゲットの Vertex AI サービスエンドポイントからステータスコードとペイロードを確認します。有効なリクエストでこの結果が予期しないものである場合は、サポートケースを登録してください。
`model_router_unavailable`	トランスポートまたは接続の障害により、モデルルーターにゲートウェイからアクセスできませんでした。	プラットフォーム側: Google Cloud サポートにサポートケースを登録します。

次のステップ

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

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

始める前に

構成の検証

構造と位置情報のチェック

HTTP メソッドのチェック

バックエンドの有効性

ルーター参照の解決

ルーターのコンテンツ

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

ターゲット モデルの検証

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

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

構成プロパティ

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

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

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

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

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

オブザーバビリティ

Cloud Logging

Cloud Monitoring

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

次のステップ

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

ターゲットモデルの検証

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

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

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