预算

预算用于保护组织或环境，避免出现意外 AI 支出。在 AISIX 中，预算执行是由 Cloud 管理的工作流：AISIX Cloud 负责预算规则和用量总计，托管网关则在实时流量中执行返回的允许或拒绝决策。

本指南说明预算可以保护哪些对象、预算执行如何影响代理流量，以及 AISIX 因预算原因拒绝请求时调用方会看到什么。Cloud 设置和部署工作流会在后续的 AISIX Cloud 中介绍。

信息

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

预算配置

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

为每个预算选择：

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

预算作用对象

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

目标	适用场景
组织	整个账号需要顶层支出上限。
环境	某个部署环境需要独立上限。
调用方 API Key	某个应用或租户需要独立上限。
服务提供方密钥	某个上游凭证或服务提供方账号需要上限。
团队	绑定到某个团队的所有调用方 API Key 需要共享上限。
成员	绑定到某个成员的所有调用方 API Key 需要共享上限。
团队中的每个成员	团队内每个成员都需要单独上限。

团队和成员预算依赖投射到托管网关的调用方 API Key 身份。如果团队或成员预算行为不符合预期，请检查 AISIX Cloud 中该 API Key 的团队或成员绑定。

预算执行路径

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

当应用发送请求时，托管控制面会跟踪匹配预算目标的用量。在 AISIX 发送服务提供方请求前，托管网关会询问控制面调用方是否可以继续。如果预算仍有余量，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 会应用控制面返回的故障行为。如果没有缓存决策且控制面不可达，AISIX 会拒绝请求。

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

预算用量指标

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

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

查看预算拒绝

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

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

下一步

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

预算配置​

预算作用对象​

预算执行路径​

预算拒绝响应​

可用性与缓存​

预算用量指标​

查看预算拒绝​

下一步​