---
title: "成本预算"
---

<!-- i18n: source=docs/architecture/cost-budgets.md blob=932ba3cd2049b60a49294a5dd87fa51b9401b693 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cost-budgets.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cost-budgets.md), which is authoritative.

<a id="cost-budgets"></a>

命名空间和具名用户的上限使用 `agent_events` 中滚动 24 小时的成本账本。正的命名空间策略会覆盖对应的服务器默认值；零表示继承，两个层级都为零则禁用该上限。具名用户的上限独立于命名空间的上限。任一上限达到时，准入都会拒绝付费合成，模型路由则使用较大的支出比例。`memory.ask`（包括其整篇文档路由）、`code.ask`、`knowledge.synthesize` 和 `code.search` 的查询扩展会提供记录在账本中的逻辑用户。命名空间范围的 worker 保持其命名空间记账；令牌主体绝不会被用来替代未归属的用户。这些软性控制不会预留支出，也不会建立计费身份。

`cost.budget_status` 与各项防护共用同一份策略和支出读取。用户模式需要指定命名空间，并报告该用户的上限和判定结果，以及 `namespace_over_cap`。除非调用方是没有命名空间角色限制的已验证平台管理员，否则用户的确切支出及其百分比为 `null`。即使所有事件都是普通事件，这一点也同样成立；数字是否出现若有所不同，就会泄露带标记的活动。缺少认证则不授予任何私有支出的访问权限。内部记账、准入和预算压力包含所有支出，包括带标记的请求。命名空间和组织的总额仍为数值。传输层准入会强制执行令牌绑定的用户。命名空间和组织模式保留其现有的读取范围。[成本指南](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md#daily-spend-caps)介绍了配置和警告时机。

可选的 `budget_alert_inbox` 必须指向同一组织内、由该预算所属命名空间拥有的现有收件箱。注册时会验证它，投递时会再次检查所有权。点检查和状态轮询会通过现有的任务事件流调度有界的后台警告，每个进程最多有 32 个待投递项。同一组织的投递在进程内串行执行，因此命名空间警告和用户警告不会相互竞争。没有发现 worker。事件 ID 包含组织、命名空间、收件箱、所选用户、上限、警告比例和 UTC 日期。分布式声明和强一致的事件读取使检查与插入串行化；去重令牌加回读用于处理不确定的重试。通知失败不会改变上限判定。

用户警告的载荷包含所选用户、上限和警告比例，并带有 `spent_24h_usd: null`。这适用于收件箱、轮询、流和 webhook，即使是由运维人员的检查触发的投递也是如此：发起者的权限并不能确立接收者的权限。命名空间警告保留其命名空间支出总额。用户上限的判定和警告阈值的越过会泄露支出的界限；更改上限的管理员可以推断出更紧的界限。这是一种可接受的策略信号，与[带标记支出的总额例外](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md)并列，而不是完全的不干扰。它不授予对带标记的工作、模型或结果的任何访问权限。

任务更新和监视流会在分页之前，按调用方的用户和会话范围过滤警告。范围不完整的调用方收不到任何警告；普通任务事件仍在收件箱内共享。已注册收件箱的 webhook 接收其命名空间的流。

每次投递和任务事件的擦除都会获取同一个组织级的警告写入租约。插入使用现有的服务器端启动截止时间和执行上限；租约 TTL 超过工作窗口加上完整的发送上限。不确定的插入或取消会让该租约自行过期，因此在所有可能的发送都结束之前，擦除无法获取它。擦除保持其带标记的变更、轮询和恢复协议。发布前后的账本检查会使被擦除触及的观察结果失效；写入后的清理只针对该次投递的确切事件和序列。账本不可读时会拒绝发布。

警告行带有完整的身份元组、进程 actor 和派生的来源类别。用户擦除会删除其任务事件，残留普查会验证删除结果；命名空间擦除同时覆盖任务和事件。新增的列带有默认值，以兼容旧的写入方。警告的产生会等待每个存活副本都支持该迁移，因此在滚动升级期间，较旧的擦除实现不会漏掉含用户信息的警告行。集群状态未知时，发布会推迟到之后的检查。

<a id="activation-and-rollback"></a>

## 启用与回滚

用户上限和预算警告要求每个在线服务的构建都支持迁移 107。只要共享这些存储的任何部署运行较旧的构建，或其版本未知，就要让 `LOOM_DEFAULT_DAILY_USER_COST_CAP_USD` 和每个命名空间的 `daily_user_cost_cap_usd` 保持为零，并让 `budget_alert_inbox` 保持为空。在此期间不要依赖用户上限。先应用迁移并升级每个在线服务进程，再设置这些策略。警告的集群检查会在旧版本或未知版本的集群上推迟产生警告；它不会删除已存储的警告。

回滚之前，保存全局的用户上限默认值，以及每个命名空间的用户上限和警告收件箱。回滚需要一个维护窗口：

1. 停止所有可能检查预算或调度警告的请求服务进程和后台进程，涵盖共享这些存储的每个部署。同时停止状态轮询。仅关闭后台 worker 或清除收件箱策略，并不会停止已经用该收件箱调度的投递。
2. 清理之前，先排空已调度的投递，并让每个进行中或不确定的写入都有结论。等待警告写入租约被释放或过期，并等待它们有界的延迟启动窗口和服务器执行窗口结束。被中断的排空，或空的运行中查询列表，都不能证明延迟的发送不会再到达。
3. 只擦除 `event` 为 `budget.warning` 的 `loom.task_events` 行。等待删除在每个存储副本上完成，并在启动第一个旧版进程之前，验证所有副本上都没有残留的警告行。存在不可读的副本或尚无结论的写入时，不得回滚。命名空间擦除或用户擦除不能替代这一步：它们还会删除无关数据。
4. 在旧版构建提供服务期间，保持用户上限和警告处于禁用状态。待每个在线服务进程再次支持迁移 107 之后，恢复保存的全局默认值，并用 `namespace.register` 重新应用各命名空间的用户上限和警告收件箱。在恢复警告的产生之前，先读取命名空间策略并检查生效的上限。

这限制了混合版本运行期间的启用，并在回滚时以可用性换取隐私。旧版任务读取方不会过滤私有警告，旧版用户擦除也不会删除它们。旧版的命名空间注册同样会省略用户上限和警告收件箱这两列；它们的替换行会把这些策略重置为默认值。命名空间注册表不会让这些列在旧版写入中保留下来。因此运维人员必须自行保存并恢复策略，而不能指望它们在回滚后依然保留。

<a id="source-entry-points"></a>

## 源码入口

- `server/observability/budget.py`：`budget_snapshot` 为各项防护和状态读取策略与滚动支出。
- `server/tasks/app/budget_notifications.py`：`deliver` 负责警告的声明和擦除屏障。
- `server/tasks/store/repo.py`：`events_since` 在游标分页之前应用警告范围。
- `server/tasks/app/reads.py` 和 `server/tasks/app/watch_routes.py`：轮询和流式读取方绑定该范围。
- `server/erasure/store/steps_ledgers.py`：警告写入租约保护任务事件的删除。

<a id="invariants"></a>

## 不变量

- 具名用户的额度绝不会抬高命名空间的上限，归属也绝不会去猜测令牌主体。
- 范围被收窄的读取方不会收到其用户和会话范围之外的警告。
- 不确定的警告写入会让擦除一直处于屏障之下，直到其可能的发送结束。
- 通知失败绝不会改变上限判定。
