预算与限速

周期预算、模型级限额与速率限制三类配额约束的配置形态、重置周期与触发行为。讲清每一项约束如何独立校验、逐请求扣减，以及达额与超速时的拦截语义

预算与限速是灵渠平台在密钥之上的一层量化管控能力。密钥决定"谁能发请求、能调哪些模型"，预算与限速则决定"能花多少、能发多快"。两类约束都挂在治理对象上、逐请求校验、按实扣减：预算管花费（按周期累计金额），限速管频率（按周期累计请求数与词元数）。

本页讲清三类配额约束——周期预算、模型级限额、速率限制——各自的配置形态、重置周期与触发行为，以及一次请求如何被它们逐项独立校验。具体的额度数额与单价不在文档中固化，一律以服务协议与控制台为准；本页只规定口径形态与触发语义。

1. 三类配额约束概览

约束类型	管什么	作用维度	触发后
周期预算	花费金额	密钥 / 模型	阻断请求，达额暂停
模型级限额	单模型 / 全模型花费	全局 / 单密钥 × 模型	阻断对应模型的请求
速率限制	请求频率与词元吞吐	密钥	限流，超阈即拒

三类约束相互独立、同时校验：一次请求须通过全部适用约束才被放行；任一项耗尽即阻断。请求完成后，花费与频次会从全部适用的约束维度各自扣减。

2. 周期预算

周期预算为治理对象设定一个周期内花费上限。平台按统一计价词元口径，对每一次落账请求实时计费并累加到适用预算上；当本次请求的预估花费将使任一适用预算越限时，请求被阻断。

2.1 配置形态

预算以"上限金额 + 重置周期"声明，可挂在密钥维度或模型维度（模型维度见 §3）。为某把密钥设月度预算：

curl https://<平台入口地址>/api/v1/keys/<子账户标识>/budgets \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "budgets": [
      { "max_amount": "<日上限>", "reset_period": "1d" },
      { "max_amount": "<月上限>", "reset_period": "1M" }
    ]
  }'

字段	含义
`max_amount`	周期内花费上限（金额，口径以服务协议与控制台为准）
`reset_period`	重置周期（见 §5）

同一对象支持多条预算并行——例如同时设"日上限"与"月上限"，任一条耗尽即阻断。这样既能防单日突发花费，也能守住月度总盘。

2.2 重置方式：滚动与对齐

每条预算可选两种重置方式：

方式	行为	适用周期
滚动（默认）	自上次重置起经过一个完整周期后清零累计	全部周期
日历对齐	在每个自然周期边界统一清零（如每月 1 日零点）	仅日 / 周 / 月 / 年

curl https://<平台入口地址>/api/v1/keys/<子账户标识>/budgets \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "budgets": [
      { "max_amount": "<月上限>", "reset_period": "1M", "calendar_aligned": true }
    ]
  }'

日历对齐仅适用于日 / 周 / 月 / 年周期；小时及更短周期不支持对齐，提交不合法组合会被拒（400）。把一条既有预算改为日历对齐时，当前周期累计清零、重置基准对齐到当期起点。日历对齐让同一配置下所有对象在统一时刻重置，便于跨对象对账。

3. 模型级限额

模型级限额是对单个模型或全部模型设定的花费上限，独立于密钥的总预算。它提供两类口径：

作用域	含义	典型用法
全局	对全平台流量下某模型设硬上限	守住某旗舰模型的总花费，无论由哪把密钥触发
单密钥	对某把密钥下某模型设上限	限定一把密钥在某模型上的独立花费

模型级限额与密钥总预算叠加校验——一次请求须同时通过"模型级限额"与"密钥总预算"才放行。例如可对某旗舰模型设全局月上限，同时让单把密钥在该模型上另有独立日上限。

curl https://<平台入口地址>/api/v1/model-limits \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "model": "<旗舰模型中性名>",
    "scope": "global",
    "budgets": [
      { "max_amount": "<日上限>", "reset_period": "1d" },
      { "max_amount": "<月上限>", "reset_period": "1M" }
    ]
  }'

字段	含义
`model`	模型中性名；填 `*` 表示全部模型
`scope`	作用域：`global`（全局）/ `key`（单密钥，需附 `scope_id`）
`scope_id`	作用域目标（`scope=key` 时为密钥标识）
`budgets`	一条或多条预算（每条含 `max_amount` + `reset_period`）

全部适用的模型级限额都须通过请求才放行——一次耗尽了日上限的突发，会阻断该模型的后续请求直到重置，即便月上限尚有余量。模型级限额与密钥预算共用同一份用量底座，扣减口径一致。

4. 速率限制

速率限制按周期限定请求数与词元数两类阈值，用于平抑突发流量、保护上游稳定性。两类阈值并行校验，任一超阈即拒。

阈值类型	含义	示例口径
请求数限制	周期内可发起的请求条数上限	如「每分钟 N 条」
词元数限制	周期内可处理的词元总数上限（输入 + 输出）	如「每小时 N 词元」

curl https://<平台入口地址>/api/v1/keys/<子账户标识>/rate-limit \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "request_max": "<请求数上限>",
    "request_reset_period": "1m",
    "token_max": "<词元数上限>",
    "token_reset_period": "1h"
  }'

字段	含义
`request_max` / `request_reset_period`	请求数上限及其重置周期
`token_max` / `token_reset_period`	词元数上限及其重置周期

速率限制作用在密钥维度，是与预算正交的频率闸门——预算管"花了多少钱"、限速管"发得多快"。两者各自独立计量与重置，互不替代。

5. 重置周期

预算与速率限制共享一套重置周期格式：

周期	含义	常见用于
`1m` / `5m`	分钟级	速率限制（请求数节流）
`1h`	小时级	速率限制（词元数节流）
`1d`	天级	预算（防单日突发）/ 速率限制
`1w`	周级	预算
`1M`	月级	预算（月度花费控制）
`1Y`	年级	预算（年度盘子）

速率限制常用分钟 / 小时级周期，预算常用天 / 周 / 月 / 年级周期。日历对齐仅适用于日及以上周期（见 §2.2）。

6. 触发行为：逐项独立校验

一次请求到达时，平台对全部适用的配额约束逐项独立校验——任一项耗尽即阻断，请求不进入路由。下图给出校验与扣减的次序：

校验与扣减遵循以下规则：

规则	说明
全部通过才放行	速率限制、模型级限额、密钥预算中任一项耗尽，请求即被阻断
独立计量	每条约束各自记账与重置，互不影响
按实扣减	请求完成后，按上游返回的实际词元用量从全部适用约束扣减
缓存命中更省	命中缓存检查点时按缓存档计量，单价相对更低，对预算的占用更小
达额暂停	账户层汇总信用额度达上限时，全部密钥一并暂停（无逐密钥子额度）

一次典型的预算扣减示意：

请求前：
  - 模型级月上限：余 <月余额>
  - 密钥日上限：  余 <日余额>
  - 速率限制：    余 <频次余量>
  → 三项均有余，放行

请求后（本次实际花费 <本次花费>）：
  - 模型级月上限：扣减 <本次花费>
  - 密钥日上限：  扣减 <本次花费>
  - 速率限制：    请求数 +1、词元数 + 本次用量
  → 若日上限就此耗尽，下一请求被阻断（429 quota_exceeded），直到日周期重置

配额拦截以平台错误结构返回（与 API 参考一致）：预算 / 模型级限额耗尽，以及密钥因达汇总信用额度被暂停，统一返回 429 quota_exceeded；速率超阈返回 429 rate_limited / token_limited（错误码细分 quota_exceeded 与 rate_limited / token_limited，便于调用方区分"花完了"与"发太快了"）；密钥因人工停用被拒返回 403 key_suspended。各类拦截在控制台「信用额度」与「用量明细」页可追溯到对应的扣减明细。