版本：Dev

预算

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

预算可通过 AISIX Enterprise 或 AISIX Cloud 使用，不属于 AISIX OSS 资源模型。

前提条件

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

具备将要创建预算的 AISIX Enterprise 或 AISIX Cloud 组织访问权限。
对于模型目录未涵盖的模型，请配置模型定价，以便其流量产生的支出计入预算。
对于团队预算，请创建团队，并绑定其流量应计入该预算的调用方 API Key。
对于标签预算，请按成本归属标签中的说明声明标签键并设置标签值。

创建预算

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

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

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

预算目标

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

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

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

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

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

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

标签预算计入解析出的标签包含其 key=value 的每个请求，无论该值来自调用方 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 Key、服务提供方密钥、团队、成员、团队中每个成员以及标签的预算。

计入的是请求记录的成本，计算方式见模型定价：它已体现模型组价格、价格分档和低峰折扣；由响应缓存应答的请求不计入任何支出。

请求的归属在其成本被计入时确定，依据的是当时生效的绑定：调用方 API Key 的团队和成员绑定、模型的服务提供方密钥，以及环境所属的组织。标签预算例外：它计入网关在请求运行时记录在用量上的标签，因此之后的标签变更不会移动已记录的支出。已计入的支出会留在原归属中。以下变更不会改变当前周期已计入的支出，只有之后的请求才会按新绑定计入：

将调用方 API Key 改绑到其他团队或成员。
将模型改到其他服务提供方密钥。
删除调用方 API Key、成员、团队或环境。
移除超出组织用量数据保留窗口的用量记录。

例如，某个 Key 从 frontend 团队改绑到 data 团队后，它此前请求的支出仍留在 frontend 团队预算中。该 Key 之后的请求会计入 data 团队预算，也不再受 frontend 预算检查。

新预算并不从零开始。创建预算，或更改预算的目标或周期时，预算会以其目标在当前周期内已记录的支出作为起点，并按当前绑定归属；之后再以增量方式计入新的支出。

每个周期都从零开始。属于上一周期、但上报较晚的请求用量不会被计入。

执行路径

配置预算后，应用仍然使用相同的代理 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
  }
}

金额使用组织币种。message 用该币种的符号书写上限，例如人民币组织中为 ¥1.00；limit_usd 和 spent_usd 保留原字段名，以该币种的纯数字表示。

Anthropic 兼容的 Messages 请求保持 Anthropic 错误格式，不包含额外的预算字段。

可用性与缓存

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

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

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

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

该缓存和故障期行为仅适用于控制面预算检查。

预算用量指标

控制面跟踪受管网关流量的预算用量。当预算响应包含合计值时，AISIX 会使用调用方 API Key ID，以及在可用时使用投影的团队和成员 ID 记录预算 Gauge 指标。如果后续决策未包含预算合计值，AISIX 会将该密钥身份的 aisix_budget_details_present 设为 0，但保留上次上报的金额。仅在该存在标志为 1 时使用这些金额。aisix_budget_limit_usd、aisix_budget_spent_usd 和 aisix_budget_remaining_usd 这几个 Gauge 取自控制面上报的金额，因此尽管名称带 usd，数值却是组织币种。组织切换币种后，同一条序列会以新币种的数值继续。

验证预算执行

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

在控制面首次测量某个预算的支出之前，该预算显示 no spend data yet，而不是 $0.00。新建预算通常在几秒内获得首次测量；控制面升级后，每个预算都要等到下一次测量。调用方 API Key、环境、团队、成员和服务提供方密钥页面上的预算区域同样如此。在 Admin API 中，state.aggregated_at 在首次测量之前为 null，之后记录最近一次测量支出的时间。

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

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

检查预算拒绝

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

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

后续步骤

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

前提条件​

创建预算​

预算目标​

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

支出如何计入​

执行路径​

预算拒绝响应​

可用性与缓存​

预算用量指标​

验证预算执行​

检查预算拒绝​

后续步骤​