配置 Token 配额

简介

Envoy AI Gateway 可以根据 token 使用量 而不是请求次数进行限流,并基于身份为每个调用方分别跟踪预算。这可以防止单个消费者或失控的智能体耗尽共享的模型预算,并且让你能够在一个 gateway 上提供按用户、按部门以及按层级划分的 token 配额。

一个 token 配额由三部分组成:

  • AIGatewayRoute.llmRequestCosts 会将每个 LLM 响应中的 token 计数提取到 Envoy 动态元数据中。
  • 全局限流后端(Redis)负责累积该成本。由于 token 成本只能在响应之后才知道,因此无法由每个 Pod 的本地限流器来跟踪。
  • 类型为 Global 的 BackendTrafficPolicy 定义预算和身份键。

使用场景

  • 为每个用户在昂贵模型上分配月度 token 预算,并为高级层级提供更高预算。
  • 限制某个部门在其所有应用中可消耗的 token 总量。
  • 保护共享模型免受单个异常自动化账户的影响。

前提条件

  1. 已安装 Envoy AI Gateway,并且存在一个路由到模型后端的 AIGatewayRoute。确认相关 CRD 已就绪:

    kubectl get crd \
      aigatewayroutes.aigateway.envoyproxy.io \
      backendtrafficpolicies.gateway.envoyproxy.io
  2. 调用方身份通过请求头传递,例如 x-user-id。请参阅 Authenticating Consumers。如果没有身份头,下面的预算会退化为所有调用方共享的单个计数器,因此这一步是实现 按消费者 配额的关键。

  3. 已有可用的 Redis 实例。使用来自 Cache Service for Redis 的托管实例作为默认提供程序,然后记录其访问地址(host:port)和凭证。在继续之前,请先验证集群能够访问它:

    # On clusters without docker.io egress (air-gapped / mirror-only), replace
    # redis:7-alpine with a Redis image from your registry mirror (it ships redis-cli).
    kubectl run redis-probe --rm -i --restart=Never \
      --image=redis:7-alpine -- \
      redis-cli -h <redis-host> -p <redis-port> PING
    # expect: PONG
  4. 记录 Gateway 的名称和命名空间——后续重启正确的数据平面代理时需要用到:

    kubectl get gateway -A
NOTE

请将 Gateway 和 AIGatewayRoute 创建在专用命名空间中(例如 maas-system),而不是 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中。放置在控制平面命名空间中的 gateway 可能不会将 AI Gateway 请求处理过滤器和 SecurityPolicy 应用到其 listener,从而会静默破坏路由和策略执行。请参阅 Envoy AI Gateway。

步骤

启用全局限流后端

本地限流器无法累积来自响应的 token 成本,因此 gateway 必须使用由 Redis 支持的 Global Rate Limit 服务。请从 Cache Service for Redis 创建一个 Redis 实例,并从实例详情页复制其访问地址。然后将该地址设置到 envoy-gateway-config ConfigMap(命名空间 envoy-gateway-system)中的 data."envoy-gateway.yaml" 下:

kubectl edit configmap envoy-gateway-config -n envoy-gateway-system

在顶层配置下添加 rateLimit 块(保留现有键,例如 gateway: 和 provider: 不变):

rateLimit:
  backend:
    type: Redis
    redis:
      url: <redis-host>:<redis-port>  # access address of the Redis instance
      # tls:                          # uncomment if Redis requires TLS
      #   certificateRef:
      #     name: redis-client-cert
  • <redis-host>:<redis-port>:从 Redis 实例详情页复制的访问地址。
  • 对于启用了密码保护的 Redis,请使用标准 Redis URI 形式将凭证嵌入 URL:url: redis://<username>:<password>@<redis-host>:<redis-port>(仅密码认证时省略 <username>:)。Envoy Gateway v1.5.x 在 rateLimit.backend.redis 下仅暴露 url 和 tls.certificateRef,没有单独基于 Secret 的认证字段。因此,凭证会存放在 envoy-gateway-config ConfigMap 中,请限制其读取权限,或者改用网络隔离 / ACL 受限的 Redis。完整 schema 请参阅 Envoy Gateway rate-limit docs。

Envoy Gateway 控制平面只在启动时读取这份 bootstrap 配置,不会热加载,因此请重启其 Deployment 以应用更改,然后确认专用的 envoy-ratelimit Deployment 运行正常:

kubectl rollout restart deployment envoy-gateway -n envoy-gateway-system
kubectl rollout status  deployment envoy-gateway   -n envoy-gateway-system
kubectl rollout status  deployment envoy-ratelimit -n envoy-gateway-system
# the envoy-ratelimit Deployment is created by the EG controller the first time
# rateLimit.backend is set; if it never appears, the config above was not parsed
NOTE

对于每个 Envoy Gateway,单个 Redis 实例即可满足需求。任何可达的 Redis 都可以使用,但为了可用性和备份,建议使用托管实例。

如果在启用限流后端之前 gateway 已经在运行,还需要重启其数据平面,以便代理加载限流服务:

kubectl rollout restart deployment -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>

在 route 上捕获 token 使用量

将 llmRequestCosts 添加到 AIGatewayRoute,使 gateway 将 token 计数写入 Envoy dynamic metadata(过滤器用于相互通信的每请求临时空间)中的 io.envoy.ai_gateway 命名空间。下一步的 rate-limit filter 会从这个命名空间读取数据。

apiVersion: aigateway.envoyproxy.io/v1alpha1
kind: AIGatewayRoute
metadata:
  name: <aigatewayroute-name>
  namespace: <your-namespace>
spec:
  # ... existing parentRefs and rules ...
  llmRequestCosts:
    - metadataKey: llm_input_token
      type: InputToken
    - metadataKey: llm_output_token
      type: OutputToken
    - metadataKey: llm_total_token
      type: TotalToken
  • metadataKey:io.envoy.ai_gateway 下写入计数的键。名称可自定义;下面的 BackendTrafficPolicy 必须引用相同字符串。

  • type:InputToken 统计 prompt,OutputToken 统计 completion,TotalToken 为二者之和。自定义公式请使用 CEL —— 例如,输出 token 的计费按 3 倍计算,因为其处理更慢:

    - metadataKey: llm_weighted_cost
      type: CEL
      cel: "input_tokens + output_tokens * 3"

应用并确认 route 仍然被接受(新增字段不应影响转换):

kubectl get aigatewayroute <aigatewayroute-name> -n <your-namespace> \
  -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
# expect: True

按身份定义 token 预算

绑定一个带有 Global 限流的 BackendTrafficPolicy。将请求成本设为 0,响应成本设为捕获到的 token 元数据,这样只有 token 会计入限制。使用 clientSelectors 按身份和按模型来限定预算范围。

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: maas-token-quota
  namespace: <your-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: <aigatewayroute-name>
  rateLimit:
    type: Global
    global:
      rules:
        - clientSelectors:
            - headers:
                - name: x-user-id       # identity header from the SecurityPolicy
                  type: Distinct
                - name: x-ai-eg-model
                  type: Exact
                  value: my-llm
          limit:
            requests: 200000             # 200k tokens per window
            unit: Hour
          cost:
            request:
              from: Number
              number: 0                   # requests do not count
            response:
              from: Metadata              # tokens count
              metadata:
                namespace: io.envoy.ai_gateway
                key: llm_total_token
  • x-user-id 配合 type: Distinct 会为每个调用方提供独立计数器,从而形成按用户配额。可以使用 x-user-group 将某个部门聚合到同一预算,或者使用 type: Exact 匹配特定组(例如 premium)来实现分层限制。
  • 这里的 limit.requests 会被解释为 token 预算,因为成本来源于 token 元数据。若配置为 200000 tokens/hour,而一次典型聊天请求大约消耗 1.5–2k tokens,则在开始限流之前,每个调用方大约可发起 ~100–130 次请求/小时。
  • cost.request.number: 0 表示如果请求未能到达上游(例如请求体格式错误),则不会消耗配额。如果你也希望按调用次数进行预先限流,可将其设为 1。
  • cost.response.metadata.key 必须与 route 上声明的 metadataKey 匹配。

验证

使用有效的身份 token 连续发起一小段突发请求,然后再使用另一个身份发送请求,确认只有第一个身份被限流:

NOTE

对于上面现实中的 200000 tokens/hour 预算,少量单词级别请求消耗的配额远低于 1%,因此它们都会返回 200,你不会观察到 429。如果想在短演示中看到限流效果,可以临时缩小预算——在 BackendTrafficPolicy 中将 limit.requests 设为 200 并将 unit 设为 Minute,重新应用后,再重启数据平面代理(kubectl rollout restart deployment -n envoy-gateway-system -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>)。演示通过后,再恢复真实预算。或者,也可以保留生产预算,同时发送几百个带较大 prompt 和较长 max_tokens 的请求。

下面的验证使用 JWT 头 Authorization: Bearer。如果你改用了 API-key 认证(请参阅 Authenticating Consumers → "Authenticate with an API key"),gateway 会从专用的 X-API-Key 头中读取凭证——请将每个 -H "Authorization: Bearer $TOKEN_…" 替换为 -H "X-API-Key: $TOKEN_…"。

GATEWAY='http://<gateway-address>'
TOKEN_ALICE='<alice-jwt-or-api-key>'
TOKEN_BOB='<bob-jwt-or-api-key>'

# With the demo budget above (200 tokens/minute), expect early 200s then 429 once it is used.
for i in $(seq 1 8); do
  curl -s -o /dev/null -w "alice #$i -> %{http_code}\n" \
    -H "Authorization: Bearer $TOKEN_ALICE" \
    -H 'Content-Type: application/json' \
    -d '{"model":"my-llm","messages":[{"role":"user","content":"hi"}]}' \
    $GATEWAY/v1/chat/completions
done

# Same model, different user — must succeed because the budget is per x-user-id.
curl -s -o /dev/null -w "bob       -> %{http_code}\n" \
  -H "Authorization: Bearer $TOKEN_BOB" \
  -H 'Content-Type: application/json' \
  -d '{"model":"my-llm","messages":[{"role":"user","content":"hi"}]}' \
  $GATEWAY/v1/chat/completions

一次耗尽 alice 配额的运行通常会打印类似 alice #1 -> 200 … alice #5 -> 429 … bob -> 200 的结果。若要直接在 Redis 中查看计数器,请扫描包含身份值的 key——Envoy Gateway 为每个计数器命名为 <gateway-namespace>/<gateway-name>/<listener>_<route>_..._<x-user-id-value>_..._<window-timestamp>,因此用户身份是最简单的过滤条件:

# <alice-x-user-id-value>: the x-user-id value the SecurityPolicy injects for alice
# (the JWT claim / API-key mapping value that appears in the counter key), not her token.
# Air-gapped clusters: replace redis:7-alpine with a mirrored Redis image.
kubectl run redis-cli --rm -i --restart=Never \
  --image=redis:7-alpine -- \
  redis-cli -h <redis-host> -p <redis-port> \
  --scan --pattern "*<alice-x-user-id-value>*" | head
WARNING

如果 Redis 不可达,Envoy 默认会 fail open:请求会在不计费的情况下继续通过,直到 Redis 恢复。请监控 rate-limit pod 的日志(kubectl logs deploy/envoy-ratelimit -n envoy-gateway-system),并对其 Ready 状态发出告警,以免静默丢失配额而不被发现。

了解更多

下一步

配置 Metering Token Usage 以按租户报告消耗量并用于成本分摊。