設定模型路由

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

事前準備

設定模型路由前,請確認環境符合下列必要條件:

  1. 檢查 IAM 權限:確認您有權存取 API Gateway 管理層和 Gemini Enterprise Agent Platform Model Garden。您必須具備 API Gateway 管理員 (roles/apigateway.admin) 角色,才能建立 API 設定和閘道。此外,閘道使用的服務帳戶 (建立 API 設定時指定的預設 Compute Engine 服務帳戶或使用者自行管理的服務帳戶),必須在託管目標模型的各項專案中,獲派「Agent Platform 使用者」(roles/aiplatform.user) 角色。因此,如果路由器的後端位於其他專案,也必須在這些專案中獲派該角色。
  2. 檢查模型可用性和端點存取權:確認可轉送的模型是 Agent Platform 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 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,就必須在 x-google-api-management 內定義 ai.models.routing.routers 區塊。
  • 您無法在同一項 API 作業中同時指定 x-google-model-router 和 x-google-backend。
  • OpenAPI 規格不得同時包含模型路由和非模型路由作業。在同一 API 規格中,您無法在某些作業上指定標準轉送擴充功能 (例如 x-google-backend),同時在其他作業上使用 x-google-model-router。

HTTP 方法檢查

  • x-google-model-router 擴充功能只能套用至使用 POST HTTP 方法的操作。管理層會拒絕任何其他 HTTP 方法 (例如 GET、PUT 或 DELETE) 的模型路由。

後端有效性

  • 在 x-google-api-management.backends 下定義的每個後端都必須包含非空白的 address 欄位。
  • 後端 address 必須是有效網址,且採用 http 或 https 配置。為保護在公開或遠端端點之間傳輸的提示酬載和驗證憑證,請務必在定義 address 欄位時指定 https 配置。Google API 端點必須使用 https;請參閱「後端主機和配置」。
  • 在 x-google-api-management.backends 下定義且由模型路由器參照的每個後端,都必須使用 pathTranslation: CONSTANT_ADDRESS。管理層會拒絕使用 pathTranslation: APPEND_PATH_TO_ADDRESS 做為模型路由後端的設定,因為模型路由器的執行階段路徑會忽略路徑轉譯。
  • 模型路由後端不支援 VPC Service Controls 或 Private Service Connect (PSC) 端點設定。所有後端 address 欄位都必須指向公開區域或全域 MaaS 開放模型端點。

路由器參考解析度

  • 作業 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 值。

後端主機和配置

模型路由僅支援 Google API 端點做為後端:主機名稱結尾為 .googleapis.com 或 .vertexai.goog。閘道會使用一個 OAuth 2.0 存取權杖,向單一路由器參照的每個後端 (包括 defaultModel.backend 和每項規則的 backend) 進行驗證,該權杖在任何 Google API 主機上都有效 (請參閱「其他 Google Cloud API」)。管理層會拒絕違反下列規則的設定:

  • 路由器參照的每個後端都必須使用 https 配置。
  • 路由器無法混合使用 Google API 端點和其他端點。

路由器參照的後端可以位於不同的主機 (例如全域端點 aiplatform.googleapis.com、區域端點,例如 us-central1-aiplatform.googleapis.com 或 .vertexai.goog 端點) 和不同的專案。

目標模型驗證

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

步驟 1:找出目標模型

找出目標基礎模型及其對應的 Agent Platform 端點網址。路由器中的模型可以使用不同的 Agent Platform 端點,例如全域端點 (aiplatform.googleapis.com) 和區域端點 (us-central1-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:x-google-api-management 下方的 backends 物件會定義所有可轉送的模型端點。每個後端名稱都代表一個符號模型名稱 (例如 gemini-35-flashlite),其中包含目的地 address。backends 欄位是現有的 Google OpenAPI 擴充功能。
  2. ai.models.routing:模型路由設定位於 x-google-api-management 下方,名稱為 ai.models.routing,包含具名路由器的對應。每個地圖項目都會定義一個模型路由器,其中鍵代表路由器名稱 (例如 gemini-claude-router),值則包含:
    • defaultModel:當傳入的要求酬載不符合任何明確規則時,系統會使用這個必要的備用模型目的地。其結構與規則項目完全相同,但省略了 model 比對欄位。如果是與 OpenAI 相容的路徑,當要求備援至 defaultModel 時,targetModel 的值會做為傳出 model 屬性,轉送至傳送給 Agent Platform 的要求主體。
    • rules:選用陣列,其中每個元素都會將用戶端酬載模型字串對應至目的地後端和目標模型。
  3. 規則屬性:rules (和 defaultModel) 中的每個項目都會定義下列屬性:
    • model (僅限規則):與用戶端傳入 JSON 提示酬載中 model 屬性比對的字串值。路由器會將傳入酬載的 model 值與這個字串進行比較。如果沒有相符的規則,路由器會選取 defaultModel。如果是與 OpenAI 相容的路徑 (目的地後端為 /openapi/chat/completions),這個字串會直接轉送為傳出 model 屬性,並包含在傳送至 Agent Platform 的要求主體中。因此,對於與 OpenAI 相容的路徑,model 選取器本身必須是有效的發布者模型 ID (例如 openai/gpt-oss-120b-maas);如果使用 gpt-oss 等別名,Agent Platform 會傳回 400 Malformed publisher model 錯誤。
    • backend:在 x-google-api-management.backends 下定義的符號後端名稱,閘道會將提示傳送至該後端。
    • targetModel:目標模型 ID,格式為 <provider>/<model-id>。模型路由器會使用這個字串,為目的地模型翻譯要求和回覆。<provider> 前置字串必須是 google、openai 或 anthropic。<model-id> 必須是有效的 Agent Platform 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 主機名稱。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 相容的提示要求傳送至閘道網址 (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"

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 錯誤。 上游服務端:檢查目標 Agent Platform 服務端點的狀態碼和酬載。如果有效要求發生這種情況,請提交客服案件。
model_router_unavailable 傳輸或連線失敗,導致閘道無法連至模型路由器。 平台端:向Google Cloud 支援團隊提交客服案件。

後續步驟