AI Rate Limiting | API 网关文档

参数

请参阅插件通用配置了解所有插件可用的配置选项。

备注

在 API7 企业版（从 3.8.17 开始）中，你应该配置以下参数集之一，但不能同时配置两者：

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

rules 尚未在 APISIX 中可用。

limit
integer | string
vaild vaule:
大于 0
指定时间间隔内允许消耗的最大 Token 数量。
在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。在 APISIX 中，仅支持整数类型。
time_window
integer | string
vaild vaule:
大于 0
对应于速率限制 limit 的时间间隔，以秒为单位。
在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。在 APISIX 中，仅支持整数类型。
show_limit_quota_header
boolean
default: true
如果为 true，则包含速率限制响应头。具体来说，如果未设置 rules，则请求头为：
- X-AI-RateLimit-Limit 显示总配额。
- X-AI-RateLimit-Remaining 显示剩余配额。
- X-AI-RateLimit-Reset 显示距离计数器重置的秒数。
当设置了 rules 时，将在 X-AI- 之后插入一个前缀（后跟连字符）。有关详细信息，请参阅 rules.header_prefix。
limit_strategy
string
default: total_tokens
vaild vaule:
total_tokens, prompt_tokens, completion_tokens, or expression
应用速率限制的 Token 类型。total_tokens、prompt_tokens 和 completion_tokens 值在每个模型响应中返回，其中 total_tokens 是 prompt_tokens 和 completion_tokens 的总和。
当设置为 expression 时，使用 cost_expr 中定义的自定义 Lua 算术表达式计算限速成本。从 API7 企业版 3.9.8 版本起可用，尚未在 APISIX 中提供。
cost_expr
string
vaild vaule:
任意非空字符串（必须是有效的 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 中提供。
instances
array[object]
LLM 实例速率限制配置。
- name
  string
  required
  LLM 服务实例的名称。
- limit
  integer | string
  required
  vaild vaule:
  大于 0
  指定时间间隔内允许消耗的最大 Token 数量。
  在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。在 APISIX 中，仅支持整数类型。
- time_window
  integer | string
  required
  vaild vaule:
  大于 0
  对应于速率限制 limit 的时间间隔，以秒为单位。
  在 API7 企业版（从 3.8.17 开始）中，此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。在 APISIX 中，仅支持整数类型。
rejected_code
integer
default: 503
vaild vaule:
between 200 and 599 inclusive
当请求超过配额被拒绝时返回的 HTTP 状态码。
rejected_msg
string
vaild vaule:
any non-empty string
当请求超过配额被拒绝时返回的响应体。
policy
string
required
vaild vaule:
local, redis, redis-cluster, or redis-sentinel
速率限制计数器的策略。从 3.8.19 版本开始在 API7 企业版中可用。从早期版本升级时，将其设置为 local；现有配置将继续有效。此选项尚未在 APISIX 中可用。
设置为 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
default: 6379
vaild vaule:
大于或等于 1
当 policy 为 redis 时 Redis 节点的端口。
redis_username
string
如果使用 Redis ACL，则为 Redis 用户名。如果你使用传统的认证方法 requirepass，则仅配置 redis_password。当 policy 为 redis 时使用。
redis_password
string
当 policy 为 redis 或 redis-cluster 时 Redis 节点的密码。
redis_database
integer
default: 0
vaild vaule:
大于或等于 0
当 policy 为 redis 或 redis-sentinel 时 Redis 中的数据库编号。
redis_ssl
boolean
default: false
如果为 true，则当 policy 为 redis 时使用 SSL 连接到 Redis。
redis_ssl_verify
boolean
default: false
如果为 true，则当 policy 为 redis 时验证服务器 SSL 证书。
redis_timeout
integer
default: 1000
vaild vaule:
大于或等于 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
default: false
如果为 true，则当 policy 为 redis-cluster 时使用 SSL 连接到 Redis 集群。
redis_cluster_ssl_verify
boolean
default: 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
default: master
vaild vaule:
master or slave
要连接的 Redis 节点角色。当 policy 为 redis-sentinel 时可配置。设置为 master 连接到当前 Redis 主节点，设置为 slave 连接到 Redis 副本。
redis_connect_timeout
integer
default: 1000
vaild vaule:
大于或等于 1
建立 Redis 节点连接的超时时间（以毫秒为单位）。当 policy 为 redis-sentinel 时可配置。
redis_read_timeout
integer
default: 1000
vaild vaule:
大于或等于 1
从 Redis 节点读取数据的超时时间（以毫秒为单位）。当 policy 为 redis-sentinel 时可配置。
redis_keepalive_timeout
integer
default: 60000
vaild vaule:
大于或等于 1
空闲 Redis 连接在连接池中保持存活的时间（以毫秒为单位）。当 policy 为 redis-sentinel 时可配置。
sentinel_username
string
用于 Redis Sentinel 实例认证的用户名。当 policy 为 redis-sentinel 时可配置。
sentinel_password
string
用于 Redis Sentinel 实例认证的密码。当 policy 为 redis-sentinel 时可配置。
allow_degradation
boolean
default: false
如果为 true，则当插件或其依赖项不可用时，允许网关继续处理请求而不使用该插件。
从 3.8.19 版本开始在 API7 企业版中可用。尚未在 APISIX 中可用。
rules
array[object]
按顺序应用的一组速率限制规则。
从 3.8.17 版本开始在 API7 企业版中可用。尚未在 APISIX 中可用。
- count
  integer | string
  required
  vaild vaule:
  大于 0
  指定时间间隔内允许消耗的最大 Token 数量。
  此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。
- time_window
  integer | string
  required
  vaild vaule:
  大于 0
  对应于速率限制 count 的时间间隔，以秒为单位。
  此参数还支持字符串数据类型，并允许使用以美元符号（$）为前缀的内置变量。
- key
  string
  required
  用于统计请求的键。如果配置的键不存在，则不会执行该规则。
  如果 key_type 为 var，则 key 被解释为变量。变量不需要以美元符号（$）为前缀。有关可用变量，请参阅内置变量。
  如果 key_type 为 var_combination，则 key 被解释为变量的组合。所有变量都应以美元符号（$）为前缀。例如，要将 key 配置为使用两个请求头 custom-a 和 custom-b 的组合，key 应配置为 $http_custom_a $http_custom_b。
  如果 key_type 为 constant，则 key 被解释为常量值。
- header_prefix
  string
  所有速率限制响应头的前缀。从 3.8.19 版本开始在 API7 企业版中可用。尚未在 APISIX 中可用。
  配置后，前缀将插入到头名称中的 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。

参数​

参数