跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

支出限制

最后更新 查看 MarkdownAgent 设置

支出限制允许你在 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 的身份验证方式。

使用 Cloudflare Access

如果你的 gateway 受 Cloudflare Access 保护,AI Gateway 会自动将已认证的 Access 用户 ID 作为保留的 cf.user_id 元数据键添加到每个请求。你无需从客户端应用传递用户 ID。

要设置按用户预算:

  1. 在 Cloudflare 仪表板 ↗中,前往 AI > AI Gateway 并选择你的 gateway。
  2. 前往 Settings(设置) > Spend limits(支出限制) 并添加规则。
  3. 在 Limit by metadata(按元数据限制) 下,选择 Add metadata dimension(添加元数据维度) 并将键输入为 cf.user_id。
  4. 将该维度设为 Split by value。
  5. 设置预算金额和时间窗口,然后保存。

每个已认证的 Access 用户现在都有独立预算。若要改为限制单个用户,将该维度设为 Filter by value 并输入该用户的 Access JWT sub 声明。

不使用 Cloudflare Access

如果 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 条支出限制规则。

这篇文档对您有帮助吗?