API Key 与模型限流

限流可以保护模型服务提供方容量，并防止单个调用方或模型耗尽共享配额。当配额属于某个调用方时，请在调用方 API Key 上配置限制；当使用某个模型的所有调用方应共享配额时，请在模型上配置限制。

这些限制属于其所配置的 API Key 或模型。限流策略是独立规则，可以匹配团队、成员、API Key、模型、模型名称或模型服务提供方，并把匹配流量划分到彼此独立的配额桶中。同一请求可以同时匹配 API Key 限制、模型限制和策略。每个匹配的限制都会生效；只要有任一配额桶耗尽，网关就会在调用模型服务提供方之前返回 429。

本指南介绍如何在 API Key 和模型上配置限制、验证限制是否生效，以及选择共享计数器存储。AISIX Cloud 和开源 AISIX 网关通过不同的管理路径提供相同能力。

准备工作

开始前，请准备以下内容：

• 可以发送代理请求的模型别名和调用方 API Key。如果尚未配置，请参阅模型服务提供方密钥、模型别名和调用方 API Key。
• 对于 AISIX Cloud：已接入网关的环境，以及具有写权限范围的 Admin Token。可以按照 AISIX Cloud 快速入门进行本地评估；如需申请混合云访问权限，请联系 API7。
• 对于开源 AISIX 网关：可验证并重新加载的声明式资源文件。参见重新加载资源文件。

导出用于验证本页任一示例的网关请求参数：

# AISIX_PROXY 末尾不包含斜杠或 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_MODEL="gpt-4o-prod"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

对于 AISIX Cloud 示例，还需导出控制平面连接参数及待限制资源的 ID：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
# API_KEY_ID 标识明文值为 AISIX_API_KEY 的调用方 Key。
export API_KEY_ID="YOUR_CALLER_API_KEY_ID"
# MODEL_ID 标识别名为 AISIX_MODEL 的模型。
export MODEL_ID="YOUR_MODEL_ID"

选择限流配置方式

可以通过两种方式配置限流：

• 把 rate_limit 块直接关联到调用方 API Key 或模型。当某个应用或租户需要独立配额时使用调用方限制；当某个别名的所有调用方应共享配额时使用模型限制。
• 当需要单独管理的配额、条件匹配，或需要为团队、成员、API Key、模型或模型服务提供方创建独立配额桶时，请创建限流策略。

调用方 API Key 还可以为其调用的每个 MCP 服务器设置单独的请求数和并发限制。参见 MCP 限流与预算。

每个匹配的限制都会生效。例如，一个请求可以同时占用调用方 API Key、解析后的模型、团队策略和成员策略中的容量。只有所有匹配的配额桶都有剩余容量，请求才会继续。

配置调用方 API Key 限制

以下示例把一个调用方 API Key 限制为每分钟一次请求。

AISIX Cloud

在控制台中打开 API keys，展开调用方 API Key，然后使用其中的 Rate limits 控件。Admin API 为自动化提供相同配置能力。

更新调用方 API Key，为其设置每分钟一次请求的限制：

curl -sS -X PATCH "${AISIX_CP}/environments/${ENV_ID}/api_keys/${API_KEY_ID}" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit": {
      "rpm": 1
    }
  }'

更改会自动投射到已接入的网关。

开源 AISIX 网关

在声明式资源文件已有的调用方 API Key 条目中添加相同限制，并保留其当前的 display_name、key_env 和 allowed_models。以下示例使用调用方 API Key 指南中的值：

resources.yaml

api_keys:
  - display_name: chat-app
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-prod
    rate_limit:
      rpm: 1

让验证命令可以访问调用方凭证：

# 使用与验证请求相同的明文值。
export CALLER_API_KEY="${AISIX_API_KEY}"

如果 AISIX 安装在主机上，请在重新加载网关之前验证完整资源文件：

aisix validate --resources resources.yaml

对于开源快速入门中的 Docker 环境，请使用基于容器的验证和重新加载命令。快速入门已让容器可以访问 CALLER_API_KEY。

配置模型限制

当某个别名的所有调用方都应共享同一配额时，请使用模型限制。以下示例允许使用 gpt-4o-prod 的所有调用方 API Key 每分钟总计发送一次请求。

AISIX Cloud

在控制台中打开 Models，编辑模型，然后使用 Rate limits 字段。Admin API 为自动化提供相同配置能力。

更新模型：

curl -sS -X PATCH "${AISIX_CP}/environments/${ENV_ID}/models/${MODEL_ID}" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_limit": {
      "rpm": 1
    }
  }'

开源 AISIX 网关

在直接模型条目中添加限制，并保留已有的模型服务提供方和密钥设置：

resources.yaml

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-prod
    rate_limit:
      rpm: 1

验证完整资源文件并重新加载网关。此后，使用不同调用方 API Key 的请求会从同一个模型配额桶中扣减容量。

验证限流

前面的调用方和模型示例都使用每分钟一次请求的限制。请一次只配置并测试一个直接限制，以便 429 响应能明确指向所测试的限制。也可以用相同的请求序列验证限流策略。

等待 AISIX Cloud 更改到达网关，或重新加载开源资源文件后，发送三个请求：

for i in 1 2 3; do
  printf "request %s: " "${i}"
  curl -sS -o /dev/null -w "%{http_code}\n" -X POST "${AISIX_PROXY}/v1/chat/completions" \
    -H "Authorization: Bearer ${AISIX_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
    {
      "model": "${AISIX_MODEL}",
      "messages": [
        {
          "role": "user",
          "content": "Hello from AISIX."
        }
      ]
    }
EOF
done

第一个请求应到达上游模型。同一固定窗口内的其余请求应超过限制：

request 1: 200
request 2: 429
request 3: 429

兼容 OpenAI 的限流拒绝会返回 429 Too Many Requests，并使用代理错误格式：

{
  "error": {
    "message": "request limit exceeded (requests)",
    "type": "rate_limit_exceeded"
  }
}

请求计数和 Token 限制的拒绝会包含 Retry-After，因为它们的固定窗口具有重置时间。并发拒绝没有基于窗口的重试提示。成功的 Chat Completions 响应还可以包含调用方 Key 的限流状态；参见响应头和错误码。

限流字段与计数器行为

调用方 API Key 和模型别名使用相同的 rate_limit 字段。每个字段都是可选的；省略某个字段时，AISIX 不会执行相应维度的限制。

字段	限制	固定窗口
rps	每秒请求数	1 秒
rpm	每分钟请求数	60 秒
rph	每小时请求数	3,600 秒
rpd	每日请求数	86,400 秒
tpm	每分钟 Token 数	60 秒
tpd	每日 Token 数	86,400 秒
concurrency	进行中的请求数	无窗口

AISIX 在处理请求的不同时点检查并记录三种限制维度：

维度	AISIX 检查时点	AISIX 记录用量时点
请求计数	调用模型服务提供方之前	在调用前检查期间；较早匹配的层可能已增加计数，随后请求才被较晚的层拒绝
Token	调用模型服务提供方之前，依据当前窗口中已记录的 Token	上游响应报告用量之后
并发	调用模型服务提供方之前	持有到响应或流结束，然后释放

Token 限制包含提示词和生成结果 Token。对于 Anthropic 流量，还包含 Anthropic 与输入 Token 分开报告的提示词缓存创建和缓存读取 Token。OpenAI 缓存 Token 已包含在提示词 Token 中，因此 AISIX 不会重复计数。

由于模型服务提供方在生成响应后才报告用量，跨过 Token 限制的请求可能成功完成。它的 Token 用量可能耗尽当前窗口，导致后续请求被拒绝。

直接关联到调用方 API Key 或模型的 Token 限制只支持分钟和日窗口，这些资源没有每秒或每小时 Token 字段。经典限流策略仅在分钟窗口中执行 Token 上限。AISIX Cloud 会拒绝使用其他窗口的 Token 上限。对于开源 AISIX 网关，资源 Schema 虽接受这些配置，但运行时不会执行相应上限。

模型限制的应用方式

如果请求同时匹配调用方限制和模型限制，AISIX 会在两个配额桶中预留容量。任一配额桶耗尽都会拒绝请求。

当直接模型作为路由模型或语义路由的目标时，模型限制同样适用。路由分发会跳过超出自身限制的目标并继续尝试其余目标；所有目标都超出限制时，请求返回 429。语义分发会执行所选目标的限制；该目标没有容量时返回 429。对同一模型的直接请求和路由请求共享其限制配额桶。

当模型服务提供方透传请求正文以模型别名或服务提供方原生名称指定模型时，模型限制也会适用。透传与建模路由共享同一限制配额桶，并执行请求计数和并发限制。透传会原样转发响应正文，不解析模型服务提供方报告的 Token 用量，因此 tpm 和 tpd 不会计入透传流量。但耗尽的 Token 窗口仍会拒绝透传请求，直到窗口重置。

选择限流计数器存储

网关启动配置决定限流计数器是某个进程本地独享，还是由多个网关实例共享。此设置同时适用于直接关联到资源的限制和该网关执行的可复用策略。

后端	计数器作用域	适用场景
Memory（默认）	单个网关进程	由单实例执行限制，或可接受每个实例分别计算配额。
Redis	使用同一 Redis 后端的所有网关实例	部署必须执行同一个共享请求数、Token 或并发配额。

使用 Memory 后端时，每个网关实例只统计自己处理的流量。因此，在流量均匀分发的多实例部署中，一个窗口内总体放行的流量可能超过所配置的单进程限制。固定路由可以减少同一调用方或租户的这种差异，但 Redis 才是共享计数器方案。

当多个网关实例必须执行同一配额时，请配置 Redis：

config.yaml

ratelimit:
  backend: redis
  redis:
    mode: single
    url: redis://127.0.0.1:6379/

当 ratelimit.backend 为 redis 时，网关要求提供 ratelimit.redis 块。缺少所选 Redis 配置或无法连接 Redis 时，启动会失败。

成功启动后，如果 Redis 随后中断，限流会降级为进程本地计数器。请求仍受各进程限制保护，但中断期间部署不会执行统一的集群级配额。中断期间的计数不会复制回 Redis，因此恢复后，在当前活动窗口结束之前，各计数器可能仍不一致。

使用 Redis 的并发槽位会在请求完成时释放。concurrency_ttl_secs 用于回收实例崩溃或请求中断后遗留的槽位，默认值为 300 秒。

Redis 连接模式

ratelimit.redis.mode 字段用于选择 Redis 部署类型，并决定必须提供哪些连接字段。前面的示例使用带单个 url 的 single 模式。

对 Redis Cluster 种子节点使用 cluster：

config.yaml

ratelimit:
  backend: redis
  redis:
    mode: cluster
    nodes:
      - redis://10.0.0.1:6379/
      - redis://10.0.0.2:6379/

对由 Sentinel 管理的主节点使用 sentinel：

config.yaml

ratelimit:
  backend: redis
  redis:
    mode: sentinel
    sentinels:
      - redis://10.0.0.1:26379/
      - redis://10.0.0.2:26379/
    master_name: mymaster

各模式必需的字段如下：

模式	必需连接字段
single	url
cluster	一个或多个 nodes 条目
sentinel	一个或多个 sentinels 条目及 master_name

在 Cluster 和 Sentinel 模式中，当 Redis 数据节点需要 ACL 身份认证时，请设置 username 和 password。在 Sentinel 模式中，Sentinel 节点凭证写在 Sentinel URL 中，而 username、password 和 database 应用于发现到的 Redis 主节点。

故障排除

先确定被拒绝请求的作用域，再找出所有可能匹配它的限制。

现象	检查项
已配置的限制未生效。	对于 AISIX Cloud，确认更改已投射到网关。对于开源网关，确认资源文件已重新加载。然后验证请求使用了预期的调用方 API Key 和模型。
请求在尚未达到预期调用方限制时被拒绝。	检查是否存在匹配该 API Key、模型、团队、成员或模型服务提供方的模型限制和限流策略。每个匹配层都必须通过。
多个网关实例的总体流量超过配置限制。	检查 ratelimit.backend。Memory 后端在每个进程中维护独立计数器；如需统一共享配额，请使用 Redis。
受 Token 限制的请求成功，但下一个请求被拒绝。	这是成功响应耗尽剩余 Token 容量时的预期行为。Token 用量会在模型服务提供方报告后记录。

后续步骤

当直接调用方限制和模型限制不够灵活时，请配置限流策略。继续配置响应缓存以复用符合条件的 Chat Completions 响应，或查看指标以监控限流拒绝。