模型路由概览

API Gateway 的模型路由是一个受管理的流量管理层，可接受与 OpenAI 兼容的提示请求，在传输过程中对这些请求进行转码，并将其路由到特定的 Gemini Enterprise Agent Platform 模型。模型路由可作为 LiteLLM 等客户端代理的受管理替代方案，提供集中式基础架构来管理 AI 代理的生命周期。

模型路由将路由逻辑移至网络边缘，并与 Agent Platform Model Garden 集成，以实现同主机优化。此架构无需托管、扩缩和维护非受管代理服务器，从而降低运营开销和基础设施成本。

范围和用户体验历程

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

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

我们计划在未来的 API 网关版本中支持更多用户体验历程。

模型路由的优势

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

  • 集中化管理：在一个受管理的网关内整合 AI 流量管理，取代分散的客户端路由配置。
  • 减少了运营开销：消除了与部署独立代理服务器相关的基础设施成本和维护负担。
  • 经过边缘优化的性能：检查提示并在网络边缘路由流量，利用与 Agent Platform 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 兼容的请求转码为目标 Agent Platform 预测架构。
  5. 后端调度：网关将转码后的请求调度到指定的 Agent Platform Model Garden 端点，并将模型响应返回给客户端。

性能和限制

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

  • 主机限制：模型路由仅支持路由到托管在 Agent Platform 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、WebSocket 或 Gemini Live。
  • 支持的模态：在公开预览期间，模型路由会假设基于文本的提示请求采用与 OpenAI 兼容的 JSON 载荷格式，并仅根据载荷中的 model 标记或名称进行路由。
  • 必需的载荷字段：传入的 JSON 请求载荷必须包含 model 属性。在公开预览期间，如果客户端请求载荷中缺少 model 字段，网关会错误地处理请求，而不是拒绝请求并返回错误。请务必确保客户端请求在 JSON 载荷中指定 model 字段。
  • 运行时限制：标准网关托管基础设施服务限制和行为适用于模型路由端点：
    • 最长超时时间：网关强制执行最长请求超时时间 3,600 秒（1 小时），适用于长时间运行的流式传输请求。
    • 冷启动延迟时间：如果网关实例在非活动期间缩放到零，则初始请求可能会遇到冷启动延迟时间，这可能会影响对延迟时间较为敏感的 AI 推理路径。
    • 预留的网址路径：您不能使用预留的网址路径，例如 /eventlog、以 /_ah/ 开头的路径或以 z 结尾的某些路径（为避免冲突，请避免使用以 z 结尾的路径名称）。
    • 网址字符解码：网关会在处理请求之前自动解码请求网址中的某些编码字符（例如，%41 会解码为 A）。

后续步骤