主题
自托管部署跑在你自己供给并付费的基础设施上，因此不受约束的用量最终会出现在你的账单与你的集群里。LlamaCloud 给了你两种互相独立的控制手段：
- API 速率限制约束一个 project 调用 API 的快慢。它们保护部署不被请求洪峰打穿，超出即以 HTTP 429 拒绝。
- 用量封顶约束一个组织或 project 在一天或一个月内可消耗多少 credit。它们保护你的预算，超出即以 HTTP 402 拒绝。
速率限制带着相当宽松的默认值出厂，用量封顶则默认关闭。两者都不能替代对方：速率限制压制的是请求频率，但长期来看不限制总花费；而用量封顶在预算耗尽之前允许任意请求速率。
用量封顶
用量封顶就是一个滚动窗口内的 credit 预算。窗口内的消耗达到上限后，继续创建任务的请求会被以 402 拒绝，并报 This <scope> has reached its <window> usage limit.。读操作不受影响 —— 被封顶的组织仍然可以取回它已提交任务的结果。
封顶适用于 Parse、Extract、Classify、Split 与 LlamaSheets 的任务创建。
开启封顶
封顶有三种模式，由 config.usageCaps.enforcementMode 设置：
| 模式 | 行为 |
|---|---|
off （默认） | 完全不做判定。在请求链路上没有额外开销。 |
observe | 对每个请求都判定并记录本应被拦住的结果，但照常放行。 |
enforce | 拒绝突破封顶的请求。 |
config:
usageCaps:
enforcementMode: observe
defaultDailyCredits: 5000
defaultMonthlyCredits: 100000defaultDailyCredits 与 defaultMonthlyCredits 是部署级默认封顶，会作用到每一个没有自己覆盖值的组织。留着不设，组织就等于不受限，此时 enforce 是个空转的开关 —— 模式是开关，credit 值才是那个上限。
注意
0 是一个封顶值，不是「没设封顶」。它表示零 credit，所以在 enforce 下会挡住它所适用的每个组织的任务创建。要让组织不受限，请省略这个键，而不是把它设成 0。
安全地推行一个封顶
一个数值设错了的封顶，会以 402 的形式落在你的用户身上。请按这个顺序走到 enforce：
- 先设 credit 值。 配上
defaultDailyCredits与defaultMonthlyCredits，enforcementMode: observe。光有模式并不强制任何东西；没有值的模式根本不做判定。 - 先在
observe下运行。 每个请求都被判定并放行，因此一个设得过低的上限只会让你多一行日志，而不是一次故障。 - 盯住「本应被拦住」的请求。 在
observe下，一次突破仍会在llamacloud_usage_cap_evaluations_total上计入blocked，并带上mode="observe"标签。这些就是enforce本会拒绝的请求，而它们背后的组织正是你要最先沟通的对象。 - 按一整个计费月来定量。 月末与季末才是真实用量的高峰；照一个清闲的两星期定的上限，之后会拒掉正当的工作。
- 切到
enforce，并对failed_open设告警。 退化的强制执行会悄无声息地不再拦截 —— 见封顶会 fail open。
组织级封顶与项目级封顶
封顶在两个层级上判定，任一层级被突破都会拦下请求：
- 组织：该组织名下所有 project 的 credit 总和。
- 项目：单独一个 project 的 credit。
被报告的是最紧的那个被突破的封顶，判定顺序为：项目日、项目月、组织日、组织月。
注意
项目的用量封顶从不继承 —— 不从它的组织继承，也不从部署级默认继承。
组织级封顶约束的是其所有 project 的合计。把同一个数字逐个加到每个 project 上，是一个大得多的预算，而不是同一件事。
设 defaultDailyCredits 会给每个组织封顶，但不会给任何项目封顶。
封顶会 fail open
若某个封顶无法解析，或用量读取失败、超时，请求会被放行。退化的封顶检查绝不会拦下正当工作 —— 但它也就此停止了强制执行，而且是无声的。请盯住 failed_open 这个结果来发现它：
| 指标 | 标签 | 含义 |
|---|---|---|
llamacloud_usage_cap_evaluations_total | outcome, mode | 封顶判定次数。outcome 取 allowed、blocked、failed_open 之一。failed_open 持续上升意味着强制执行已退化，而不是「什么都没拦」。 |
在 enforce 模式下，持续非零的 failed_open 比率应当被当作这个控制手段的一次故障，而不是「风平浪静」。
封顶检查读到的还是一个周期性聚合后的用量总数，而不是每落地一个任务就即时累加，因此它可能落后于最新的工作，从而放行一个「用量绝对新鲜时本会被拒」的请求。同样出于这个原因，一个组织的头几次封顶检查可能读到零，通常在其用量开始之后的一分钟以内。总数落定后，强制执行自己会追平。
API 速率限制
速率限制是按 project 的默认值，表达方式要么是每秒查询数，要么是窗口内的请求数。在 values.yaml 的 config.rateLimits 下设置它们：
config:
rateLimits:
parseApiCreationQueries: 500
parseApiCreationSeconds: 10
parseApiQueryQps: 80
parseApiListQps: 5| 取值 | 默认值 | 限制的是 |
|---|---|---|
parseApiCreationQueries / parseApiCreationSeconds | 500 per 10s | Parse 任务创建 |
parseApiQueryQps | 80 | Parse 任务读取 |
parseApiListQps | 5 | Parse 任务的 list 调用 |
extractApiCreationQps | 40 | Extract 任务创建 |
extractApiQueryQps | 80 | Extract 任务读取 |
extractApiListQps | 5 | Extract 任务的 list 调用 |
extractAgentCreationQps | 10 | Extract 智能体创建 |
classifyApiCreationQps | 40 | Classify 任务创建 |
classifyApiQueryQps | 80 | Classify 任务读取 |
classifyApiListQps | 5 | Classify 任务的 list 调用 |
splitApiCreationQps | 40 | Split 任务创建 |
splitApiQueryQps | 80 | Split 任务读取 |
spreadsheetCreationQpm | 60 | LlamaSheets 任务创建（每分钟） |
spreadsheetApiQueryQps | 80 | LlamaSheets 任务读取 |
spreadsheetApiListQps | 5 | LlamaSheets 任务的 list 调用 |
usageApiQueryQps | 20 | 用量指标 API |
list 类操作的默认值刻意最低：它们单次最贵，也最容易被循环刷出来。
为单个组织覆盖某个限制
部署级默认是整个集群的下限；单个组织通常要自己的数字。全局管理员在 Settings → Admin → Quota Management 里设覆盖值，可按名称或 id 搜索组织。
这个页面有两个视图：
- Overrides —— 只有某人特意为这个组织、或为其某个 project 设下的值。这些才是你可以修改或删除的行。
- All Limits —— 该组织当前解析出的全部限制，以及每个值的来源：它自己的覆盖值、其套餐档位，还是部署级默认。改数值之前用它的 effective 值核对一遍。套餐档位与部署级这两类值无法在这里删除。
Daily Usage Credits Limit 与 Monthly Usage Credits Limit 会覆盖单个组织所对应的部署级封顶，就如同速率限制条目覆盖它们各自的默认值一样。用覆盖值可以让一个高量组织免于部署级封顶，或把一个吵闹的组织压在其之下。
给单个项目封顶
添加日或月用量封顶时提供了一个 Applies to 选择：整个组织，或其下的某一个 project。选组织约束的是所有 project 的合计；选某个 project 只约束那一个 project。
只有用量封顶提供这个选择。其他所有限制都是继承来的，因此组织级覆盖已经管住了它的 project，再来一份项目级配置只是重复。也正因为封顶不继承，给项目封顶是约束它的唯一办法 —— 一个自己没有设封顶的项目，无论组织设成多少都不受限。
关于如何设置全局管理员，见全局管理员配置。
一个限制是如何解析的
每个限制都是一份额额，而份额按「从最具体到最不具体」的顺序解析：
组织覆盖值 → 套餐档位默认 → 部署级默认
三者中最先存在的那个胜出。某个限制能设在哪里、又会退回到哪里，随层级而不同：
| 层级 | 可从何处设置 | 向后回退到 | 什么都没设时的结果 |
|---|---|---|---|
| Organization | 管理界面覆盖值，然后套餐档位，然后 Helm values | 链条上下一个更一般的层级 | 部署级默认 |
| Project (rate limits) | 其组织，然后套餐档位，然后 Helm values | 链条上下一个更一般的层级 | 部署级默认 |
| Project (usage caps) | 在管理界面为该项目设的封顶 | 无 | 不受限 |
部署级默认来自你的 Helm values，而你的部署会在启动时把它们存下来。改动的值要等后端重启后才生效，不会在下一个请求上立刻生效。
组织覆盖值在管理界面设置，即时生效。
注意
清掉一个你先前设过的值，并不会移除它当时写入的默认。启动同步只负责写入与更新默认，从不删除它们。要解除一个已经生效的限制，请把它改成一个更高的值，而不是删掉那个键。
那次启动同步也是把 Helm values 带进部署的通道。如果你的配置把同步范围收窄到某几类份额，那么两种用量封顶必须在这个子集里 —— 否则 defaultDailyCredits 与 defaultMonthlyCredits 会被静默忽略。
查看一个组织消耗了多少
封顶的好坏，取决于你对当前用量的了解有多准。Settings → Admin → Global Usage 会按组织与 project 报告 credit 用量，用量指标 API 也暴露同样的聚合结果，便于导出到你们自己的报表里。安全地推行一个封顶一节的第 4 步就是从那里取数的。
相关配置
- 弹性伸缩配置 —— 按上面这些限制所放行的负载来给部署定规模。
- LlamaParse 吞吐 —— worker 与模型并发，它们约束的是被接受的工作能多快被处理。
- 全局管理员配置 —— 授予 Quota Management 页面所需的访问权限。