模型路由概览

API Gateway 的模型路由是一种托管式流量管理层，可接受与 OpenAI 兼容的提示请求，在传输过程中对这些请求进行转码，并将它们路由到特定的 Vertex AI 模型。模型路由是客户端代理（例如 LiteLLM）的托管替代方案，可提供集中式基础架构来管理 AI 智能体的生命周期。

模型路由将路由逻辑移至网络边缘，并与 Vertex AI Model Garden 集成以进行同主机优化。此架构无需托管、扩缩和维护非托管代理服务器，从而降低了运营开销和基础架构费用。

范围和用户体验历程

模型路由支持以下核心用户体验历程：

  • 模型选择：AI 开发者使用 Vertex AI Model Garden 中“模型即服务”(MaaS) 的开放模型。这些模型包括 Gemini、Anthropic Claude 或 OpenAI GPT 系列模型。
  • 规范编写：AI 开发者在 OpenAPI 3.x 规范中创建或更新模型路由器配置，以引用已部署的模型。
  • API Gateway 部署：AI 开发者使用编写的 OpenAPI 规范部署 API 配置和 API Gateway 实例。
  • 提示路由：客户端应用向网关发送与 OpenAI 兼容的提示请求，网关会根据 JSON 载荷中指定的模型名称路由请求并转换载荷。

API Gateway 的未来版本计划支持其他用户体验历程。

模型路由的优势

在 API Gateway 中实现模型路由具有以下优势：

  • 集中式管理：在一个托管式网关中整合 AI 流量管理，取代分散的客户端路由配置。
  • 降低运营开销：消除与部署独立代理服务器相关的基础架构费用和维护负担。
  • 边缘优化性能：在网络边缘检查提示和路由流量，利用与 Vertex AI Model Garden 端点的直接集成。
  • 标准化客户端接口：使客户端应用能够与统一的 OpenAI 兼容 REST 接口进行交互，同时将请求动态分派到各种底层基础模型。

角色和使用场景

模型路由满足以下角色的要求：

  • 平台工程师：预配托管式基础架构解决方案，以取代企业 AI 部署中的客户端路由逻辑。
  • AI 开发者：公开标准化 API 端点，该端点根据请求载荷参数在不同的基础模型（例如 Gemini Pro、Gemini Flash 或 Anthropic Claude）之间动态路由请求。
  • 治理管理员：强制执行集中式访问政策（例如身份验证和配额），并监控整个组织的总体 AI 流量。

支持的使用场景

在公开预览版期间，模型路由仅支持根据与 OpenAI 兼容的客户端请求的 JSON 载荷中指定的模型标记或名称（例如 "model": "gemini-3.5-flash-lite"）进行路由。

架构和请求流

模型路由作为 API 网关数据平面中的托管式路由层运行。当客户端应用向网关发送与 OpenAI 兼容的提示请求时，会发生以下序列：

  1. 请求拦截：网关拦截传入的 POST 请求（例如 POST /chat/completions）。
  2. 载荷检查：模型路由器检查传入 JSON 载荷中的 model 属性（例如 {"model": "claude-opus-4-7", "messages": [...]}）。
  3. 规则评估：路由器将 model 字符串与 OpenAPI 规范中定义的路由规则进行匹配。如果没有匹配的规则，路由器会选择配置的默认模型。
  4. 传输中转码：网关将与 OpenAI 兼容的请求转码为目标 Vertex AI 预测架构。
  5. 后端分派：网关将转码后的请求分派到指定的 Vertex AI Model Garden 端点，并将模型响应返回给客户端。

性能和限制

在实现模型路由之前，请查看以下技术限制：

  • 主机限制：模型路由仅支持路由到 Vertex AI Model Garden 上预先部署的 MaaS 模型，其中单个路由器引用的所有模型共享同一主机名（例如全局端点 aiplatform.googleapis.com 或单个区域端点，例如 us-central1-aiplatform.googleapis.com）。
  • 规范要求：模型路由需要 OpenAPI 3.x 规范和相应的 API Gateway OpenAPI 3.x 扩展程序。不支持 OpenAPI 2.0 (Swagger) 规范。
  • 网关更新：您无法更新在未启用模型路由的情况下部署的现有网关来启用模型路由，也无法更新在启用模型路由的情况下部署的网关来停用或移除模型路由。如需切换路由模式，您必须创建并部署新的 API 配置和网关实例。
  • 混合配置：OpenAPI 规范不能包含模型路由和非模型路由操作的混合。规范中的所有操作都必须使用模型路由或使用标准网关路由。
  • VPC Service Controls：模型路由网关不支持 VPC Service Controls。您无法将 VPC Service Controls 边界与启用模型路由的 API Gateway 实例搭配使用。
  • 流式传输和不受支持的协议：模型路由支持响应流式传输（服务器发送的事件），但不支持请求端流式传输、gRPC、WebSockets 或 Gemini Live。
  • 支持的模态：在公开预览版期间，模型路由假定基于文本的提示请求格式为与 OpenAI 兼容的 JSON 载荷，并且仅根据载荷中的 model 标记或名称进行路由。
  • 必需的载荷字段：传入的 JSON 请求载荷必须包含 model 属性。在公开预览版期间，如果客户端请求载荷中缺少 model 字段，网关会错误地处理请求，而不是拒绝请求并返回错误。请务必确保客户端请求在 JSON 载荷中指定 model 字段。
  • 运行时限制：标准网关托管基础架构服务限制和行为适用于您的模型路由端点：
    • 最长超时时间：网关强制执行 3,600 秒（1 小时）的最长请求超时时间，该超时时间适用于长时间运行的流式传输请求。
    • 冷启动延迟时间：如果您的网关实例在不活动期间缩减为零，则初始请求可能会遇到冷启动延迟时间，这可能会影响对延迟时间敏感的 AI 推理路径。
    • 预留网址路径：您无法使用预留网址路径，例如 /eventlog、以 /_ah/ 开头的路径或以 z 结尾的某些路径（为避免冲突，请避免使用以 z 结尾的路径名称）。
    • 网址字符解码：网关会在处理请求之前自动解码请求网址中的某些编码字符（例如，%41 会解码为 A）。

后续步骤