跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

位于 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它在此处的角色
edgecore/gateway/envoy-gateway网关,从模型 chat 提供一个别名 assistant
ai-controllercore/gateway/envoy-ai-gateway-operatorEnvoy AI Gateway 的控制器,网关将其作为扩展服务器调用,随六个 AI Gateway 资源定义一起安装
chatcore/ai-model/openaiOpenAI 的 gpt-4o-mini,以引用的方式访问:集群中不为它运行任何内容
counterscore/datastore/redis网关的限流服务在其中保存预算计数的存储
assistantcore/ai-agent/crewai一个将模型请求发往网关的代理
certscore/security/cert-managercert-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 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example envoy-ai-gateway-token-budget

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd envoy-ai-gateway-token-budget

构建

Terminal window
aggrega build --release release.yaml --auto-pull

release 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:

Terminal window
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flag
aggrega 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/v1beta1
kind: AIGatewayRoute
metadata:
[… 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/v1alpha1
kind: BackendTrafficPolicy
metadata:
[… 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/v1alpha1
kind: EnvoyGateway
extensionApis:
enableBackend: true
enableEnvoyPatchPolicy: true
extensionManager:
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: 1063
gateway:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
logging:
level:
default: info
provider:
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: Kubernetes
rateLimit:
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 assistant

agent 读取网关发布的两个键,它们正是模型所发布的那两个键,因此其 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 assertions
    caused 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 路由之前,请先指定一个。