配置模型路由

本页介绍了如何使用 OpenAPI 3.x 规范在 API Gateway 中配置、部署和测试模型路由。

准备工作

在配置模型路由之前，请检查您的环境是否满足以下前提条件：

  1. 检查 IAM 权限：检查您是否拥有 API Gateway 管理平面和 Vertex AI Model Garden 的访问权限。您必须拥有 API Gateway Admin (roles/apigateway.admin) 角色才能创建 API 配置和网关。此外，API 网关使用的服务账号（默认 Compute Engine 服务账号或创建 API 配置时指定的用户代管式服务账号）必须被授予 Vertex AI User (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 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-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 开放模型端点。

路由器参考解析

  • 操作的 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 字符串（google、openai 或 anthropic）的 <provider> 部分和 <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：x-google-api-management 下的 backends 对象定义了所有可路由的模型端点。每个后端名称都表示一个包含目标 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 选择器本身必须是有效的发布者模型标识符（例如 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
  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"

Cloud Monitoring

标准 API 网关指标 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 支持团队提交支持请求。

后续步骤