跳到主要内容

参数​

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

备注

在 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, or completion_tokens

    应用速率限制的 Token 类型。total_tokens、prompt_tokens 和 completion_tokens 值在每个模型响应中返回，其中 total_tokens 是 prompt_tokens 和 completion_tokens 的总和。

  • 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。