支出限制允许你在 AI Gateway 上设置基于成本的预算。当累计支出在时间窗口内达到限制时,AI Gateway 会阻止进一步请求并返回 429 响应,直到窗口重置。
与限制请求数量的速率限制不同,支出限制根据模型定价跟踪每个请求的实际美元成本。你可以将限制范围限定为模型、提供商或用户 ID、团队、应用等自定义元数据维度的任意组合。
支出限制适用于具有已知定价的模型的 Unified Billing 请求和 BYOK 请求。
每个支出限制规则在滚动或固定时间窗口内定义预算(美元)。AI Gateway 根据 token 使用和模型定价计算每个请求的成本,然后实时跟踪累计支出与限制的比较。
在向提供商发送请求之前,AI Gateway 一次性评估所有适用的支出限制规则。如果任何单个规则超出预算,请求将被阻止并返回 429 响应。
支出限制是最终一致的。当前请求的成本在完成后记录,因此并发请求突发可能在执行赶上之前短暂超出限制。
每条规则可以通过一个或多个维度限定范围:
- Limit by provider(按提供商限制) — 请求所使用的提供商。
- Limit by model(按模型限制) — 请求所使用的模型。
- Limit by metadata(按元数据限制) — 你附加到请求的自定义元数据键。输入元数据键名(例如
agent_id或environment)。
每个维度可以配置为以下两种模式之一:
| 模式 | 行为 | 示例 |
|---|---|---|
| Split by value | 每个不同值获得独立的预算桶。 | 例如,如果你传入 agent_id,按 agent_id 分割会为每个智能体提供独立预算。 |
| Filter by value | 规则仅在维度等于特定值时适用。 | 例如,如果你传入 agent_id,将 agent_id 过滤为 agent_42 仅限制该智能体的请求。 |
如果规则上未配置维度,所有值共享一个预算桶。例如,没有 provider 维度的规则一起跟踪所有提供商的支出。
给定模型为 openai/gpt-5.5、元数据 agent_id 值为 agent_42 的请求:
| 场景 | 维度 | 预算桶 |
|---|---|---|
| 所有人的全局预算 | 无 | 一个共享桶 |
| 按智能体预算 | agent_id 元数据:split by value |
每个智能体独立桶 |
| 按提供商、按智能体 | agent_id 元数据:split by value,provider:split by value |
每个智能体+提供商组合独立桶 |
| 仅特定模型 | model:filter by value openai/gpt-5.5 |
仅适用于 openai/gpt-5.5 请求 |
| 按智能体、按模型 | agent_id 元数据:split by value,model:split by value |
每个智能体+模型组合独立桶 |
支出限制通过仪表板或 API 在每个 gateway 上配置。在仪表板中,选择你的 gateway,然后前往 Settings(设置) > Spend limits(支出限制)。每个 gateway 最多可定义 20 条规则。
要按用户 ID 或团队等自定义维度限定支出限制范围,请为请求附加自定义元数据。
你可以通过将规则范围限定为用户标识符,为每个用户提供独立预算。如何获取该标识符取决于 gateway 的身份验证方式。
如果你的 gateway 受 Cloudflare Access 保护,AI Gateway 会自动将已认证的 Access 用户 ID 作为保留的 cf.user_id 元数据键添加到每个请求。你无需从客户端应用传递用户 ID。
要设置按用户预算:
- 在 Cloudflare 仪表板 ↗中,前往 AI > AI Gateway 并选择你的 gateway。
- 前往 Settings(设置) > Spend limits(支出限制) 并添加规则。
- 在 Limit by metadata(按元数据限制) 下,选择 Add metadata dimension(添加元数据维度) 并将键输入为
cf.user_id。 - 将该维度设为 Split by value。
- 设置预算金额和时间窗口,然后保存。
每个已认证的 Access 用户现在都有独立预算。若要改为限制单个用户,将该维度设为 Filter by value 并输入该用户的 Access JWT sub 声明。
如果 gateway 不在 Access 之后,请将你自己的用户标识符作为自定义元数据传递(例如 user_id 键)。然后在 Limit by metadata(按元数据限制) 下,添加键为 user_id 的维度,并将其设为 Split by value。
超出支出限制时,AI Gateway 返回 429 Too Many Requests 响应。你有两个选项:
- Block requests(默认)- 请求被拒绝,直到预算窗口重置。
- Fall back to a cheaper model - 创建带有主要模型和回退的动态路由(例如
anthropic/claude-opus-4.7回退到@cf/moonshotai/kimi-k2.6)。然后使用此功能对主要模型设置支出限制。当主要模型预算超出时,AI Gateway 自动将请求路由到回退模型,而不是阻止它们。
你可以在分析仪表板上按模型、提供商或任何自定义元数据属性跟踪支出。使用此功能了解使用模式并设置合理的预算。
- 成本跟踪是基于 token 数量和模型定价的最佳努力估算。请参阅提供商仪表板获取准确的计费金额。
- 每个 gateway 最多可配置 20 条支出限制规则。