治理与配额
灵渠平台的三层治理模型——账户归属、密钥发放、预算与限速。一页讲清密钥/预算/限速如何协同约束每一次查询请求，再分页指引到密钥治理与预算限速两节
治理与配额是灵渠平台在中间件管道之外的一层企业管控能力。中间件管道决定每一次查询请求"怎么被处理"（路由、缓存检查点、安全护栏），治理与配额则决定"谁能发请求、能花多少、能发多快"。两者在同一条请求路径上协同：请求进入平台后，先经治理校验（密钥是否有效、归属是否清晰、预算与限速是否还有余量），通过后才进入中间件管道的路由与上游调用。
本节面向部署、运维与集成灵渠平台的内部管理员，讲清三件事：平台用什么样的层级模型组织治理对象、密钥怎样发放与归属、预算与限速如何约束每一次请求。具体的额度数额、单价与计费口径不在文档中固化，一律以服务协议与控制台为准。
1. 三层治理模型
灵渠的治理对象自上而下分三层。上层提供组织归属与汇总口径，下层承载具体的请求凭据与逐请求约束——一次请求的每一项治理判定，都能沿这条链路向上追溯到明确的归属。
| 层级 | 治理对象 | 承载能力 | 主要读者 |
|---|---|---|---|
| 账户层 | 企业账户 | 组织归属的最高层；汇总用量、汇总信用额度、账单结算口径都落在账户层 | 客户 Portal / 运营控制台 |
| 密钥层 | API 密钥子账户 | 按部门 / 业务线 / 成本中心发放的请求凭据；逐请求归属分账、访问范围约束、按密钥路由约束 | 客户应用（数据平面鉴权） |
| 约束层 | 预算 / 限速规则 | 挂在密钥或模型维度上的周期预算、模型级限额、速率限制；逐请求扣减与拦截 | 控制台配置 |
同源原则。 三层治理对象共享同一份用量底座。一把密钥的逐请求用量，向上汇入账户层的汇总用量与信用额度；同一条请求在密钥维度、账户维度看到的数字相互对得上。治理判定不另起一套计量，而是复用平台统一的计价词元口径。
下图给出三层治理对象的归属关系，以及一次请求在这条链路上被依次校验的次序：
2. 三层治理能力速览
| 能力域 | 作用对象 | 治理形态 | 详见 |
|---|---|---|---|
| 密钥发放与归属 | API 密钥子账户 | 按维度发放、必需请求头、有效期、启停与轮换 | 密钥治理 |
| 访问范围约束 | API 密钥子账户 | 限定可调用的模型范围；越权模型在路由前被拒 | 密钥治理 |
| 按密钥路由约束 | API 密钥子账户 | 把某把密钥的流量约束到指定上游分组 / 模型范围 | 密钥治理 |
| 周期预算 | 密钥 / 模型维度 | 按周期设定花费上限，达额阻断，支持滚动与对齐两种重置 | 预算与限速 |
| 模型级限额 | 模型维度（全局 / 单密钥） | 对单个模型或全部模型设花费上限，独立于密钥总预算 | 预算与限速 |
| 速率限制 | API 密钥子账户 | 按周期限定请求数与词元数，平抑突发流量 | 预算与限速 |
3. 治理与请求路径的衔接
治理判定发生在请求进入中间件管道之前，作为路由前置的一道闸门。一次请求在治理与管道之间的衔接如下：
| 阶段 | 治理动作 | 通过 / 拒绝 |
|---|---|---|
| 入站鉴权 | 校验 API 密钥有效性与归属，解析必需请求头 | 缺失或失效 → 401；缺必需头 → 400 |
| 访问范围 | 比对请求模型是否在密钥允许范围内 | 越权模型 → 403 |
| 配额校验 | 逐层检查预算与限速余量（密钥预算、模型级限额、速率限制） | 任一项耗尽 → 429；预算耗尽细分见预算页 |
| 放行入管道 | 全部通过后，请求进入路由中间件，按复杂度择优转发上游 | 进入 中间件管道 |
| 落账回扣 | 上游响应返回后，按实计量并从全部适用的预算 / 限速维度扣减 | 计量落账，更新各层余量 |
治理面与生成面的边界。 治理判定只决定"放行或拒绝、扣减多少"，不改写请求或响应内容，也不参与生成。内容生成由路由选定的上游模型完成，与 中间件管道的能力边界 一致。配额扣减以上游返回的实际词元用量为准，缓存命中档单价相对更低。
4. 拒绝与状态语义
治理拦截统一以平台错误结构返回（与 API 参考 的错误约定一致），错误码标明拦截原因，便于调用方本地化处置：
| 状态码 | 错误码示例 | 触发原因 |
|---|---|---|
400 | missing_required_headers | 请求缺少平台要求的必需头 |
401 | key_invalid | 缺失或无效的 API 密钥 |
403 | model_blocked | 请求的模型不在该密钥的允许范围内 |
403 | key_suspended | 密钥被人工停用 |
429 | quota_exceeded | 适用预算 / 模型级限额耗尽，或账户汇总信用额度达上限被暂停 |
429 | rate_limited / token_limited | 触发速率限制（请求数或词元数超阈） |
各错误码的具体取值与文案以平台运行态为准。预算类拦截在控制台「信用额度」与「用量明细」页可追溯到对应的扣减明细。
下一步
- 密钥治理：API 密钥的发放维度、必需请求头、访问范围与按密钥路由约束、有效期与轮换。
- 预算与限速：周期预算、模型级限额、速率限制的配置形态、重置周期与触发行为。
- API 参考 · 控制平面：密钥、信用额度等治理接口的端点契约。
- 中间件管道：治理放行后，请求在路由 / 缓存检查点 / 安全护栏三类中间件中的流转。