GDC 网闸隔离配置上的 AI 网关参考架构

问题陈述

在经过网闸隔离的环境中运行大语言模型 (LLM) 的组织会快速累积模型端点：在 Google Distributed Cloud 网闸隔离配置上运行的每个开放权重模型（请参阅配套指南集“GDC 网闸隔离配置上的开放权重模型”）都会公开其自己的 Kubernetes Service、自己的地址、自己的凭据和自己的运维生命周期。应用和智能体开发者最终会陷入架构孤岛，为每个模型硬编码一个端点，并在每次模型迭代时重写集成。这种碎片化会产生技术债务，并减慢关键任务、多步骤智能体工作负载的部署速度。

标准网络层也“无法识别 AI”：传统负载均衡器会将推理流量视为通用 HTTP，无法读取请求的 model 字段、无法优先处理对延迟时间敏感的工作负载、无法考虑词元（而非请求），也无法将请求引导至已包含相关 KV 缓存的模型服务器副本。在成本高昂的经过网闸隔离的 GPU 集群中，这会导致硬件利用率低下，投资回报率不佳。虽然 Gemini on GDC 提供代管式前沿模型，但如果客户将这些模型与自托管的开放权重模型结合使用，则需要一个推理层，该推理层既能提供类似云的敏捷性，又不会影响数据主权：任何请求、提示或模型权重都不得离开 GDC 边界。

建议的解决方案

本文档概述了 GDC 网闸隔离配置上的自行管理的 AI 网关的参考架构：一个安全的集中式推理层，可为应用提供一个与 OpenAI 兼容的端点，用于所有模型，并将每个请求路由到正确的后端。参考实现基于 Kubernetes Gateway API 构建：Envoy Gateway 是 Gateway API 实现（控制平面和 Envoy 代理数据平面），Envoy Agent Router（以前称为 Envoy AI Gateway）通过 AI 专用请求处理对其进行了扩展：从请求正文中提取模型、请求和响应转换、上游身份验证、词元统计以及（可选）基于词元的速率限制。Gateway API 推理扩展程序添加了模型服务器感知端点选择（InferencePool 和端点选择器），以便高效使用 GPU 容量。所有制品都暂存在 GDC 组织的 Harbor 注册表中，整个堆栈在标准集群中运行，没有任何外部连接。

包含的内容：此架构涵盖在标准集群中部署 Envoy Gateway 和 Envoy Agent Router、公开统一的 OpenAI 兼容端点的 Gateway API 资源（GatewayClass、Gateway）和 Envoy Agent Router 资源（AIGatewayRoute、AIServiceBackend、BackendSecurityPolicy、GatewayConfig）、基于 model 字段的正文路由、用于模型感知型负载均衡的 Gateway API Inference Extension（InferencePool、InferenceObjective、端点选择器）、使用 Redis 的可选基于令牌的速率限制、网关处的 TLS 终结、网络政策（NetworkPolicy/ProjectNetworkPolicy）以及 Harbor 中的经过网闸隔离制品管理。网关背后的模型部署后端（Ollama、vLLM）通过配套指南集“在 GDC 网闸隔离配置上部署开放权重模型”进行部署。

不包含的内容：此架构不涵盖托管式 AI 网关产品、模型本身的部署和调优（配套指南集）、模型微调、非 LLM 生成式 AI 模态、智能体到工具的流量 (MCPRoute) 或商业支持的网关发行版。Gemini on GDC 是一项代管式产品功能；其预配不在本指南集的讨论范围内，本指南集使用自托管的开放权重模型来验证网关。

受众群体：本文档的主要受众群体包括负责在标准集群中部署和运行网关的平台管理员，以及在经过网闸隔离的环境中设计 AI 平台的技术架构师。使用统一端点的应用开发者是次要受众群体，他们可以从了解请求的路由方式中受益。

架构

该解决方案完全在 GDC 网闸隔离配置组织的标准集群中运行。在服务层，Kubernetes Gateway API 会标准化配置模型；AI 网关控制平面（Envoy Gateway 控制器和 Envoy Agent Router 控制器）会读取 Gateway API 和 Envoy Agent Router 资源，并配置数据平面：作为请求入口点的 Envoy 代理 Deployment（通过类型为 LoadBalancer 的 Service 公开）和 Envoy Agent Router 外部处理器（在代理 Pod 中作为边车运行并执行 AI 专用逻辑）。在应用层，客户工作负载（应用和代理）向代理发送 AI 请求 (1)，代理将请求交给外部处理器，外部处理器提取模型名称、转换请求并记录 token 使用情况 (2)，代理将均衡后的流量转发到所选模型的推理 Pod (3)，模型在基础设施层的 GPU 节点上运行 (4)。模型部署后端可以作为 AIServiceBackend（任何与 OpenAI 兼容的 Service）或 InferencePool 附加到网关，后者的端点选择器会为每个请求选择最佳副本。容器映像和 Helm 图表是从 Harbor 中拉取的。

GDC 网闸隔离配置上的 AI Gateway 参考架构。

解决方案组件

此解决方案使用以下组件：

解决方案组件 需求管理代表的职责 数据流 接口
Kubernetes Gateway API 面向角色的标准资源模型，用于入站流量和路由：GatewayClass（由平台所有）、Gateway（监听器、TLS）和路由资源（由应用团队所有）。Ingress API 的后继者，不含供应商专用注解。 仅限声明式配置；资源由控制器监控，不承载请求流量。 Kubernetes API (gateway.networking.k8s.io/v1)；CRD 是从 Envoy Gateway CRD 图表安装的。
Envoy Gateway 控制器（控制平面） 实现 Gateway API：为每个 Gateway 预配一个 Envoy 代理 Deployment 和 LoadBalancer Service，将路由和政策（BackendTrafficPolicy、SecurityPolicy、EnvoyExtensionPolicy、Backend、EnvoyProxy）转换为 xDS 配置，在配置后运行全局速率限制服务，并通过其扩展程序管理器调用 Envoy Agent Router 扩展程序服务器，以便将 InferencePool 后端添加到转换中。 监视 Kubernetes API 并将 xDS 配置推送到代理；无请求流量。 Kubernetes API（监视）、面向代理的 xDS gRPC、面向扩展服务器的 gRPC（端口 1063）。
Envoy 代理路由器控制器（控制平面） 将 aigateway.envoyproxy.io/v1beta1 资源、AIGatewayRoute（基于提取的模型名称的路由规则）、AIServiceBackend（具有其 API schema 的后端）、BackendSecurityPolicy（上游凭据）和 GatewayConfig（每个 Gateway 的外部处理器设置）协调到 Envoy Gateway 资源中，将外部处理器边车注入 Envoy 代理 Pod 中，并提供 Envoy Gateway 使用的扩展服务器。 仅限配置。 Kubernetes API、gRPC 扩展服务器（端口 1063）、用于 Sidecar 注入的变更准入网络钩子。
Envoy 代理（数据平面） 请求入口点：终止 TLS、匹配监听器和路由、在后端端点之间进行负载均衡、强制执行速率限制和超时、重试并回退到备用后端，以及发出访问日志和指标。 在 LoadBalancer VIP (80/443) 上接收客户端请求，针对每个 AI 请求咨询外部处理器，将请求转发到所选后端端点（Service 或端点选择器选择的 Pod），并将响应流式传输回客户端。 面向客户端的 HTTP/HTTPS（OpenAI 兼容 API）、面向边车和端点选择器的 ext_proc gRPC、面向后端的 HTTP、面向速率限制服务的 gRPC。
Envoy 代理路由器外部处理器 (ExtProc) 解析与 OpenAI 兼容的请求正文，将 model 字段提取到路由标头 x-ai-eg-model 中，应用模型名称替换，在客户端 API schema 和后端 API schema 之间转换请求和响应载荷，注入由 BackendSecurityPolicy 定义的上游凭据，并将响应中的 token 用量（输入、输出、总计）提取到动态元数据中，用于基于 token 的速率限制和指标。 Envoy 代理 Pod 中的边车容器；处理请求和响应正文，包括流式响应。 Envoy ext_proc gRPC；Prometheus 指标端点。
Gateway API Inference Extension（InferencePool + 端点选择器） InferencePool (inference.networking.k8s.io/v1) 会对一个模型服务器部署的 Pod（例如标签选择器、目标端口 8000）进行分组，并引用其端点选择器 (EPP)。InferenceObjective (v1alpha2) 为每个模型或目标分配优先级。EPP 会抓取模型服务器指标（请求队列深度、KV 缓存利用率、已加载的 LoRA 适配器），并为每个请求选择端点。 代理使用请求标头调用 EPP（ext_proc，端口 9002）；EPP 使用要使用的端点进行应答；代理将请求转发到该 Pod。 Kubernetes API (CRD)、gRPC ext_proc (9002)、模型服务器的 Prometheus 爬取。
Redis（可选） Envoy 速率限制服务的后备存储区：所有代理副本中基于请求和基于令牌的限制的共享计数器。仅在配置了全局速率限制时才需要。 速率限制服务会针对每个受限请求读取并递增端口 6379 上的计数器。 Redis 协议 (6379)。集群中部署的 Redis 8.10 或现有 Redis 实例。
模型部署后端（Ollama/vLLM） 在网关后方提供开放权重模型；使用配套指南“在 GDC 网闸隔离配置上设置开放权重模型”进行部署。作为 AIServiceBackend（任何与 OpenAI 兼容的 Service，例如 Ollama）或 InferencePool（模型服务器，例如 vLLM，可公开端点选择器评分所依据的指标）附加。 接收来自代理的路由请求，在 GPU 节点上运行推理（或在 CPU 上运行推理，以便使用小型模型进行功能评估），并返回与 OpenAI 兼容的响应。 OpenAI 兼容的 REST API：端口 8000 上的 vLLM，端口 11434 上的 Ollama；端点选择器的 Prometheus 指标 (vLLM)。
Harbor 存储解决方案的容器映像（Envoy 代理、Envoy Gateway、Envoy Agent Router 控制器和外部处理器、速率限制服务、端点选择器、Redis）和 Helm 图表（OCI 工件）。 制品会从公共注册表复制到 Harbor，其中 seed_registry.sh (crane) 来自可访问互联网的工作站；集群会通过映像拉取密钥使用机器人账号拉取映像，而图表则会从 Harbor 中使用 helm template 呈现。 OCI Distribution API；Harbor 界面和机器人账号。
Standard 集群和 GPU 节点 托管所有网关组件（CPU 节点就足够了）和推理 Pod（具有从节点发现的加速器资源的 GPU 节点）。提供 LoadBalancer VIP、用于模型权重的永久性存储空间以及网络政策强制执行。 基础平台；请求通过 Gateway 的 LoadBalancer VIP 进入，并留在集群网络内。 Kubernetes API、GDC 网络 API（networking.gdc.goog/v1 ProjectNetworkPolicy）、GDC 控制台和 gdcloud（适用于平台管理员）。

特性和功能

此参考架构提供以下核心功能：

  • 统一的 OpenAI 兼容端点：应用为网关后面提供的每个模型调用一个地址（/v1/chat/completions、/v1/models 等）。
    • 组件：Gateway、AIGatewayRoute、Envoy 代理、外部处理器。
    • 职责：公开稳定的虚拟 IP、终止 TLS、接受与 OpenAI 兼容的请求格式，并在需要时将其转换为后端架构。
    • 接口：HTTPS REST（JSON，包括用于流式传输的服务器发送事件）。
  • 基于正文（模型感知）的路由：网关会读取请求正文的 model 字段，并将请求路由到匹配的后端，而无需任何客户端端点逻辑。
    • 组件：外部处理器、AIGatewayRoute 规则（匹配 x-ai-eg-model、AIServiceBackend、InferencePool）。
    • 职责：提取模型名称、匹配路由规则、重命名模型 (modelNameOverride)、按权重拆分流量，以及按优先级回退到备用后端。
    • 接口：Kubernetes API (aigateway.envoyproxy.io/v1beta1)。
  • 模型服务器感知型负载均衡：发送到 InferencePool 的请求会发送到队列最短且 KV 缓存最实用的副本，而不是轮循。
    • 组件：Gateway API Inference Extension（InferencePool、InferenceObjective、端点选择器）。
    • 职责：抓取模型服务器指标、对端点进行评分（队列深度、KV 缓存利用率、前缀缓存亲和性、LoRA 适配器），并在负载下遵循每个目标的优先级。
    • 接口：Kubernetes API（inference.networking.k8s.io/v1、inference.networking.x-k8s.io/v1alpha2）、ext_proc gRPC (9002)。
  • 上游身份验证和安全政策：需要凭据的后端的凭据由网关注入，绝不会分发到应用。
    • 组件：BackendSecurityPolicy、Envoy Gateway SecurityPolicy、TLS 监听器。
    • 职责：向后端注入 API 密钥，在 Gateway 处终止客户端 TLS，在需要时强制执行客户端身份验证和授权政策。
    • 接口：政策引用的 Kubernetes Secret。
  • 基于 token 的速率限制（可选）：用量以 token 为单位，而不仅仅以请求为单位。
    • 组件：外部处理器 (llmRequestCosts)、Envoy Gateway BackendTrafficPolicy（全局速率限制）、速率限制服务、Redis。
    • 职责：从每个回答中提取输入、输出和总 token 数，将其作为请求费用附加，并在所有代理副本中强制执行每个使用方或每个模型的预算。
    • 接口：Kubernetes API、Redis (6379)。
  • 流量管理：标准 Gateway API 功能适用于 AI 流量。
    • 组件：Gateway、HTTPRoute、AIGatewayRoute、BackendTrafficPolicy。
    • 职责：基于主机、路径和标头的匹配、适合长时间生成的超时、重试、加权流量拆分以及后端之间基于优先级的回退。
    • 接口：Kubernetes API。
  • 可观测性：每个模型都提供请求、延迟时间和词元指标。
    • 组件：Envoy 代理访问日志和统计信息、外部处理器指标（令牌用量、请求时长、首个令牌生成时间）、端点选择器指标。
    • 职责：公开 Prometheus 格式的指标和结构化访问日志，以便 GDC 可观测性堆栈或客户管理的 Prometheus 进行抓取。
    • 接口：Prometheus 指标端点、标准输出日志。
  • 经过网闸隔离的制品管理：每个映像和图表都会在安装前暂存在 Harbor 中。
    • 组件：Harbor、seed_registry.sh、机器人账号、映像拉取密钥、EnvoyProxy 资源（代理映像和拉取密钥）。
    • 职责：从已连接的工作站中植入映像和 OCI Helm 图表、固定版本、使用 helm template 离线呈现图表。
    • 接口：OCI Distribution API、Kubernetes API。

架构原则

  • 标准优先：网关通过 Kubernetes Gateway API 及其推理扩展程序进行配置，并向应用提供与 OpenAI 兼容的 API，因此应用、路由和后端可在不同的网关实现之间移植。
  • 安全至上：所有组件和数据都位于 GDC 网闸隔离边界内。TLS 在 Gateway 处终止，后端凭据由网关注入，网络访问受 NetworkPolicy 和 ProjectNetworkPolicy 对象限制。
  • 数据主权：提示、回答、模型权重和使用情况数据绝不会离开客户的 GDC 组织；操作无需外部连接。
  • 关注点分离：面向角色的 Gateway API 让平台管理员拥有 GatewayClass、Gateway、TLS 和网络政策，而应用团队则在其自己的命名空间中拥有其 AIGatewayRoute、AIServiceBackend 和 InferencePool 资源。
  • 解耦的控制平面和数据平面：控制器仅转换配置；请求路径由 Envoy 代理、其外部处理器边车和端点选择器组成，如果控制器重启，它们会继续处理流量。
  • 开放灵活：该架构全程使用开源软件（Envoy Gateway、Envoy Agent Router、Gateway API Inference Extension、Ollama、vLLM），并且相同的 Gateway API 资源可由替代实现提供。
  • 可伸缩性和性能：数据平面可通过添加代理副本进行横向扩缩，也可通过调整 CPU 和内存进行纵向扩缩；模型服务器感知型负载均衡可让 GPU 保持饱和状态，而不会使单个副本过载。
  • 简化的最终用户体验：每个模型都有一个端点、一种 API 格式和一个凭证，从而缩短了从模型部署到使用的路径。
  • 弹性：Kubernetes 健康检查和复制、Envoy 重试以及后端之间基于优先级的回退，可在单个模型副本发生故障时保持端点可用。

注意事项

  • 可伸缩性和性能：
    • 网关组件是仅限 CPU 的工作负载；Gateway 的 Envoy 代理 Deployment 通过增加其副本数（EnvoyProxy 资源）进行横向扩缩，并通过提高 CPU 和内存请求进行纵向扩缩。外部处理器进行正文检查时，CPU 消耗与请求和响应大小成正比；流式响应会以增量方式处理。
    • 模型服务器感知型负载均衡仅适用于作为 InferencePool 挂接的后端；作为 AIServiceBackend 挂接的后端由代理在其 Service 的端点之间进行负载均衡。
    • 网关不会增加 GPU 容量：吞吐量和延迟时间受模型服务器的限制。根据配套指南集（vLLM 适用于高吞吐量，Ollama 适用于易用性和仅 CPU 评估）调整模型部署规模。
    • 与典型的 HTTP API 相比，长生成需要更长的请求和空闲超时；请在路由和政策（而非客户端）上配置这些超时。
  • 资源管理：
    • 所有网关组件都在 CPU 节点上运行，不需要加速器；下表给出了功能部署的指示性大小。参考实现设置了确切的请求和限制；生产值取决于请求速率和载荷大小。
    • 下表列出了网络政策必须允许的每个端口。
    • GPU 规划属于模型部署：加速器资源名称是从节点中发现的，如配套指南集中所述。

网关组件的指示性大小（仅限 CPU）

组件 副本 CPU（请求） 内存（请求） 备注
Envoy Gateway 控制器 1 1 亿 - 5 亿 256Mi–1Gi 控制平面；不在请求路径中
Envoy 代理路由器控制器 1 1 亿 - 5 亿 256Mi–512Mi 控制平面和扩展程序服务器
Envoy 代理 Pod（代理 + 外部处理器边车） 每Gateway 1-2 次 500m–2 512Mi–2Gi 根据请求速率和载荷大小进行扩缩
端点选择器 每 InferencePool 1 次 1 亿 - 5 亿 256Mi–512Mi 抓取模型服务器指标
速率限制服务（可选） 1 1 亿 - 5 亿 256Mi–512Mi 仅限全局速率限制
Redis（可选） 1 1 亿 - 5 亿 256Mi–1Gi 仅限全局速率限制

网络端口

端口 组件 用途
80 / 443 Envoy 代理（Gateway 监听器） LoadBalancer VIP 上的 HTTP/HTTPS 入口点
1063 Envoy 代理路由器控制器（扩展服务器） 来自 Envoy Gateway 扩展程序管理器的 gRPC 调用
9002 端点选择器 来自 Envoy 代理的 ext_proc gRPC 调用
6379 Redis 速率限制计数器
8000 vLLM 模型服务器的 OpenAI 兼容 API 和指标
11434 Ollama 模型服务器的 Ollama 和 OpenAI 兼容 API
  • 可用性和可靠性：
    • 代理和外部处理器在同一 Pod 中运行；LoadBalancer Service 后面的多个副本会掩盖单个 Pod 故障，并且控制器可以在不中断流量的情况下重启。
    • AIGatewayRoute 规则可以列出多个具有优先级的后端，以便在后端运行状况不佳时，网关可以回退到另一个副本集或模型服务器。
    • 端点选择器是每个池的 Deployment；如果它不可用，则对该 InferencePool 的请求会失败，直到它恢复。使用资源请求和就绪性探测运行它，并像监控数据平面组件一样监控它。
    • Redis 仅保存速率限制计数器；Redis 服务中断会影响速率限制，而不会影响路由。
  • 操作复杂性：
    • Envoy Gateway、Envoy Agent Router 和 Gateway API 推理扩展程序之间的版本一致性：将这三者一起升级到经过测试的组合（Envoy Gateway 1.8.4、Envoy Agent Router 1.1.0、Gateway API 推理扩展程序 1.5.0）。
    • 经过网闸隔离的生命周期：每次升级时，每个映像和图表都会重新植入 Harbor；EnvoyProxy 资源和图表值会固定注册表和拉取密钥。
    • 两个配置层：平台拥有的 GatewayClass / Gateway / EnvoyProxy 和团队拥有的 AIGatewayRoute / AIServiceBackend / InferencePool；添加新模型意味着添加路由规则和后端，而不是新网关。
    • 监控：请求速率、延迟时间（包括首个词元生成时间）、每个模型和每个使用方的词元用量、端点选择器评分以及模型服务器的 GPU 利用率。
    • InferenceObjective 仍是 Alpha 版 API (v1alpha2)；推理扩展程序的各版本之间可能会有架构更改。
  • 安全与合规性：
    • 整个解决方案在 GDC 网闸隔离安全边界内运行。
    • 网络政策是强制性的：命名空间 NetworkPolicy 允许从代理到模型服务器端口（8000、11434）和端点选择器 (9002) 的流量，而 ProjectNetworkPolicy 允许客户端流量流向 LoadBalancer VIP（当使用方位于项目外部时）。
    • TLS 在 Gateway 处终止，证书存储在 Kubernetes Secret 中；客户端只能看到网关端点。
    • 上游凭据（例如模型服务器所需的 API 密钥）存储在 BackendSecurityPolicy 引用的 Secret 中，并由网关注入，因此应用绝不会持有后端凭据。
    • 基于令牌的速率限制会限制每个使用者或每个模型的昂贵 GPU 容量消耗。
    • Harbor 机器人账号和 Kubernetes 映像拉取 Secret 可确保对容器映像的安全访问；面向角色的 Gateway API RBAC 可分离平台和应用职责。

设计决策

此参考架构做出了以下关键设计决策：

决策 1：AI 网关实现：Envoy Gateway 上的开源 Envoy Agent Router 与替代发行版

上下文 关键决策 理由
AI 网关是主要架构选择，同时也有可行的替代方案，从自行管理的开源选项到商业支持的产品，不一而足：(a) Envoy Gateway 上的 Envoy Agent Router（开源）；(b) kgateway 和 agentgateway（开源 Gateway API 实现，还可在单个数据平面中处理 LLM 提供商流量、MCP 工具和智能体间通信，可选择由 solo.io 提供供应商支持）；(c) Solo Enterprise for agentgateway，作为商业支持的高级选项。 参考实现使用 Envoy Gateway 上的开源 Envoy Agent Router。在相同的 Gateway API 资源背后，这些替代方案仍然是有效的选择；对于需要专用供应商支持的生产环境，建议使用商业支持的发行版。 开源优势：轻量级且符合标准、高性能 L7 路由、无许可费，非常适合在承诺使用付费产品之前评估解决方案；Envoy Agent Router 是本指南集中验证的选项。开源缺点：支持由解决方案团队尽力提供，并由社区驱动，可能无法满足核心生产环境的需求。高级优势：针对网关生命周期的企业支持服务，通常还提供高级智能体功能。高级版缺点：需要付费许可或支持协议，并且需要与额外的供应商建立关系。

决策 2：使用推理扩展程序的 Kubernetes Gateway API 与 Ingress 或专有网关 API

上下文 关键决策 理由
推理端点可以通过旧版 Ingress API、特定于网关的配置格式或 Kubernetes Gateway API 公开。模型感知型负载均衡还需要一种方法来描述模型服务器池及其优先级。 该解决方案在 Envoy Gateway 实现的 Kubernetes Gateway API（GatewayClass、Gateway、路由）以及 Gateway API 推理扩展（InferencePool、InferenceObjective、端点选择器）的基础上进行了标准化，以实现模型感知路由。 Gateway API 是 Kubernetes 的标准，它取代了 Ingress，以角色为导向（平台团队与应用团队），并且可在各种实现之间移植。推理扩展是模型服务器感知路由（队列深度、KV 缓存、优先级）的社区标准，Envoy Agent Router 开箱即用；替代网关发行版实现了相同的 API，这使得决策 1 具有可逆性。

决策 3：在统一端点上，基于 OpenAI 兼容请求的 model 字段进行请求正文路由

上下文 关键决策 理由
应用可以通过每个模型一个端点（基于主机或路径）、通过客户端设置的自定义标头，或通过每个 OpenAI 兼容请求已携带的 model 字段来寻址模型。 网关公开一个与 OpenAI 兼容的端点，并根据 model 字段进行路由：外部处理器将其提取到 x-ai-eg-model 标头中，AIGatewayRoute 规则会根据该标头进行匹配。 现有的 OpenAI 兼容客户端和 SDK 无需更改即可运行，只需更改一个字符串即可切换模型；端点、凭据和模型放置位置可以更改，而无需修改应用；相同的规则可以将一个模型名称映射到多个后端，以实现流量分配、后备或模型名称替换。

决策 4：将经过网闸隔离的制品播种到 Harbor 与按需拉取

上下文 关键决策 理由
上游安装会根据需要从公共注册表和 Helm 图表拉取容器映像作为 OCI 工件，这在经过网闸隔离的环境中是不可能的。 所有容器映像（Envoy 代理、Envoy Gateway、Envoy Agent Router 控制器和外部处理器、速率限制服务、Endpoint Picker、Redis）以及 Envoy Gateway 和 Envoy Agent Router Helm 图表都会通过 seed_registry.sh (crane) 植入到 Harbor 项目中，图表会通过 Harbor 的 helm template 离线呈现，EnvoyProxy 资源和图表值会固定 Harbor 注册表和拉取密钥。 每个版本都有一个可重复、可审核的种子设定步骤；集群永远不需要外部连接；版本固定使升级变得明确且可逆。

决策 5：使用 Redis 的可选基于令牌的速率限制与仅基于请求的限制

上下文 关键决策 理由
GPU 容量是按 token 消耗的，而不是按请求消耗的；请求数量限制无法保护共享模型免受少数超大提示或超长生成内容的影响。Envoy Gateway 中的全局速率限制需要一个共享计数器存储区。 基于 token 的速率限制是该架构的可选功能：外部处理器记录每个请求的输入、输出和总 token 数 (llmRequestCosts)，BackendTrafficPolicy 强制执行预算，Redis 实例（Redis 8.10，部署在集群中或现有实例中）存储计数器。没有速率限制的部署不需要 Redis。 使用量以反映费用的单位进行衡量，预算在所有代理副本中一致执行，并且只有需要配额的客户才需要为依赖项付费。

决策 6：拓扑：标准集群的专用命名空间中的网关控制和数据平面，应用命名空间中的模型

上下文 关键决策 理由
网关可以在专用集群中运行，也可以在每个应用命名空间中运行，或者在每个标准集群中运行一次，紧邻其前端的模型。GDC 网闸隔离配置上的开放权重模型部署在标准集群中（配套指南集）。 Envoy Gateway 和 Envoy Agent Router 控制平面以及 Envoy 代理数据平面在托管模型的标准集群的专用命名空间中运行；AIGatewayRoute、AIServiceBackend、InferencePool 和模型部署位于应用命名空间中，并跨命名空间引用。 请求在代理和模型 Pod 之间的集群网络内传输（延迟时间最低，无需额外的负载均衡器），平台管理员拥有网关命名空间，而应用团队拥有其路由和模型，并且端点选择器可以直接抓取模型服务器。每个项目的客户端网关都会转发到中央服务器网关，这仍然是此拓扑的扩展，可供多个项目使用。

假设和限制

  • GDC 网闸隔离配置 1.16.2-hf1 或更高版本环境可与运行 Kubernetes v1.32.13-gke.400 或更高版本的标准集群搭配使用。
  • 模型服务后端有足够的硬件资源（尤其是 GPU）；网关组件本身在 CPU 节点上运行。实际模型需要 GPU；Ollama 上的小型模型可以在 CPU 上运行，但仅用于功能评估。
  • Harbor 实例已设置并可访问，并且有一个可访问互联网并可连接到 GDC 环境（Harbor 和 Kubernetes API）的工作站，用于播种映像和图表。
  • 用户拥有必要的权限：项目角色 Harbor Instance Viewer 和 Standard Cluster Admin，以及标准集群上集群级安装（CRD、GatewayClass、命名空间）的 StandardClusterRoleBinding 到 cluster-admin 角色，请参阅参考实现。
  • 模型部署后端会公开与 OpenAI 兼容的 API；作为 InferencePool 附加的后端也会公开端点选择器所依赖的与 vLLM 兼容的指标。
  • 限制：解决方案团队会尽最大努力为开源组件（Envoy Gateway、Envoy Agent Router、Gateway API Inference Extension）提供支持；如需获得专门的供应商支持，则需要使用商业支持的发行版（决策 1）。
  • 限制：InferenceObjective 是 Alpha 版 API (inference.networking.x-k8s.io/v1alpha2)，在推理扩展程序的各个版本之间可能会发生变化。
  • 限制：项目外部的使用方需要 Gateway 的 LoadBalancer VIP 和 ProjectNetworkPolicy；在项目内部，集群内客户端或 kubectl port-forward 可以直接访问网关 Service。
  • 限制：Gemini on GDC、模型微调、非 LLM 生成式 AI 模型和多节点模型部署不在此版本的解决方案范围内。

用户体验流程

以下是 GDC 网闸隔离配置上的 AI 网关的完整用户体验流程：首先是应用开发者依赖的请求路径，然后是平台管理员遵循的设置路径。

1. 开发者请求路径

应用或代理只需要网关端点、客户端凭据（如果网关强制执行）和模型名称。

  • 发送请求：应用在网关端点上调用 POST /v1/chat/completions，并使用 OpenAI 兼容的 JSON 正文来指定模型（例如 "model": "gemma"），就像调用任何 OpenAI 兼容的服务一样。
  • 进入网关：请求到达 Gateway 的 LoadBalancer VIP；Envoy 代理终止 TLS 并匹配监听器和路由。
  • 处理正文：代理将请求传递给 Envoy 代理路由器外部处理器，后者会解析正文，将模型名称提取到 x-ai-eg-model 标头中，并将载荷转换为后端架构（如果不同）。
  • 选择后端：与模型名称匹配的 AIGatewayRoute 规则会选择 AIServiceBackend（例如 Ollama Service）或 InferencePool（例如 vLLM 副本集）；对于 InferencePool，端点选择器会选择队列最短且 KV 缓存匹配度最高的副本。
  • 转发和响应：当 BackendSecurityPolicy 适用时，代理会注入上游凭据，将请求转发到所选的 Pod，将响应流式传输回来，并让外部处理器记录 token 使用情况，从而为指标和基于 token 的速率限制（如果已配置）提供数据。
  • 切换模型：如需使用其他模型，开发者只需更改 model 字符串，无需新的端点、凭证或客户端库。

2. 平台管理员设置路径

  • 将工件植入 Harbor：创建 Harbor 机器人账号，然后使用 seed_registry.sh 从可访问互联网的工作站将容器映像以及 Envoy Gateway 和 Envoy Agent Router Helm 图表复制到 Harbor。
  • 安装 Envoy Gateway：使用 helm template 渲染 Harbor 中的 CRD 和控制器图表，并将其应用到网关命名空间；创建 EnvoyProxy 资源，用于固定代理映像和拉取密钥，并使用基本的 GatewayClass、Gateway 和 HTTPRoute 验证控制器。
  • 安装 Envoy Agent Router：安装 Envoy Agent Router CRD 和 Gateway API Inference Extension CRD，部署 Envoy Agent Router 控制器，并重新配置 Envoy Gateway 以调用其扩展服务器（端口 1063）并接受 InferencePool 后端；（可选）部署 Redis 并启用全局速率限制服务。
  • 公开网关：使用 HTTP 和 HTTPS 监听器（TLS 证书 Secret）创建 GatewayClass 和 Gateway，等待 LoadBalancer VIP，并为项目外部的使用方应用 ProjectNetworkPolicy。
  • 附加模型：使用配套指南集部署模型服务后端，然后为兼容 OpenAI 的 Service 和 InferencePool 创建 AIServiceBackend 资源，并为兼容 vLLM 的副本集创建端点选择器资源，以及命名空间 NetworkPolicy 对象。
  • 发布路由：创建 AIGatewayRoute，每个模型名称对应一条规则（基于正文的路由），并根据需要为上游凭据和令牌预算创建 BackendSecurityPolicy 和 BackendTrafficPolicy 对象。
  • 验证和操作：通过 VIP（或 kubectl port-forward 回退）调用 /v1/models 和 /v1/chat/completions，检查代理、外部处理器和端点选择器指标，并将端点和模型名称提供给应用团队。独立扩缩代理副本和模型部署；同时升级 Envoy Gateway、Envoy Agent Router 和推理扩展程序。

Envoy 代理路由器参考实现和使用 Envoy 代理路由器进行基于正文的路由用户指南中提供了详细步骤。

其他资料