配置模型路由

本页介绍了如何使用 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 错误。