配置令牌配额

简介

Agent Router 可以根据令牌使用量而不是请求数进行限流,并根据调用方身份为每个调用方跟踪独立的预算。这可以防止单个使用者或失控的智能体耗尽共享模型预算,还可以让你在一个网关上提供按用户、按部门和按层级划分的令牌配额。

令牌配额由以下三个部分组成:

  • AIGatewayRoute.llmRequestCosts 从每个 LLM 响应中提取令牌计数,并写入 Envoy 动态元数据。
  • 全局限流后端(Redis)累积消耗量。由于令牌消耗量只有在响应之后才能确定,因此无法由每个 Pod 的本地限流器进行跟踪。
  • 类型为 Global 的 BackendTrafficPolicy 定义预算和身份密钥。

使用场景

  • 为每个用户在高成本模型上分配每月令牌预算,并为高级层级提供更高的预算。
  • 限制一个部门在其所有应用中可消耗的令牌总数。
  • 防止单个运行异常的自动化账户影响共享模型。

前提条件

  1. 已安装 Alauda AI Platform Gateway,并且有一个将请求路由到模型后端的 AIGatewayRoute。确认相关 CRD 存在:

    kubectl get crd \
      aigatewayroutes.aigateway.envoyproxy.io \
      backendtrafficpolicies.gateway.envoyproxy.io
  2. 调用方身份通过请求标头传递,例如 x-user-id。请参阅对使用者进行身份验证。如果没有身份标头,下面的预算会合并为由所有调用方共享的单个计数器,因此此步骤是实现按使用者配额的关键。

  3. 有一个可用的 Redis 实例。默认情况下,使用 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

请在专用命名空间(例如 maas-system)中创建 Gateway 和 AIGatewayRoute,不要在 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中创建。放置在控制平面命名空间中的网关可能不会在其监听器上应用 AI Gateway 请求处理过滤器和 SecurityPolicy,从而导致路由和策略执行静默失效。请参阅 Alauda AI Platform Gateway。

步骤

启用全局速率限制后端

本地速率限制器无法累积从响应中派生的令牌成本,因此网关必须使用由 Redis 支持的 Global Rate Limit 服务。从 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。完整架构请参阅 Envoy Gateway 速率限制文档。

Envoy Gateway 控制平面仅在启动时读取此引导配置,不会热加载,因此请重启其 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>

在路由上捕获令牌使用量

将 llmRequestCosts 添加到 AIGatewayRoute,使网关将令牌计数写入 Envoy 动态元数据(过滤器用于彼此通信的每请求临时存储空间)中的 io.envoy.ai_gateway 命名空间。速率限制过滤器将在下一步中从此命名空间读取数据。

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 统计提示词,OutputToken 统计补全内容,TotalToken 是两者之和。使用 CEL 可指定自定义公式——例如,由于输出令牌处理速度较慢,将其按 3 倍计费:

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

应用更改并确认路由仍被接受(新字段不应导致转换失败):

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

按身份定义令牌预算

附加一个带有 Global 速率限制的 BackendTrafficPolicy。将请求成本设置为 0,将响应成本设置为捕获的令牌元数据,这样只有令牌会计入限制。使用 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 在此处会被解释为令牌预算,因为成本来源于令牌元数据。使用每小时 200000 个令牌,并假设一次典型聊天调用的成本约为 1.5–2k 个令牌,则在触发限流前,每个调用方预计每小时可调用约 100–130 次。
  • cost.request.number: 0 表示未能到达上游的请求(例如请求正文格式错误)不会消耗配额。如果还希望对调用次数执行预检限流,请将其设置为 1。
  • cost.response.metadata.key 必须与路由上声明的 metadataKey 匹配。

验证

使用有效的身份令牌短时间连续发送请求,然后使用另一个身份发送请求,并确认只有第一个身份受到限流:

NOTE

对于上述现实的每小时 200000 个令牌预算,少量单词请求消耗的配额远低于 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>)。演示通过后,请恢复实际预算。或者,保留生产环境预算,并使用较大的提示词和较长的 max_tokens 发送数百次请求。

以下验证使用 JWT 标头 Authorization: Bearer。如果配置的是 API 密钥身份验证(对消费者进行身份验证 →“使用 API 密钥进行身份验证”),网关会从专用的 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 中检查计数器,请扫描包含身份值的键——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 恢复。请监视速率限制 Pod 的日志(kubectl logs deploy/envoy-ratelimit -n envoy-gateway-system),并针对其 Ready 状况配置告警,避免配额悄然丢失而未被发现。

了解更多

后续步骤

配置计量令牌用量,以报告每个租户的消耗情况并用于费用分摊。