Copilot commented on code in PR #13209: URL: https://github.com/apache/apisix/pull/13209#discussion_r3076970457
########## docs/zh/latest/plugins/ai-rate-limiting.md: ########## @@ -418,15 +899,17 @@ X-AI-RateLimit-Reset-deepseek-instance: 0 ### 配置实例优先级和速率限制 -以下示例演示了如何配置两个具有不同优先级的模型，并对具有较高优先级的实例应用速率限制。在 `fallback_strategy` 设置为 `["rate_limiting"]` 的情况下，一旦高优先级实例的速率限制配额完全消耗，插件应继续将请求转发到低优先级实例。 +以下示例演示了如何配置两个具有不同优先级的模型，并对具有较高优先级的实例应用速率限制。在 `fallback_strategy` 设置为 `["rate_limiting"]` 的情况下，一旦高优先级实例的速率限制配额完全消耗，Plugin 应继续将请求转发到低优先级实例。 Review Comment: 此处中文说明中使用了英文单词 “Plugin”（非 CRD 的 kind/字段名），与文档其它位置的“插件”表述不一致。建议改为“插件”，以保持中文文档用词一致。 ```suggestion 以下示例演示了如何配置两个具有不同优先级的模型，并对具有较高优先级的实例应用速率限制。在 `fallback_strategy` 设置为 `["rate_limiting"]` 的情况下，一旦高优先级实例的速率限制配额完全消耗，插件应继续将请求转发到低优先级实例。 ``` ########## docs/zh/latest/plugins/ai-rate-limiting.md: ########## @@ -33,29 +33,33 @@ description: ai-rate-limiting 插件对发送到 LLM 服务的请求实施基于 <link rel="canonical" href="https://docs.api7.ai/hub/ai-rate-limiting"; /> </head> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## 描述 -`ai-rate-limiting` 插件对发送到 LLM 服务的请求实施基于令牌的速率限制。它通过控制在指定时间范围内消耗的令牌数量来帮助管理 API 使用，确保公平的资源分配并防止服务过载。它通常与 [`ai-proxy`](ai-proxy.md) 或 [`ai-proxy-multi`](ai-proxy-multi.md) 插件一起使用。 +`ai-rate-limiting` 插件对发送到 LLM 服务的请求实施基于令牌的速率限制。它通过控制在指定时间范围内消耗的令牌数量来帮助管理 API 使用，确保公平的资源分配并防止服务过载。它通常与 [`ai-proxy`](./ai-proxy.md) 或 [`ai-proxy-multi`](./ai-proxy-multi.md) 插件一起使用。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -|------------------------------|----------------|----------|----------|---------------------------------------------------------|-------------| -| limit | integer | 否 | | >0 | 在给定时间间隔内允许的最大令牌数。`limit` 和 `instances.limit` 中至少应配置一个。如果未配置 `rules`,则为必填项。 | -| time_window | integer | 否 | | >0 | 与速率限制 `limit` 对应的时间间隔（秒）。`time_window` 和 `instances.time_window` 中至少应配置一个。如果未配置 `rules`,则为必填项。 | -| rules | array[object] | 否 | | | 速率限制规则列表。每个规则是一个包含 `count`、`time_window` 和 `key` 的对象。如果配置了此项，则优先于 `limit` 和 `time_window`。 | -| rules.count | integer 或 string | 是 | | >0 或变量表达式 | 在给定时间间隔内允许的最大令牌数。可以是静态整数或变量表达式，如 `$http_custom_limit`。 | -| rules.time_window | integer 或 string | 是 | | >0 或变量表达式 | 与速率限制 `count` 对应的时间间隔（秒）。可以是静态整数或变量表达式。 | -| rules.key | string | 是 | | | 用于计数请求的键。如果配置的键不存在，则不会执行该规则。`key` 被解释为变量组合，例如：`$http_custom_a $http_custom_b`。 | -| rules.header_prefix | string | 否 | | | 速率限制头部的前缀。如果配置了此项，响应将包含 `X-AI-{header_prefix}-RateLimit-Limit`、`X-AI-{header_prefix}-RateLimit-Remaining` 和 `X-AI-{header_prefix}-RateLimit-Reset` 头部。如果未配置，将使用规则索引 (从 1 开始) 作为前缀。| -| show_limit_quota_header | boolean | 否 | true | | 如果为 true，则在响应中包含 `X-AI-RateLimit-Limit-*`、`X-AI-RateLimit-Remaining-*` 和 `X-AI-RateLimit-Reset-*` 头部，其中 `*` 是实例名称。 | -| limit_strategy | string | 否 | total_tokens | [total_tokens, prompt_tokens, completion_tokens] | 应用速率限制的令牌类型。`total_tokens` 是 `prompt_tokens` 和 `completion_tokens` 的总和。 | -| instances | array[object] | 否 | | | LLM 实例速率限制配置。 | -| instances.name | string | 是 | | | LLM 服务实例的名称。 | -| instances.limit | integer | 是 | | >0 | 实例在给定时间间隔内允许的最大令牌数。 | -| instances.time_window | integer | 是 | | >0 | 实例速率限制 `limit` 对应的时间间隔（秒）。 | -| rejected_code | integer | 否 | 503 | [200, 599] | 当超出配额的请求被拒绝时返回的 HTTP 状态码。 | -| rejected_msg | string | 否 | | | 当超出配额的请求被拒绝时返回的响应体。 | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------|------|--------|--------|--------|------| +| limit | integer | False | | >0 | 在给定时间间隔内允许的最大令牌数。`limit` 和 `instances.limit` 中至少应配置一个。如果未配置 `rules`，则为必填项。 | +| time_window | integer | False | | >0 | 与速率限制 `limit` 对应的时间间隔（秒）。`time_window` 和 `instances.time_window` 中至少应配置一个。如果未配置 `rules`，则为必填项。 | +| show_limit_quota_header | boolean | False | true | | 如果为 true，则在响应中包含速率限制头部。当未设置 `rules` 时，头部为 `X-AI-RateLimit-Limit-*`、`X-AI-RateLimit-Remaining-*` 和 `X-AI-RateLimit-Reset-*`，其中 `*` 是实例名称。当设置了 `rules` 时，详见 `rules.header_prefix`。 | +| limit_strategy | string | False | total_tokens | [`total_tokens`, `prompt_tokens`, `completion_tokens`, `expression`] | 应用速率限制的令牌类型。`total_tokens` 是 `prompt_tokens` 和 `completion_tokens` 的总和。当设置为 `expression` 时，使用 `cost_expr` 字段动态计算令牌消耗。 | +| cost_expr | string | False | | | 用于动态计算令牌消耗的 Lua 算术表达式。变量从 LLM API 原始使用量响应字段注入。缺失的变量默认为 0。仅在 `limit_strategy` 为 `expression` 时有效。示例：`input_tokens + cache_creation_input_tokens + output_tokens`。 | +| instances | array[object] | False | | | LLM 实例速率限制配置。 | +| instances.name | string | True | | | LLM 服务实例的名称。 | +| instances.limit | integer | True | | >0 | 实例在给定时间间隔内允许的最大令牌数。 | +| instances.time_window | integer | True | | >0 | 实例速率限制 `limit` 对应的时间间隔（秒）。 | +| rejected_code | integer | False | 503 | [200, 599] | 当超出配额的请求被拒绝时返回的 HTTP 状态码。 | +| rejected_msg | string | False | | | 当超出配额的请求被拒绝时返回的响应体。 | +| rules | array[object] | False | | | 按顺序应用的速率限制规则数组。如果配置了此项，则优先于 `limit` 和 `time_window`。 | +| rules.count | integer 或 string | True | | >0 或变量表达式 | 在给定时间间隔内允许的最大令牌数。可以是静态整数或变量表达式，如 `$http_custom_limit`。 | +| rules.time_window | integer 或 string | True | | >0 或变量表达式 | 与速率限制 `count` 对应的时间间隔（秒）。可以是静态整数或变量表达式。 | +| rules.key | string | True | | | 用于计数请求的键。如果配置的键不存在，则不会执行该规则。`key` 被解释为变量组合。所有变量应以美元符号（`$`）为前缀。例如：`$http_custom_a $http_custom_b`。 | +| rules.header_prefix | string | False | | | 速率限制响应头部的前缀。配置后，前缀插入到头部名称中 `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`。 | Review Comment: 中文文档的“必选项”列目前使用了英文布尔值 True/False，这与仓库中其他中文插件文档（例如 ai-proxy）普遍使用“是/否”的写法不一致，且会降低可读性。建议将此列统一改为“是/否”（并相应调整各行取值）。 ```suggestion | cost_expr | string | 否 | | | 用于动态计算令牌消耗的 Lua 算术表达式。变量从 LLM API 原始使用量响应字段注入。缺失的变量默认为 0。仅在 `limit_strategy` 为 `expression` 时有效。示例：`input_tokens + cache_creation_input_tokens + output_tokens`。 | | instances | array[object] | 否 | | | LLM 实例速率限制配置。 | | instances.name | string | 是 | | | LLM 服务实例的名称。 | | instances.limit | integer | 是 | | >0 | 实例在给定时间间隔内允许的最大令牌数。 | | instances.time_window | integer | 是 | | >0 | 实例速率限制 `limit` 对应的时间间隔（秒）。 | | rejected_code | integer | 否 | 503 | [200, 599] | 当超出配额的请求被拒绝时返回的 HTTP 状态码。 | | rejected_msg | string | 否 | | | 当超出配额的请求被拒绝时返回的响应体。 | | rules | array[object] | 否 | | | 按顺序应用的速率限制规则数组。如果配置了此项，则优先于 `limit` 和 `time_window`。 | | rules.count | integer 或 string | 是 | | >0 或变量表达式 | 在给定时间间隔内允许的最大令牌数。可以是静态整数或变量表达式，如 `$http_custom_limit`。 | | rules.time_window | integer 或 string | 是 | | >0 或变量表达式 | 与速率限制 `count` 对应的时间间隔（秒）。可以是静态整数或变量表达式。 | | rules.key | string | 是 | | | 用于计数请求的键。如果配置的键不存在，则不会执行该规则。`key` 被解释为变量组合。所有变量应以美元符号（`$`）为前缀。例如：`$http_custom_a $http_custom_b`。 | | rules.header_prefix | string | 否 | | | 速率限制响应头部的前缀。配置后，前缀插入到头部名称中 `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`。 | ``` ########## docs/zh/latest/plugins/ai-rate-limiting.md: ########## @@ -875,4 +1745,355 @@ curl "http://127.0.0.1:9080/anything"; -X POST \ } ``` -这显示了 `ai-proxy-multi` 根据消费者在 `ai-rate-limiting` 中的速率限制规则对流量进行负载均衡。 +这显示了 `ai-proxy-multi` 根据 Consumer 在 `ai-rate-limiting` 中的速率限制规则对流量进行负载均衡。 + +### 按规则进行速率限制 + +以下示例演示了如何配置 Plugin 根据请求属性应用不同的速率限制规则。在此示例中，速率限制基于表示调用者访问层级的 HTTP 头部值进行应用。所有规则按顺序执行。如果配置的键不存在，则跳过相应的规则。 + +创建一个带有 `ai-rate-limiting` Plugin 的 Route，根据请求头部应用不同的速率限制，允许按订阅（`X-Subscription-ID`）进行速率限制，并对试用用户（`X-Trial-ID`）实施更严格的限制： Review Comment: 本段落在中文说明中使用了英文 “Plugin / Route”（非资源字段名），与中文文档整体以中文术语叙述的风格不一致。建议将此处统一为“插件/路由”等中文术语，并在本节保持一致表述，避免中英混排影响阅读。 ```suggestion 以下示例演示了如何配置插件，根据请求属性应用不同的速率限制规则。在此示例中，速率限制基于表示调用者访问层级的 HTTP 头部值进行应用。所有规则按顺序执行。如果配置的键不存在，则跳过相应的规则。 创建一个带有 `ai-rate-limiting` 插件的路由，根据请求头部应用不同的速率限制，允许按订阅（`X-Subscription-ID`）进行速率限制，并对试用用户（`X-Trial-ID`）实施更严格的限制： ``` ########## docs/zh/latest/plugins/ai-rate-limiting.md: ########## @@ -563,11 +1227,14 @@ curl "http://127.0.0.1:9080/anything"; -X POST \ } ``` -### 按消费者进行负载均衡和速率限制 +### 按 Consumer 进行负载均衡和速率限制 + +以下示例演示了如何配置两个模型进行负载均衡，并按 Consumer 应用速率限制。 -以下示例演示了如何配置两个模型进行负载均衡，并按消费者应用速率限制。 +创建 Consumer `johndoe` 并对 `openai-instance` 实例设置 60 秒窗口内 10 个令牌的速率限制配额： Review Comment: 本段落在中文说明中多处使用英文 “Plugin / Route”（非资源字段名），与同仓库中文插件文档普遍使用“插件/路由”的写法不一致（例如 ai-proxy-multi 相关示例仍使用“按消费者…/向路由发送…”）。建议统一为中文术语，避免中英混排影响阅读。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
