预算

预算用于在组织、环境、调用方 API Key、服务提供方密钥、团队或成员级别保护由 Cloud 托管的 AI 支出。在 AISIX 中，预算执行是由 Cloud 管理的工作流：AISIX Cloud 负责预算规则和用量总计，托管网关则在实时流量中执行返回的允许或拒绝决策。

本指南说明预算可以保护哪些对象、预算执行如何影响代理流量，以及 AISIX 因预算原因拒绝请求时调用方会看到什么。

信息

预算执行仅支持通过 AISIX Cloud 托管预算检查完成。自托管网关不支持预算执行。

预算配置

请在 AISIX Cloud 中配置预算策略。与限流不同，预算不会通过 Admin API 创建，也没有本地自托管执行引擎。

组织和环境预算在 Budgets 视图中创建。其他预算使用相同的执行规则，但在对应资源视图中创建和编辑：调用方 API Key 预算在 API Key 列表中创建，服务提供方密钥预算在服务提供方密钥列表中创建，成员预算在 Members 视图中创建，团队预算在团队详情页中创建。团队详情页还包含该团队的成员预算。

为每个预算选择：

预算目标，例如组织、环境、调用方 API Key、服务提供方密钥、团队、成员，或团队内的每个成员。
美元支出上限。
周期：天、周或月。
执行模式。阻断型预算会在达到上限后拒绝流量；仅告警预算会继续放行流量，并在 Cloud 中展示超预算状态。

预算作用对象

请选择与要控制的支出匹配的最小预算目标：

目标	适用场景
组织	整个账号需要顶层支出上限。
环境	某个部署环境需要独立上限。
调用方 API Key	某个应用或租户需要独立上限。
服务提供方密钥	某个上游凭证或服务提供方账号需要上限。
团队	绑定到某个团队的所有调用方 API Key 需要共享上限。
成员	某个成员需要一个组织范围内的统一额度，无论其调用方 API Key 绑定到哪个团队。
团队中的每个成员	团队中的每个成员分别拥有一个额度，该额度只统计其在该团队中的消耗。

调用方 API Key 预算跟随对应用或租户进行认证的下游密钥。服务提供方密钥预算跟随 AISIX 调用模型服务提供方时使用的上游凭证。

团队和成员预算依赖投射到托管网关的调用方 API Key 身份。调用方 API Key 可以绑定团队、绑定成员、同时绑定两者，或不绑定任何一者。只有 API Key 自身的绑定决定其消耗计入哪些预算；仅仅因为某成员属于某团队，并不会自动将该成员 API Key 的消耗计入团队预算。

成员目标与团队内按成员目标统计的消耗范围不同：

成员预算是组织范围内的预算。它会汇总绑定到该成员的所有调用方 API Key 在任意团队中的消耗。
团队内的按成员预算只统计成员通过绑定到该团队的 Key 产生的消耗。只有同时绑定团队和成员的 Key 才会计入，每个团队成员在同一额度下拥有独立的预算。

如果团队或成员预算行为不符合预期，请检查 AISIX Cloud 中该 API Key 的团队或成员绑定。

示例：同一成员属于两个团队

Alice 同时属于 frontend 和 data 团队，并使用三个调用方 API Key：

Key	团队绑定	成员绑定
`K1`	`frontend`	Alice
`K2`	`data`	Alice
`K3`	无	Alice

其组织配置了三个预算：

Alice 的成员预算：每月 $300。K1、K2 和 K3 的消耗都会计入同一个额度，因为三个 Key 都绑定到 Alice。
frontend 的团队预算：每月 $1,000。所有绑定到 frontend 的 Key 都会计入，包括 K1 以及绑定到其他成员或未绑定成员的 Key。
frontend 的按成员预算：每月 $100。Alice 在此预算下的额度只统计 K1；frontend 中的其他成员各自拥有独立的 $100 额度。

需要注意：

Alice 通过 K2 发送到 data 的流量不会计入任何 frontend 额度。她的两个团队分别计费。
即使 Alice 属于两个团队，K3 也不会计入任何团队预算。若要让 Key 的消耗计入某个团队，必须将 Key 绑定到该团队。
通过 K1 发送的请求会同时检查所有匹配的预算。在此示例中，包括 frontend 团队预算、Alice 的成员预算和她在 frontend 中的按成员额度，以及组织、环境、调用方 API Key 或服务提供方密钥预算（如果已配置）。任何已达到额度且启用了阻断的预算都会拒绝请求。

预算执行路径

一种常见配置是在某个调用方 API Key 上设置阻断型月度预算。应用继续使用同一个代理 API 和调用方 API Key，不需要调用单独的预算 API。

当应用发送请求时，托管控制面会跟踪匹配预算目标的用量。在 AISIX 发送服务提供方请求前，托管网关会询问控制面调用方是否可以继续。如果预算仍有余量，AISIX 会继续正常请求链路。某个被放行的请求在其用量记录后可能使预算超过上限；之后的硬性停止检查会在服务提供方调用前拒绝匹配的流量，并返回 429。

预算拒绝响应

对于兼容 OpenAI 的请求，响应会使用 OpenAI 风格错误信封：

{
  "error": {
    "message": "api key budget 'production-chat' exceeded ($1.00/month). Resets 2026-06-01 00:00 UTC.",
    "type": "billing_error",
    "code": "budget_exceeded",
    "scope": "api_key",
    "scope_ref": "api-key-uuid-1",
    "limit_usd": "1.00",
    "spent_usd": "2.00",
    "period": "month",
    "period_resets_at": "2026-06-01T00:00:00Z",
    "retry_after_seconds": 259200
  }
}

对于 Anthropic 风格的 Messages 请求，响应会保持 Anthropic 错误格式，不包含额外预算字段。

可用性与缓存

托管预算检查会使用短时决策缓存，因此重复请求不一定每次都需要控制面往返。新鲜缓存决策会复用 5 秒。

如果控制面不可达，AISIX 可以复用过期缓存决策，最长不超过 AISIX_DP_BUDGET_STALE_MAX_SECONDS 设置的上限。这是一个进程环境变量，默认值为 600 秒。如果没有缓存决策且控制面不可达，AISIX 会拒绝请求。

在过期上限之内，sticky 模式会继续沿用上一次缓存决策：此前被拒绝的密钥保持拒绝，此前被放行的密钥继续放行。过期上限到达后，AISIX 会应用控制面返回的故障行为：

sticky 模式拒绝流量，因为缓存决策已过旧。
fail-open 模式放行流量。
fail-closed 模式拒绝流量。

该行为仅适用于托管预算检查。

预算用量指标

AISIX Cloud 会根据托管流量跟踪预算用量。当托管预算响应包含总量时，AISIX 也会记录带有调用方 API Key 身份的预算 gauge。标签包括 API Key ID，以及可用时的投射团队和成员 ID。

如果决策不包含预算总量，AISIX 会清除该 API Key 身份对应的预算 gauge。

查看预算拒绝

当托管部署返回 budget_exceeded 时，请先检查错误代码和结构化预算字段。拒绝来自托管预算检查响应，而不是 Admin API。

然后检查返回预算目标对应的 AISIX Cloud 预算配置。如果返回的作用域看起来不正确，请检查到达托管网关的调用方 API Key 绑定。

下一步

你已经了解托管预算决策来自哪里，以及 AISIX 如何在请求链路中执行这些决策。接下来继续阅读限流，配置请求、token 和并发限制。

预算配置​

预算作用对象​

示例：同一成员属于两个团队​

预算执行路径​

预算拒绝响应​

可用性与缓存​

预算用量指标​

查看预算拒绝​

下一步​