設定模型路徑

本頁面說明如何使用 OpenAPI 3.x 規格，在 API Gateway 中設定、部署及測試模型路徑。

事前準備

設定模型路徑前，請先確認環境符合下列必要條件：

1. 檢查 IAM 權限：確認您有權存取 API Gateway 管理平面和 Vertex AI Model Garden。您必須具備 API Gateway 管理員 (roles/apigateway.admin) 角色，才能建立 API 設定和閘道。此外，API 閘道使用的服務帳戶 (預設的 Compute Engine 服務帳戶，或建立 API 設定時指定的使用者管理服務帳戶)，必須取得 Vertex AI 使用者 (roles/aiplatform.user) 角色，才能存取目標模型。
2. 檢查模型可用性和端點存取權：確認可路由傳送的模型已預先部署在 Vertex AI Model Garden 中，做為模型即服務 (MaaS) 的開放式模型。單一路由器參照的所有模型都必須共用完全相同的主機名稱。為該路由器中參照的每個模型，選擇全域端點 (aiplatform.googleapis.com) 或單一區域端點 (例如 us-central1-aiplatform.googleapis.com)。
3. 檢查閘道部署資格：您無法更新已部署的閘道，啟用模型路徑，也無法更新已部署的閘道，停用或移除模型路徑。如要切換路由模式，必須建立並部署新的 API 設定和閘道執行個體。
4. 檢查 VPC Service Controls 和端點相容性：模型路由閘道不支援 VPC Service Controls 或 Private Service Connect (PSC) 端點設定。確認目標專案和 API 閘道執行個體未受 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，就必須在 x-google-api-management 內定義 ai.models.routing.routers 區塊。
• 您無法在同一個 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 配置的有效網址。為保護在公用或遠端端點之間傳輸的提示酬載和驗證憑證，定義 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 欄位。
• 單一路由器中所有規則定義的 model 值不得重複。管理平面會拒絕同一個路由器中的重複 model 值。

後端主機和配置一致性

• 單一路由器參照的所有後端 (包括 defaultModel.backend 和每個規則的 backend) 必須共用相同的主機名稱和網址配置。管理平面會拒絕在同一路由器中，使用不同主機名稱或不一致的架構 (http 與 https) 的設定，確保路由器將所有要求派送至一致的上游服務端點。

驗證目標模型

• 在設定建立 (部署) 時，系統會驗證 targetModel 字串的 <provider> 部分 (google、openai 或 anthropic) 和 <provider>/<model> 識別碼格式。如果 targetModel 的格式不是 <provider>/<model>，或供應商不是 google、openai 或 anthropic，管理層會在部署期間拒絕 targetModel，並傳回 InvalidArgument: unsupported publisher 錯誤。

步驟 1：找出目標機型

找出目標基礎模型及其對應的 Vertex AI 端點網址。路由器中的所有可路由模型都必須共用單一主機名稱 (如果是 MaaS 開放模型，這個主機名稱為 aiplatform.googleapis.com)。

端點網址路徑會因模型供應商而異：

• Google Gemini：使用 :generateContent 方法。
• Anthropic Claude：使用 :rawPredict 方法。
• OpenAI：使用 /endpoints/openapi/chat/completions 端點路徑。

下表列出本節稍後 OpenAPI 規格範例中使用的 MaaS 端點：

模型	端點網址
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 規格，定義後端端點和模型路徑設定。

以下範例展示 OpenAPI 3.0.3 規格，定義兩個不同的模型路由器。為避免水平捲動，後端位址網址過長時，請使用 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"

設定屬性

1. backends：backends 物件 (位於 x-google-api-management 下方) 會定義所有可路由傳送的模型端點。每個後端名稱都代表含有目的地 address 的符號模型名稱 (例如 gemini-35-flashlite)。backends 欄位是現有的 Google OpenAPI 擴充功能。
2. ai.models.routing：模型路由設定位於 x-google-api-management 下方，為 ai.models.routing，內含具名路由器地圖。每個對應關係都會定義一個模型路由器，其中鍵代表路由器的名稱 (例如 gemini-claude-router)，值則包含：
   • defaultModel：當傳入的要求酬載不符合任何明確規則時，系統會使用這個必要備用模型目的地。這項屬性與規則項目的結構完全相同，但會省略 model 比對欄位。如果是相容於 OpenAI 的路徑，當要求回溯至 defaultModel 時，targetModel 的值會轉送為傳送至 Vertex AI 的要求主體中，外送的 model 屬性。
   • rules：選用陣列，其中每個元素都會將用戶端酬載模型字串對應至目的地後端和目標模型。
3. 規則屬性：rules (和 defaultModel) 中的每個項目都會定義下列屬性：
   • model (僅限規則)：與用戶端傳入的 JSON 提示酬載中 model 屬性相符的字串值。路由器會將傳入酬載的 model 值與這個字串進行比較。如果沒有符合的規則，路由器會選取 defaultModel。如果是與 OpenAI 相容的路徑 (目的地後端為 /openapi/chat/completions)，這個字串會直接轉送為傳送至 Vertex AI 的要求主體中外送的 model 屬性。因此，對於與 OpenAI 相容的路徑，model 選取器本身必須是有效的發布商模型 ID (例如 openai/gpt-oss-120b-maas)；使用別名 (例如 gpt-oss) 會導致 Vertex AI 傳回 400 Malformed publisher model 錯誤。
   • backend：閘道傳送提示時，在 x-google-api-management.backends 下定義的符號後端名稱。
   • targetModel：目標模型 ID，格式為 <provider>/<model-id>。模型路由器會使用這個字串，為目標模型翻譯要求和回應。「<provider>」前置字串必須完全符合「google」、「openai」或「anthropic」。<model-id> 必須是有效的 Vertex AI Model Garden 發布商模型 ID。閘道會在傳回給用戶端的回應中，於 model 欄位內回傳這個字串。範例值包括：
     • google/gemini-3.5-flash-lite
     • google/gemini-2.5-pro
     • openai/gpt-oss-120b-maas
     • anthropic/claude-opus-4-7
4. 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 狀態，然後擷取其網址：

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

在公開測試期間，模型路由閘道會傳回 *.run.app 主機名稱。閘道 ACTIVE 後再擷取主機名稱；閘道仍在建立時回報的值並非最終網址。

使用 curl 將與 OpenAI 相容的提示要求傳送至閘道網址 (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

透過閘道路由的每項要求，都會在專案的標準 API Gateway 要求記錄中產生項目，位置如下： Google Cloud

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 欄位無法識別所選模型。如要解決這個問題，您可以為每個測試端點部署單一規則的路由器，這樣目標就會明確顯示在路由器設定中，也可以檢查回應主體，因為 Gemini、Claude 和 OpenAI 模型的回應具有可區分的酬載形狀和模型專屬欄位。日後版本將新增結構化要求路由決策記錄。

Cloud Monitoring

標準 API Gateway 指標 apigateway.googleapis.com/proxy/request_count (Beta 版) 會提供閘道流量的報表，並依下列項目細分：

• response_code_class：2xx、3xx、4xx 或 5xx。
• api_config：閘道使用的 API 設定名稱。

這項指標可協助您驗證整體流量和錯誤率。我們會在日後推出的版本中，加入模型路由器專屬指標 (例如每個路由器或每個目標模型的細目)。

如要追蹤匯總要求延遲時間，可以從要求記錄中的 httpRequest.latency 欄位建立記錄指標。

排解型號路由器故障問題

如果透過模型路由器轉送的要求失敗，對應要求記錄項目的 responseDetails 欄位會指出失敗是否發生在模型路由器層。模型路由器會顯示四個品牌類別：

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 擴充功能