速率限制策略

在滚动时间窗口内限制某个用户、工作区或 API key 可通过 LLM Gateway 发送的请求数或 token 数。

NOTE

LLM Gateway 处于 beta 阶段。

速率限制策略限制某个主体在短滚动时间窗口内可通过 LLM Gateway 消耗的 requests 或 tokens。网关会实时执行该限制，并阻止任何会超出限制的请求，返回带 Retry-After 头的 429 响应：

API Error: 429 request blocked by gateway policies: Dev Team Rate Limit
Retry-After: 42

Retry-After 的值是当前窗口重置前的秒数。客户端应遵守该头并在重试前退避。

速率限制策略与支出上限策略互为补充，可以同时应用——支出上限用于成本控制，速率限制用于吞吐量和流量控制。

策略维度

每个传入请求都会经过速率限制策略的评估。你可以将策略设为默认值（对所有用户、工作区或 API key 应用统一的速率限制），也可以设为细粒度策略（针对单个主体的限制或一组主体的限制）。

主体	限制内容	示例
User	单个用户或一组用户的请求数或 token 数（根据 API key 的身份解析）	“任何单个开发者每分钟最多发送 100 个请求”
Workspace	单个工作区或一组工作区内的请求数或 token 数	“R&D 工作区每小时不能超过 1,000,000 个 token”
API key	单个 API key 或一组 API key 的请求数或 token 数	“客户支持 agent 的多个 key 共享每分钟 200 个请求的限制”

默认策略与细粒度策略

速率限制策略有两种模式：

1. Default policies 自动应用于某个主体维度中的每个成员。示例：“此工作区中的每个用户都有每分钟 100 个请求的默认上限。”无需为每个人单独创建策略。
2. Granular policies 针对指定的主体，仅覆盖该主体的默认值。示例：“值班工程师每分钟获得 500 个请求。”编辑默认值会更新所有仍在使用它的主体。

独立执行

每个主体都会被单独跟踪和执行。一个用户达到限制不会影响其他用户。

限制

单个速率限制策略可以同时执行多个限制。例如，一个策略可以同时执行 每分钟 100 个请求 和 每小时 1,000,000 个 token。

每个限制有三个字段：

字段	允许的值
Metric	requests 或 tokens（提供商上报的总 token 数）
Window	minute 或 hour
Value	一个正整数（上限）

规则：

• 每个策略至少需要一个限制。
• 一个策略内不能有两个 metric 和 window 组合相同的限制。

创建速率限制策略

WARNING

创建和管理策略需要 organization:manage 权限。完整权限明细请参阅追踪、引擎和访问控制。

1. 前往 LLM Gateway。
2. 点击 Create policy。
3. 选择 Rate limit 作为策略类型。
4. 选择主体范围（user、workspace 或 API key）。
5. 添加一个或多个限制，每个限制包含 metric、window 和 value。
6. 保存。

策略会立即生效。

速率限制策略还可以携带基于自定义请求头的条件，从而让单个主体的流量按 header 值拆分为不同的限制。用这种方式，你可以让每个终端客户在同一个 API key 下拥有各自的吞吐量配额。更多信息请参见按客户划分的策略。

后续步骤

• 支出策略：在速率限制之外设置成本上限。
• 按客户划分的策略：按自定义请求头拆分限制，让每个终端客户拥有自己的配额。
• 数据策略：添加数据策略。

---