位于 OpenAI 前端的 Envoy Gateway,带有每月 token 预算
一个团队将 OpenAI 的 gpt-4o-mini 置于集群内网关之后,希望为网关每个日历月在其上消耗的
token 设定上限,并让其智能体指向网关而不是 OpenAI。本工作区将此编译为 Kubernetes
manifests:Envoy Gateway 通过 Envoy AI Gateway 提供模型服务,并附加
core/period-budget,由一个 Redis 保存计数,一个 CrewAI 智能体
通过网关发送其模型请求。
本页还展示了此网关拒绝计数的内容:以美元计的预算 会使构建中止,按调用方设定的预算也是如此。
本工作区不编写任何自有的目录实体。这里的三个实体文件 ——一个 Aggregate、一个 Manifest 和一个 Release——就是任何人需要 编写的全部内容。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
edge | core/gateway/envoy-gateway | 网关,从模型 chat 提供一个别名 assistant |
ai-controller | core/gateway/envoy-ai-gateway-operator | Envoy AI Gateway 的控制器,网关将其作为扩展服务器调用,随六个 AI Gateway 资源定义一起安装 |
chat | core/ai-model/openai | OpenAI 的 gpt-4o-mini,以引用的方式访问:集群中不为它运行任何内容 |
counters | core/datastore/redis | 网关的限流服务在其中保存预算计数的存储 |
assistant | core/ai-agent/crewai | 一个将模型请求发往网关的代理 |
certs | core/security/cert-manager | cert-manager,为控制器的 webhook 所提供的证书签发证书 |
网关的 uses 边从其 extension 插槽出发,指向控制器;从 models 出发,指向模型,并以网关向 OpenAI 出示的密钥作为其 credential;从 cache 出发,指向存储,携带限流服务向存储出示的密码。代理的 model 边指向网关,而不是模型。网关上有一个 Feature 挂载,
budget:Aggregate 写明计数的对象 total_tokens,以及一个限额覆盖谁的流量 gateway——即网关提供的全部内容——而
Release 写明数量和时长:每个自然月两千万个 token。
Manifest 将每个凭据绑定到 k8s-existing-secret,它让工作负载指向其命名空间中已有的 Secret,自身不渲染任何 Secret,因此 Aggregate、Release 和渲染输出中都没有任何密钥或密码。这些 Secret 的名称是 Release 满足的两个参数,而存储自身的 password 插槽读取的参数与网关的 cache 连接相同,因此存储和向其出示密码的服务指向同一个 Secret。
Release 声明每个工作负载的运行位置:cert-manager 在 cert-manager 中,控制器在 envoy-ai-gateway-system 中,代理在 assistant 中,网关在 envoy-gateway-system 中——控制器会在那里查找网关的控制平面,网关放在其他任何位置都会使构建中止——存储与网关位于同一处。模型不运行任何内容:它唯一的文件是一个将集群内名称映射到 OpenAI 主机的 Service,没有指定命名空间,并且网关通过模型发布的端点访问 OpenAI,而不是通过该 Service。
cert-manager 是声明出来的,而不是假定存在的
控制器的 webhook 提供由 cert-manager 签发的证书:其 Recipe
渲染一个 cert-manager Certificate 以及为其签名的自签名 Issuer,
而这些只有正在运行的 cert-manager 才会协调。编译器无法查看集群来确认其中是否运行着 cert-manager,因此工作区声明 cert-manager,
而不是假定它存在:certs 与控制器一同位于 Aggregate 中,
构建时会将 cert-manager 与其他所有内容一起渲染。
一个集群只运行一个 cert-manager。如果你的集群中已经运行了一个,请在构建之前从 Aggregate 和 Release 中移除 certs;
这样构建渲染出的文件与原来相同,只是少了 cert-manager 自身的文件。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example envoy-ai-gateway-token-budget然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd envoy-ai-gateway-token-budget构建
aggrega build --release release.yaml --auto-pullrelease 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build解析会固定 Recipes 所渲染的三个 chart:来自 Docker Hub 的 Envoy Gateway 和 Envoy AI Gateway 的 chart,以及来自 quay.io 的 cert-manager 的 chart,因此需要网络。此工作区从 .aggrega-config.yaml 指定的默认注册表解析目录实体。
使用 --auto-pull 构建时输出如下,其中 <workspace> 代表本示例的文件夹:
Pull complete: release.lock (entities=26, source_artifacts=3, external_inputs=0)[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and the total build time, which differs per run]Build completed: 113 files written to <workspace>/dist借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `envoy-ai-gateway-token-budget` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `envoy-ai-gateway-token-budget`,且不设置 `dir`:它会把示例写入新的 `envoy-ai-gateway-token-budget` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `envoy-ai-gateway-token-budget`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我这次构建写入了哪些文件;它们位于 `envoy-ai-gateway-token-budget/dist/` 下。渲染出的目录树
dist/helm/├── ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml[… omitted: the controller's two cluster roles and their bindings]├── ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml├── ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml├── ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml├── ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml[… omitted: the controller's service account]├── ai-controller/│ ├── aigateway.envoyproxy.io_aigatewayroutes.yaml[… omitted: the other five AI Gateway resource definitions]├── assistant-deployment.yaml[… omitted: the files cert-manager's chart renders, each named certs-…]├── chat-service.yaml├── counters-default-service.yaml├── counters-deployment.yaml[… omitted: Envoy Gateway's cluster roles and their bindings]├── edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml[… omitted: the resource definitions Envoy Gateway's chart installs]├── edge-deployment-envoy-gateway-system-envoy-gateway.yaml[… omitted: the rest of Envoy Gateway's chart — its certificate job, admission configurations, roles, bindings, Service and service accounts]└── edge/ ├── gateway.yaml ├── gatewayclass.yaml └── models.yaml预算本身不带来任何文件。它的作用写入网关的两个文件中:dist/helm/edge/models.yaml,其中包含 AI 路由以及通往模型的资源;以及控制平面的配置,
dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml。
网关所读取的预算
models.yaml 中的 AI 路由:
apiVersion: aigateway.envoyproxy.io/v1beta1kind: AIGatewayRoutemetadata: [… omitted: the labels and annotations every rendered resource carries] name: edge-models namespace: "envoy-gateway-system"spec: parentRefs: - name: edge kind: Gateway group: gateway.networking.k8s.io llmRequestCosts: - metadataKey: llm_total_token type: TotalToken rules: - matches: - headers: - type: Exact name: x-ai-eg-model value: "assistant" backendRefs: - name: edge-assistant modelNameOverride: "gpt-4o-mini"以及同一文件中对其进行限制的流量策略,其名称与它所指向的路由相同:
apiVersion: gateway.envoyproxy.io/v1alpha1kind: BackendTrafficPolicymetadata: [… omitted: the labels and annotations every rendered resource carries] name: edge-models namespace: "envoy-gateway-system"spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: edge-models rateLimit: global: rules: - limit: requests: 20000000 unit: Month shared: true cost: request: from: Number number: 0 response: from: Metadata metadata: namespace: io.envoy.ai_gateway key: llm_total_token以下是控制平面配置中的 envoy-gateway.yaml 键:
apiVersion: gateway.envoyproxy.io/v1alpha1kind: EnvoyGatewayextensionApis: enableBackend: true enableEnvoyPatchPolicy: trueextensionManager: hooks: xdsTranslator: post: - Translation - Cluster - Route translation: cluster: includeAll: true listener: includeAll: true route: includeAll: true secret: includeAll: true service: fqdn: hostname: ai-controller.envoy-ai-gateway-system.svc.cluster.local port: 1063gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controllerlogging: level: default: infoprovider: kubernetes: rateLimitDeployment: container: env: - name: REDIS_AUTH valueFrom: secretKeyRef: key: password name: counter-store-password - name: USE_CALENDAR_MONTH_RATE_LIMIT value: "true" image: docker.io/envoyproxy/ratelimit:8fe6ea42 patch: type: StrategicMerge value: spec: template: spec: containers: - imagePullPolicy: IfNotPresent name: envoy-ratelimit shutdownManager: image: docker.io/envoyproxy/gateway:v1.9.1 type: KubernetesrateLimit: backend: redis: url: counters-default.envoy-gateway-system.svc.cluster.local:6379 type: Redis failClosed: true从中可以看出:
成本设在 AI 路由上,限额设在它转换成的路由上。 Envoy AI
Gateway 读取模型每次回复所报告的 total_tokens,并将其写入请求元数据的 llm_total_token 下:这正是
llmRequestCosts 所声明的内容。控制器将 AI 路由转换为同名的 HTTP 路由
edge-models,流量策略指向该路由,因此预算覆盖模型流量,而不覆盖挂接到网关的其他路由。
回复在完成时计费。 cost.request 在请求到达时不计费;cost.response 在回复完成后按回复的 token 数计费。一旦截至目前的计费总数超过 limit,请求即被拒绝。
整个网关共用一个计数。 shared: true 在路由的所有规则之间保持同一个计数——即挂接所要求的 gateway 范围。若使用
scope: model,该 Recipe 会为 models 套接字上的每个连接写入一条规则,
每条规则匹配请求在 x-ai-eg-model 中携带的模型名称,从而对每个模型分别计数。
周期是时钟上的一个单位。 1mo 写作 unit: Month,
配置通过 USE_CALENDAR_MONTH_RATE_LIMIT 告知 Envoy Gateway 的限流服务,
将一个 Month 从日历月的第一天计到最后一天。该设置属于服务本身,因此适用于此 Envoy Gateway 安装所维护的每个 Month 限流,包括预算的限流及其他限流。每个窗口都从 UTC 时钟上的固定时间点开始,而不是从第一个请求开始:一天从 UTC 00:00 开始,一周从星期四开始。
计数保存在 cache 套接字所连接的存储中。 rateLimit 块启用 Envoy Gateway 自带的限流服务(由控制平面在其命名空间中创建,并为其服务的每个网关启用),并将其指向网关的 cache 套接字所连接的 Redis。该存储发布的主机名不带命名空间,因此网关会用该 Release 放置存储的命名空间对其进行限定。
未获应答的检查会拒绝请求。 failClosed: true 使 Envoy 在存储或限流服务无法访问时,或者检查耗时超过 Envoy 的限流超时(默认 20 ms)时,以 HTTP 500 拒绝模型请求,而不是放行且不计数。该设置属于控制平面,因此对此 Envoy Gateway 安装所维护的每个限流都有效,手动应用到该安装的限流同样会以关闭方式失败。只有在挂接预算时,配置中才会包含该设置。
其中不含密码。 服务以 REDIS_AUTH 读取存储的密码,来源是 cache 连接的凭据所指定的 Secret
counter-store-password,服务在自己的命名空间(即网关的命名空间)中解析它。存储 counters-deployment.yaml 启动时使用从同一 Secret 读取的 --requirepass。
从 agent 到模型的路径
摘自 assistant-deployment.yaml,agent 容器的 env:
env: - name: OPENAI_BASE_URL value: http://envoy-envoy-gateway-system-edge-06431a46.envoy-gateway-system.svc.cluster.local:80/v1 - name: MODEL value: assistant - name: CREWAI_ALLOW_DELEGATION value: "false" - name: CREWAI_BACKSTORY value: a help-desk agent answering customers - name: CREWAI_GOAL value: answer questions about the product - name: CREWAI_LOG_LEVEL value: DEBUG - name: CREWAI_ROLE value: support assistantagent 读取网关发布的两个键,它们正是模型所发布的那两个键,因此其 Recipe 像读取模型的键一样读取它们。CREWAI_ 变量携带 agent 自身的值,使用 CrewAI Component 默认赋予它们的名称。地址是 Envoy Gateway 为网关数据平面创建的 Service,以网关的命名空间、名称以及二者的哈希命名,并用 envoy-gateway-system 限定,因此可以从 agent 的命名空间解析。模型名称是别名 assistant;路由将指定该名称的请求发送到模型的后端,并改为请求 gpt-4o-mini。
后端通过模型发布的端点访问 OpenAI:
models.yaml 包含一个指向 api.openai.com 端口
443 的 Envoy Gateway Backend、一个根据系统信任锚校验其证书的 TLS 策略、一个用于 /v1 下 OpenAI API 的 AIServiceBackend,以及提供密钥的安全策略 edge-assistant,其 spec 为:
spec: targetRefs: - group: aigateway.envoyproxy.io kind: AIServiceBackend name: edge-assistant type: APIKey apiKey: secretRef: name: "openai-api-key"控制器从网关命名空间中的该 Secret 读取数据键 apiKey 下的密钥,并将其作为 bearer token 发送给 OpenAI,因此任何渲染出的文件都不包含它,agent 也从不持有它。网关通过控制器发布的地址调用控制器,该地址用 Release 放置控制器的命名空间限定——即上面的 extensionManager 块。在接入模型期间,网关还会采用 Envoy AI Gateway 的客户端流量策略,即 models.yaml 中的 edge-client-buffer-limit,将每个传入连接允许的缓冲区提高到 50Mi;该策略以网关为目标,因此适用于挂接到网关的每条路由。
网关在运行时做什么
对于每个模型请求,网关都会询问限流服务本月到目前为止计费的 token 数是否超过 limit。一旦超过,网关会以 HTTP 429 响应模型请求,直到当月结束。一个请求的 token 在其回复完成后才会计入,因此越过上限的那个请求仍会得到服务,与它同时得到响应的任何请求也是如此。当存储或限流服务无法访问,或者一次检查耗时超过 Envoy 的限流超时时,网关会依据上文的 failClosed 设置以 HTTP 500 拒绝模型请求,因此在计数无法检查期间,不会放行任何模型请求。
由此产生的以下结果属于产品本身的行为,而非配置:
- 在故障发生前刚被放行的请求仍会得到服务,且不会被计数。 其 token 在回复之后才计费,因此在存储或服务无法访问时完成的回复不会给计数增加任何值。
- 在内存中保存计数的存储在重启时会让每个窗口重新开始。
core/datastore/redis默认将其条目保存在内存中,因此重启后的存储会丢失到目前为止保存的计数,当月剩余时间将从零开始计数。 - 未报告用量的回复不会增加任何计数。 计数就是每个回复所报告的用量;对于流式回复,Envoy AI Gateway 也会要求模型在回复结束时报告其用量。
什么会中止构建
以下每一项都是构建打印的一句话,指明需要修改什么:
-
以美元计的成本。 在附件中设置
unit: usd,构建会在任何内容渲染之前中止:[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "period-budget-envoy-gateway" instance "edge" assertion "unit_is_a_token_count": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/period-budget attachment "budget" on "edge" asks for unit usd, but core/gateway/envoy-gateway, which declares dataplane.aggrega.ai/period-budget: tokens, counts the tokens each model's reply reports and prices nothing, so it keeps no budget in US dollars; set unit to total_tokens, prompt_tokens or completion_tokens, or attach the Feature to a gateway that counts cost -
按调用方的预算,
scope: caller。网关只能通过调用方自己写入的请求头来区分调用方,而这条路径上没有任何环节验证调用方的身份,因此发送新值的调用方会开启一份新的预算,而不发送该值的调用方则不会被计数。 -
网关没有对应窗口的任何周期。 它保留其速率限制的一个完整单位:
1s、1m、1h、1d、7d、30d、365d或1mo,或以其他写法表示的相同时长,如24h。2h、14d或2mo会中止构建。 -
不是整数个 token 的限额,或大于 4294967295 的限额。
-
网关上的第二个
core/period-budget附件,它会把一份预算写到为其模型提供服务的路由上。 -
models插槽上未连接任何内容,这样就没有可计数的模型路由;或cache插槽上未连接任何内容,这样计数就无处存放。如果只移除模型的连接,网关自身的 Component 会先中止,原因是values.model指定了一个没有任何服务提供的别名。 -
cache插槽上不使用 Redis 协议的存储——即发布的协议不是redis或valkey的存储。 -
网关被放置在
envoy-gateway-system之外,而控制器连接在其extension插槽上。
应用之前
该树不包含 Namespace,也不包含 Secret,因此接收
dist/helm/ 的集群需要:
- 命名空间
cert-manager、envoy-ai-gateway-system、envoy-gateway-system和assistant。 - 位于
envoy-gateway-system中的 Secret:openai-api-key, 在数据键apiKey下保存 OpenAI 的密钥;以及counter-store-password, 在password下保存存储的密码。引用不存在的 Secret 的 workload 不会启动。 - 对其中两个 AI Gateway 定义使用服务器端应用(server-side apply):
aigateway.envoyproxy.io_backendsecuritypolicies.yaml和aigateway.envoyproxy.io_mcproutes.yaml。它们大于客户端应用(client-side apply)所记录的已应用对象副本, 因此客户端应用会拒绝它们。 - 智能体的镜像。 该 Release 指定了
registry.example/crew-assistant:1.0.0;目录打包的是智能体 运行时,而它运行的 crew 是你自己的代码。
编译器不做解释的地方
编译器将限额、单位和 token 成本以字符串形式传入网关的资源,并依据模型的端点、存储的地址和控制器的地址各自发布的内容将它们传入。它不会访问 OpenAI,不知道某个回复是否报告其 token 数,自身也不计数任何东西;它不检查这些 Secret 是否存在,也不检查 cert-manager 是否在运行。上面的每一种中止都由 catalog 自身的实体声明,作为预算实现中或网关的 Component 或 Recipe 中的断言,且其中没有一项依赖于对流量的任何理解。
改编示例
- 每个模型一个限额。 将更多模型连接到
models插槽并设置scope: model:每个模型都会获得各自的规则和计数。 - 只计一侧。 设置
unit: prompt_tokens以计算模型读取的内容, 或设置completion_tokens以计算模型写出的内容。 - 重新发送失败的请求。 将
core/retry-policy附加到网关, 设置max_attempts,并在 Manifest 中将其映射到helm/retry-policy-envoy-gateway:同一个流量策略edge-models会在速率限制旁增加一个retry,因为 Envoy Gateway 只为一条路由附加 一个流量策略。 - 更短或固定长度的窗口。 在 Release 中将
period设置为 上述长度之一:1d是从 UTC 00:00 起的一天,30d是从 1970 年 1 月 1 日起计算的 30 天, 而不是一个日历月。若周期不是1mo, 配置不会设置日历月选项。 - MCP 路由。 控制器使用一个密钥加密 MCP 会话标识符,该密钥
派生自
ai-controller上infra.mcp_session_seed_secret所指定 Secret 中的种子; 若未指定(如本例),种子为其 chart 公开的 默认值,因此在通过它提供 MCP 路由之前,请先指定一个。