预算

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

预算可通过 AISIX Cloud 控制面使用，不属于开源网关资源模型。

前提条件

开始前，请准备以下内容：

具备将要创建预算的 AISIX Cloud 组织访问权限。
对于模型目录未涵盖的模型，请配置模型定价，以便其流量产生的支出计入预算。

创建预算

打开 AISIX Cloud 控制面的 Budgets 视图，然后选择 New budget。
在 Name 中输入预算名称。
选择 Scope：组织、环境、调用方 API Key、服务提供方密钥、团队、成员或团队中的每个成员。系统提示时，再选择 Environment 或目标。对于调用方 API Key 范围，请先选择 Environment，再选择 API Key。
在 Limit (USD) 中输入限额，并在 Period 中选择日、周或月。
在 Alert thresholds (%) 中输入应发送通知的限额百分比。默认阈值为 80%。详见预算告警与通知。
保持选中 Hard stop at limit，以便达到限额后拒绝匹配的流量。取消选中后，预算将变为仅告警预算，继续放行流量并在控制面中显示超出预算的状态。
选择 Create budget。

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

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

预算目标

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

目标	计入预算的支出
组织	组织中的所有 AISIX Cloud 网关流量
环境	某个部署环境中的流量
调用方 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 错误格式，不包含额外的预算字段。

可用性与缓存

网关会将 AISIX Cloud 预算决策缓存 5 秒，因此重复请求无需始终往返控制面。

如果控制面无法访问，AISIX 可以在 AISIX_DP_BUDGET_STALE_MAX_SECONDS 设置的上限内复用过期缓存决策。该进程环境变量默认为 600 秒。如果不存在缓存决策，AISIX 会拒绝请求。

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

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

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

预算用量指标

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

验证预算执行

使用与预算目标匹配的调用方 API Key 和模型发送流量。然后在 Budgets 视图中检查预算，确认支出计入预期范围。

使用用量上报确认模型请求产生了支出。如果可以看到 Token 用量，但没有支出，请检查模型定价是否包含与服务提供方和模型名称完全匹配的条目。

仅告警预算在达到限额后仍会继续放行匹配的流量，并在控制面中显示超出预算的状态。阻断型预算会以 429 拒绝后续匹配请求。由于控制面会在服务提供方响应后记录用量，使支出越过限额的请求本身仍可能完成。缓存的决策也可能继续生效最多 5 秒。

检查预算拒绝

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

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

后续步骤

配置预算告警与通知，在达到所配置的阈值时接收 Webhook 或 Slack 消息。然后使用日志记录与审计调查预算拒绝及其背后的控制面变更。

前提条件​

创建预算​

预算目标​

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

执行路径​

预算拒绝响应​

可用性与缓存​

预算用量指标​

验证预算执行​

检查预算拒绝​

后续步骤​