预算

预算可以在组织、环境、调用方 API Key、服务提供方密钥、团队或成员级别保护托管 AI 支出。托管控制面跟踪用量并做出预算决策，网关则在调用上游服务提供方之前执行这些决策。

预算执行需要 AISIX 托管控制面。自托管网关不包含预算执行引擎。

预算配置

在托管控制面的 Budgets 视图中创建和编辑预算。先选择目标类型，再选择预算需要控制支出的组织、环境、密钥、团队或成员。由于调用方 API Key 属于某个环境，选择 API Key 目标前需要先选择环境。

资源视图还提供内联预算控件作为快捷入口。这些控件位于 API Key 列表、服务提供方密钥列表、Members 视图和团队详情页。团队详情页同时包含共享团队预算和每个成员的预算。内联控件和 Budgets 视图编辑的是同一个预算，因此在任意一处所做的更改都会同步显示。

一个目标可以拥有一个预算。编辑该预算可以更改限额、周期或执行模式。如果需要控制其他目标，请创建另一个预算。

为每个预算配置：

目标，例如组织、环境、调用方 API Key、服务提供方密钥、团队、成员或团队中的每个成员。
以美元计算的支出限额。
日、周或月周期。
执行模式。阻断型预算可在达到限额后拒绝流量；仅警告预算会保持流量通过，并在控制面中显示超出预算的状态。
以限额百分比表示的告警阈值（默认为 80%）。超过阈值时，系统会通过组织的通知渠道发送通知。详见预算告警与通知。

预算是托管控制面资源，不能通过自托管 AISIX Admin API 创建。

预算目标

选择能够代表所需控制支出的最细粒度目标：

目标	计入预算的支出
组织	组织中的所有托管流量
环境	某个部署环境中的流量
调用方 API Key	使用某个下游应用或租户密钥进行身份认证的流量
服务提供方密钥	归因到使用某个上游凭证或服务提供方账户的模型用量
团队	来自绑定到某个团队的每个调用方 API Key 的流量
成员	在整个组织范围内，来自绑定到某个成员的每个调用方 API Key 的流量
团队中的每个成员	为每个成员通过绑定到某个团队的密钥发送的流量分别设置限额

团队和成员预算取决于调用方 API Key 上存储的身份。一个密钥可以包含团队绑定、成员绑定、两者或都不包含。仅仅是团队成员并不会使该密钥的支出计入团队预算；只有请求所使用密钥上的绑定才能决定适用哪些预算。

服务提供方密钥记账会跟随每条用量记录中附加到模型的凭证。预调度执行发生得更早：控制面会检查调用方 API Key 所属环境可用凭证的服务提供方密钥预算。因此，已耗尽的阻断型服务提供方密钥预算可能在路由选择同一环境中的其他凭证之前，就拒绝使用该 API Key 进行身份认证的请求。

成员预算和团队中每个成员的预算会计入不同的流量：

成员预算在整个组织范围内生效。它会合并绑定到该成员的每个调用方 API Key 所产生的支出，不受密钥团队绑定的影响。
团队中每个成员的预算会为该团队内的每个成员分别设置限额。仅当调用方 API Key 同时包含该团队绑定和成员绑定时，该预算才适用。

如果团队或成员预算计入了意外流量，请检查到达网关的调用方 API Key 上的绑定。

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

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

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

该组织配置了以下月度预算：

Alice 拥有 300 美元的成员预算。由于三个密钥都绑定到 Alice，K1、K2 和 K3 的支出都会计入这个组织级限额。
frontend 团队拥有 1,000 美元的共享预算。绑定到 frontend 的每个密钥的支出都会计入，包括 K1、绑定到其他成员的密钥以及未绑定到任何成员的密钥。
frontend 中的每个成员拥有 100 美元的限额。只有 K1 会计入 Alice 的限额，因为它同时包含 Alice 的成员绑定和 frontend 团队绑定。其他每个成员都会获得独立的 100 美元限额。

通过 K2 发送的流量不会计入任何 frontend 预算。虽然 Alice 属于两个团队，但由于 K3 没有团队绑定，它不会计入团队预算。

通过 K1 发送的请求会检查每个匹配的预算，包括 frontend 团队预算、Alice 的成员预算、她在 frontend 中的成员限额，以及任何匹配的组织、环境、调用方 API Key 或服务提供方密钥预算。任何达到限额的匹配阻断型预算都会拒绝该请求。

执行路径

配置预算后，应用仍然使用相同的代理 API 和调用方 API Key，无需调用单独的预算 API。

在 AISIX 发送服务提供方请求之前，托管网关会询问控制面调用方是否可以继续。如果每个匹配的阻断型预算都有余额，请求会继续沿正常代理路径执行。服务提供方响应后，本次请求的用量可能会使预算超出限额；后续检查将在调用服务提供方前拒绝匹配的流量。

预算拒绝响应

对于 OpenAI 兼容请求，预算拒绝会返回 429 和 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 会拒绝请求。

在过期时间上限内，粘滞模式会复用上一次决策：先前被拒绝的密钥仍会被拒绝，先前允许的密钥则可以继续。超出该上限后，AISIX 会应用控制面返回的故障期行为：

粘滞模式会因缓存决策过旧而拒绝流量。
失败开放模式会允许流量。
失败关闭模式会拒绝流量。

该缓存和故障期行为仅适用于托管预算检查。

预算用量指标

控制面跟踪托管流量的预算用量。当预算响应包含合计值时，AISIX 会使用调用方 API Key ID，以及在可用时使用投影的团队和成员 ID 记录预算 Gauge 指标。如果决策中未包含预算合计值，AISIX 会清除该密钥身份的 Gauge 指标。

检查预算拒绝

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

在 Budgets 视图中找到返回的目标，并检查其限额、周期和执行模式。如果范围不符合预期，请检查请求所使用调用方 API Key 上的团队和成员绑定。

后续步骤

配置预算告警与通知，在达到所配置的阈值时接收 Webhook 或 Slack 消息。然后继续阅读限流，配置请求、Token 和并发限制。

预算配置​

预算目标​

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

执行路径​

预算拒绝响应​

可用性与缓存​

预算用量指标​

检查预算拒绝​

后续步骤​