AI Rate Limiting | Apache APISIX 与 API7 网关插件文档

参数

有关所有插件均可使用的配置项，请参阅插件通用配置。

备注

在 API7 企业版 3.8.17 及更高版本和 Apache APISIX 3.16.0 及更高版本中，请配置以下两组参数之一，不要同时配置：

rules
limit、time_window 和/或 instances 的任意组合

limit
integer | string
有效值：
大于 0
指定时间间隔内允许消耗的最大 Token 数量。
在 API7 企业版（自 3.8.17 起）和 APISIX（自 3.16.0 起）中，此参数还支持字符串类型，并允许使用以美元符号（$）为前缀的内置变量。较早的 APISIX 版本仅支持整数类型。
time_window
integer | string
有效值：
大于 0
对应于速率限制 limit 的时间间隔，以秒为单位。
在 API7 企业版（自 3.8.17 起）和 APISIX（自 3.16.0 起）中，此参数还支持字符串类型，并允许使用以美元符号（$）为前缀的内置变量。较早的 APISIX 版本仅支持整数类型。
show_limit_quota_header
boolean
默认值：true
如果为 true，则包含速率限制响应头。具体而言，使用 limit/time_window 或 instances 时，响应头以实例名称作为后缀：
- X-AI-RateLimit-Limit-{name} 显示总配额。
- X-AI-RateLimit-Remaining-{name} 显示剩余配额。
- X-AI-RateLimit-Reset-{name} 显示计数器重置前的剩余秒数。
设置 rules 后，响应头改用前缀。有关详细信息，请参阅 rules.header_prefix。
limit_strategy
string
默认值：total_tokens
有效值：
total_tokens、prompt_tokens、completion_tokens 或 expression
应用速率限制的 Token 类型。total_tokens、prompt_tokens 和 completion_tokens 值在每个模型响应中返回，其中 total_tokens 是 prompt_tokens 和 completion_tokens 的总和。
当设置为 expression 时，使用 cost_expr 中定义的自定义 Lua 算术表达式计算限速成本。自 API7 企业版 3.9.8 和 APISIX 3.17.0 起可用。
cost_expr
string
有效值：
任意非空字符串（必须是有效的 Lua 算术表达式）
用于动态 Token 成本计算的 Lua 算术表达式。变量从 LLM 提供者的原始 usage 响应字段注入（如 input_tokens、output_tokens、cache_creation_input_tokens）。缺失的变量默认为 0。仅允许 math 函数（abs、ceil、floor、max、min）和算术运算符。表达式语法在配置时校验。当 limit_strategy 为 expression 时必填，其他情况下不得设置。
示例：input_tokens + cache_creation_input_tokens 根据 Anthropic Claude 的缓存感知 Token 用量计算成本。
自 API7 企业版 3.9.8 和 APISIX 3.17.0 起可用。
instances
array[object]
LLM 实例速率限制配置。
- name
  string
  必填
  LLM 服务实例的名称。
- limit
  integer | string
  必填
  有效值：
  大于 0
  指定时间间隔内允许消耗的最大 Token 数量。
  在 API7 企业版（自 3.8.17 起）和 APISIX（自 3.16.0 起）中，此参数还支持字符串类型，并允许使用以美元符号（$）为前缀的内置变量。较早的 APISIX 版本仅支持整数类型。
- time_window
  integer | string
  必填
  有效值：
  大于 0
  对应于速率限制 limit 的时间间隔，以秒为单位。
  在 API7 企业版（自 3.8.17 起）和 APISIX（自 3.16.0 起）中，此参数还支持字符串类型，并允许使用以美元符号（$）为前缀的内置变量。较早的 APISIX 版本仅支持整数类型。
rejected_code
integer
默认值：503
有效值：
介于 200 和 599 之间（含边界值）
当请求超过配额被拒绝时返回的 HTTP 状态码。
rejected_msg
string
有效值：
任意非空字符串
当请求超过配额被拒绝时返回的响应体。
policy
string
默认值：local
有效值：
local、redis、redis-cluster 或 redis-sentinel
速率限制计数器的策略。API7 网关要求配置此字段；不使用 Redis 时请设置为 local。APISIX 在省略此字段时使用 local。
Redis 后端策略自 API7 企业版 3.8.19 和 APISIX 3.18.0 起可用。
设置为 local 以将计数器存储在本地内存中。
设置为 redis 以将计数器存储在 Redis 实例上。
设置为 redis-cluster 以将计数器存储在 Redis 集群中。
设置为 redis-sentinel 以将计数器存储在由 Redis Sentinel 管理的 Redis 主节点上，这通过在故障情况下自动将副本提升为主节点来确保高可用性。Redis Sentinel 在不使用 Redis Cluster 时为 Redis 提供高可用性。
redis_host
string
Redis 节点的地址。当 policy 为 redis 时必填。
redis_port
integer
默认值：6379
有效值：
大于或等于 1
当 policy 为 redis 时 Redis 节点的端口。
redis_username
string
如果使用 Redis ACL，则为 Redis 用户名。如果使用传统身份认证方法 requirepass，请仅配置 redis_password。当 policy 为 redis 时使用；在 API7 企业版 3.10.5 和 APISIX 3.18.0 中，也可与 redis-sentinel 一起使用。
redis_password
string
当 policy 为 redis 或 redis-cluster 时 Redis 节点的密码；在 API7 企业版 3.10.5 和 APISIX 3.18.0 中，也可与 redis-sentinel 一起使用。
在 API7 网关 3.10.x 系列的 3.10.2 及更高版本，以及 3.9.x 系列的 3.9.16 及更高版本中，该值在保存到数据库前会使用 AES256 加密。
在 APISIX 3.18.0 及更高版本中，该值在存储到 etcd 前会使用 AES 加密。
redis_database
integer
默认值：0
有效值：
大于或等于 0
当 policy 为 redis 或 redis-sentinel 时 Redis 中的数据库编号。
redis_ssl
boolean
默认值：false
如果为 true，则当 policy 为 redis 时使用 SSL 连接到 Redis。
redis_ssl_verify
boolean
默认值：false
如果为 true，则当 policy 为 redis 时验证服务器 SSL 证书。
redis_timeout
integer
默认值：1000
有效值：
大于或等于 1
当 policy 为 redis 或 redis-cluster 时 Redis 超时值（以毫秒为单位）。
redis_cluster_nodes
array[string]
Redis 集群节点列表，至少包含两个地址。当 policy 为 redis-cluster 时必填。
redis_cluster_name
string
Redis 集群的名称。当 policy 为 redis-cluster 时必填。
redis_cluster_ssl
boolean
默认值：false
如果为 true，则当 policy 为 redis-cluster 时使用 SSL 连接到 Redis 集群。
redis_cluster_ssl_verify
boolean
默认值：false
如果为 true，则当 policy 为 redis-cluster 时验证服务器 SSL 证书。
redis_sentinels
array[object]
Redis Sentinel 节点（主机和端口）的数组。当 policy 为 redis-sentinel 时必填。
redis_master_name
string
Sentinel 监控的 Redis 主组名称。当 policy 为 redis-sentinel 时必填。
redis_role
string
默认值：master
有效值：
master 或 slave
要连接的 Redis 节点角色。当 policy 为 redis-sentinel 时可配置。设置为 master 连接到当前 Redis 主节点，设置为 slave 连接到 Redis 副本。
redis_connect_timeout
integer
默认值：1000
有效值：
大于或等于 1
建立 Redis 节点连接的超时时间（以毫秒为单位）。当 policy 为 redis-sentinel 时可配置。
redis_read_timeout
integer
默认值：1000
有效值：
大于或等于 1
从 Redis 节点读取数据的超时时间（以毫秒为单位）。当 policy 为 redis-sentinel 时可配置。
redis_keepalive_timeout
integer
默认值：`redis` 或 `redis-cluster` 为 `10000`；`redis-sentinel` 为 `60000`
有效值：
对 redis 和 redis-cluster 大于或等于 1000；对 redis-sentinel 大于或等于 1
空闲 Redis 连接在连接池中保持存活、超过后关闭的时间（毫秒）。在 APISIX 3.18.0 中，所有 Redis 后端策略都会使用此字段。在 API7 企业版中，redis-sentinel 使用此字段；redis 和 redis-cluster 自 3.9.x 系列的 3.9.16 以及 3.10.x 系列的 3.10.3 起支持此字段。
redis_keepalive_pool
integer
默认值：100
有效值：
大于或等于 1
保活连接池中空闲 Redis 连接的最大数量。当 policy 为 redis 或 redis-cluster 时使用。自 API7 企业版 3.9.x 系列的 3.9.16、3.10.x 系列的 3.10.3 以及 APISIX 3.18.0 起可用。
sentinel_username
string
用于 Redis Sentinel 实例认证的用户名。当 policy 为 redis-sentinel 时可配置。
sentinel_password
string
用于向 Redis Sentinel 实例进行身份认证的密码。当 policy 为 redis-sentinel 时可配置。
在 API7 网关 3.10.x 系列的 3.10.2 及更高版本，以及 3.9.x 系列的 3.9.16 及更高版本中，该值在保存到数据库前会使用 AES256 加密。
在 APISIX 3.18.0 及更高版本中，该值在存储到 etcd 前会使用 AES 加密。
allow_degradation
boolean
默认值：false
如果为 true，则当插件或其依赖项不可用时，允许网关继续处理请求而不使用该插件。
自 API7 企业版 3.8.19 和 APISIX 3.18.0 起可用。
rules
array[object]
按顺序应用的一组速率限制规则。
自 API7 企业版 3.8.17 和 APISIX 3.16.0 起可用。
- count
  integer | string
  必填
  有效值：
  大于 0
  指定时间间隔内允许消耗的最大 Token 数量。
  此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。
- time_window
  integer | string
  必填
  有效值：
  大于 0
  对应于速率限制 count 的时间间隔，以秒为单位。
  此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。
- key
  string
  必填
  用于对请求计数的键。如果配置的键不存在，则不会执行该规则。
  key 被解释为变量。变量无需以美元符号（$）作为前缀。有关可用变量，请参阅内置变量。
- header_prefix
  string
  所有速率限制响应头的前缀。自 API7 企业版 3.8.19 和 APISIX 3.17.0 起可用。
  配置后，前缀将插入到头名称中的 X-AI- 之后。例如，将 header_prefix 设置为 test，则头变为 X-AI-Test-RateLimit-Limit、X-AI-Test-RateLimit-Remaining 和 X-AI-Test-RateLimit-Reset。
  如果未配置，则使用规则在规则数组中的索引作为前缀。例如，第一个规则的头将是 X-AI-1-RateLimit-Limit、X-AI-1-RateLimit-Remaining 和 X-AI-1-RateLimit-Reset。

参数​

参数