动态限流 (RPM/TPM) 与周期配额 (Budget)

在企业级大模型应用接入与高并发调度场景中，流量与算力消耗的失控是引发基础设施雪崩和账单透支的最核心风险。传统基于单纯 QPS 或 IP 的限流策略在大模型网关场景下彻底失效：一方面，内部微服务集群通常使用相同的出口 IP，粗粒度 IP 限流无法精准识别具体调用方；另一方面，大模型推理对算力资源的消耗具有极其特殊的“非对称性”——一次请求可能仅包含十几个 Token，另一次请求却可能携带数万字的长文档、复杂 Agent 思考链，瞬间吞吐数十万 Token 并耗尽 GPU 显存与计算带宽。

此外，仅控制瞬时并发速率并不能解决长期无序消耗的问题。若缺乏周期性的用量上限约束，单个业务系统的死循环或全量数据密集批处理，将在数小时内打满整个平台的所有可用额度。

OmniCortex 构筑了“瞬时防爆（RPM/TPM 速率限流）”与“周期防穿（Budget 周期配额限额）”双重流量与用量防线。网关将管控能力原生融合在模型访问策略（Access Profiles）与虚拟密钥（Virtual Keys）中，在请求入口处即时判决。一旦检测到瞬时频次超标、Token 吞吐超标或周期总额度耗尽，网关即刻拦截并返回标准错误响应，从源头阻止无效流量透传，保障后端大模型基础设施的稳定可靠。

核心机制与业务场景

1. 瞬时限流：RPM 与 TPM 双轨协同防护

针对大模型场景下请求频次与算力开销脱节的问题，系统在入口流量评估中全面引入双重指标门禁：

RPM (Requests Per Minute - 每分钟请求数)：
- 防御目标：防范客户端高频轮询、代码递归死循环与突发流量冲击；
- 运行逻辑：统计当前 1 分钟时间窗口内发起的请求总次数。达到上限后立即拒绝后续请求，防止上游连接池被占满。
TPM (Tokens Per Minute - 每分钟 Token 吞吐量)：
- 防御目标：防范超长 Prompt 注入、密集长文本生成与恶意批量吞吐；
- 运行逻辑：动态累加请求输入（Prompt Tokens）与模型输出（Completion Tokens）的总和。即便请求并发极低（例如仅 5 RPM），只要累计消耗的 Token 吞吐超过设定的 TPM 阈值，网关同样执行精准拦截，保障 GPU 显存水位与推理算力公平共享。

2. 周期限额：Budget 配额管控与自然月对齐

速率限制（RPM/TPM）负责“瞬时”防爆，而周期限额（Budget）则负责“长效”防穿：

多周期阶梯支持：支持按天（Daily）、按周（Weekly）、按月（Monthly）或按自然日历月（Calendar Monthly）设定算力消费额度上限；
自然日历对齐 (Calendar Aligned)：开启后，额度重置周期将严格与自然月首日（每月 1 号零点）自动对齐并清零重置，完美贴合企业财务预算与月度业务核算周期；
超额即时阻断熔断：系统实时累计当前周期内的算力消耗金额。一旦达到设定的最高限额，网关立即拒绝该凭据后续的所有调用请求，直至下一个周期自动重置或管理员介入临时调额。

3. 双层管控机制与未来演进路线

在大规模企业架构中，OmniCortex 采取了清晰的双层流量与配额管控架构：

🌐 1. 全局层 · 上游算力供应商级防护 (Provider Rate Limit)

通道物理承载上限

针对各大模型供应商通道设立全局吞吐阈值，防止突发高并发打垮物理集群或触发云端账号封控。

↓ 下发受控凭据与策略

🔑 2. 凭据层 · 虚拟密钥实例级限流与限额 (Virtual Key Limits & Budgets)

速率 + 周期额度双保险

终端业务系统持虚拟密钥接入；支持继承「模型访问策略 (Access Profiles)」标准基线或自主个性化配置独立的 RPM/TPM 与最高消费限额。

↓ 主体归属与权责绑定

👥 3. 主体归属 · 团队 (Team) 与个人用户 (User) 权责归集

部门与人员隔离闭环

个人与部门的流量限制完全通过其所持有的虚拟密钥实现，确保非核心业务异常流量被 100% 隔离在其凭据沙箱内。

第一层：上游算力供应商级防护 (Provider-Level)：针对接入的各大模型供应商设立通道级全局吞吐防护门限，防止特定供应商被突发流量刷爆或触发云端账号封禁；
第二层：虚拟密钥凭据级隔离 (Virtual Key Level)：终端微服务均持有网关分发的虚拟密钥（可继承策略模板，亦可独立覆写）。个人与团队的流量与限额，完全通过为其颁发绑定的虚拟密钥实现——每个凭据拥有清晰独立的 RPM、TPM 与周期消费额度。

🚀 演进规划：主体级全局聚合限流与限额 (Roadmap)

在当前版本中，个人与团队的管控通过其名下绑定的各把虚拟密钥独立生效。在未来的版本演进规划中，系统将支持更高维度的主体级全局聚合限流与限额：

个人多密钥全局管控 (Single User Multi-Keys)：当一名研发人员名下持有多个不同业务或沙箱环境的测试凭据时，支持在用户主体层面对其所有凭据的累计用量实施全局汇总限流与限额；
团队组织级全局配额 (Team-Level Aggregate)：支持为整个部门或业务线设置总流量与消费天花板，无论部门内部衍生申请了多少把业务密钥，该部门名下的总消耗均无法突破团队统一设定的配额底线。

4. 统计周期与自动平滑重置

瞬时速率重置：RPM 与 TPM 严格按自然分钟（1m）为周期统计，到达下一分钟后自动清零重置，业务调用即可正常继续；
周期配额重置：限额按设定的重置周期（天/周/月/自然月）自动重置。若开启日历对齐，每月 1 号零点用量归零，进入全新配额周期；
多节点集群同步：在多网关节点分布式部署模式下，系统自动在节点间同步各凭据的实时速率与累计消耗，确保防护规则全局一致生效。

5. 流量与配额双重门禁判决流程

🛡️

流量限流与周期配额双重门禁判决流程

业务请求接入 ➔ 凭据规则提取 ➔ 瞬时速率校验 ➔ 周期额度校验 ➔ 放行 / 阻断

双重门禁 · 零额外损耗

1. 业务客户端携带虚拟密钥发起调用 (POST /v1/chat/completions)

网关提取凭据 ID ➔ 加载对应的限流（RPM/TPM）与周期限额（Budget）规则基线

↓

⚡ 门禁一：瞬时速率检验 (RPM & TPM)

当前分钟请求数或 Token 吞吐是否超标？
• 未超标：速率正常，进入配额校验
• 已超标：即刻拦截，返回 HTTP 429

💰 门禁二：周期配额检验 (Budget Limit)

当前周期累计消费金额是否超过上限？
• 未超额：额度充裕，放行请求
• 已超额：即刻熔断，拒绝本次调用

↓

✅ 校验通过 (Allow)

路由至最优模型通道并实时累加吞吐与用量

⛔ 拦截熔断 (Blocked)

入口阻断，返回明确错误提示，零算力损耗

企业控制台配置导览

在控制台架构中，OmniCortex 将限额与限流深度固化在「模型访问策略」与「虚拟密钥」中，实现企业统一定义与实例弹性微调。

1. 模型访问策略中的基线配置

管理入口：「模型与治理」➔「模型访问策略」。

管理员在为团队制定标准化访问策略时，可同时设立消费限额与速率限制基线：

点击「新建策略」或编辑现有策略，右侧滑出配置抽屉；
配置消费限额 (分区 3)：
- 点击「添加预算配置」新增一行配额规则；
- 设定最高限额（如 $100.00）与重置周期（每天 / 每周 / 每月 / 自然月）；
- 在顶部基础信息中可开启「自然月日历对齐」开关；
配置速率限制 (分区 4)：
- 设定 TPM 限制（每分钟 Token 吞吐上限，步长 1,000）；
- 设定 RPM 限制（每分钟请求调用上限，步长 10）；
保存后，策略列表表格清晰呈现设定的限额与限流指标。

📸 截图替换指引（图 1：模型访问策略中的配额与限流基线配置）

需截图内容：进入「模型访问策略」抽屉，展示第 3 分区「消费预算配置」与第 4 分区「速率限制配置」区域。
关键画面要素：
1. 抽屉主标题「新建/编辑模型访问策略」；
2. 第 3 分区包含最高限额输入框（如 $100.00）与重置周期下拉选择器；
3. 第 4 分区包含 TPM 与 RPM 数字步进器；
4. 底部包含取消与保存操作按钮。
推荐保存路径：
- 中文版：Documentation/docs/public/images/rate-limits-and-budgets/zh/access-profile-rate-and-budget.png
- 英文版：Documentation/docs/public/images/rate-limits-and-budgets/en/access-profile-rate-and-budget.png

2. 虚拟密钥中的应用与受管锁定态

管理入口：「模型与治理」➔「虚拟密钥」。

虚拟密钥作为承载具体业务调用的终端实体，支持两种配置模式：

策略集受管模式 (Managed Mode)：关联访问策略集后，密钥严格继承策略集的限额与限流规则。抽屉中展示紫色锁定标签（已从策略集继承规则，当前处于托管锁定状态），输入框置灰保护；
独立自由配置模式 (Custom Mode)：未绑定策略集时，管理员可直接在该密钥抽屉中手动设定专属的消费限额与 RPM/TPM；
看板监视态：表格「限流规则」列展示黄色闪电（⚡ 100k TPM）与蓝色循环（🔄 600 RPM）胶囊徽标；详情抽屉可直观查看当前周期的消费金额进度条。

虚拟密钥中的配额与限流规则展示

📸 截图替换指引（图 2：虚拟密钥中的配额与限流规则展示）

需截图内容：展示虚拟密钥列表表格的「限流规则」列与详情抽屉中的消费额度监控。
关键画面要素：
1. 虚拟密钥表格的「限流规则」列，展示包含黄色图标的 ⚡ 100k TPM 与蓝色图标的 🔄 600 RPM 胶囊徽标；
2. 抽屉中展示紫色的锁定提示条说明；
3. 资产详情抽屉中的用量进度条与限额说明。
推荐保存路径：
- 中文版：Documentation/docs/public/images/rate-limits-and-budgets/zh/virtual-key-rate-and-budget.png
- 英文版：Documentation/docs/public/images/rate-limits-and-budgets/en/virtual-key-rate-and-budget.png

3. 生产紧急临时调额 (Budget Override)

在实际生产运行中，业务线可能会面临突发大促、大规模数据回测等临时性高吞吐需求，原有的月度限额可能提前耗尽。为避免调整全局策略集基线影响其他业务，控制台提供了无侵入的临时调额机制：

在虚拟密钥表格操作列或详情抽屉中，点击「临时调额」按钮；
弹出 「临时调额 (Budget Override)」 模态框；
输入调额追加金额：设定在基础额度之外允许额外使用的临时上限金额；
选择调额有效期限：
- 单次/指定周期 (cycles)：设定生效的周期数（如 1 个周期），指定周期结束后自动回归基线额度；
- 持续生效 (indefinite)：持续生效直至管理员手动在弹窗中点击「恢复基线」清除；
保存后立即生效，业务调用无缝恢复，且不改变底层的策略集模板。

虚拟密钥临时调额弹窗

📸 截图替换指引（图 3：虚拟密钥临时调额弹窗）

需截图内容：在虚拟密钥列表或详情抽屉中点击「临时调额」弹出的模态框。
关键画面要素：
1. 模态框标题「临时调额」；
2. 顶部基础限额（Base Limit）与当前已用金额（Current Usage）对比卡片；
3. 调额金额输入框（如 $50.00）；
4. 有效期单选组（持续生效 / 指定生效周期数）；
5. 底部包含取消与保存按钮。
推荐保存路径：
- 中文版：Documentation/docs/public/images/rate-limits-and-budgets/zh/virtual-key-budget-override-modal.png
- 英文版：Documentation/docs/public/images/rate-limits-and-budgets/en/virtual-key-budget-override-modal.png

4. 核心配置项速查

配置项	归属模块	说明与建议
RPM 限制	瞬时限流	每分钟最大请求次数。防范循环刷量与突发并发冲击，留空表示不限制。
TPM 限制	瞬时限流	每分钟最大 Token 吞吐总量。防范长文本独占推理显存，留空表示不限制。
最高消费限额 (USD)	周期配额	当前周期内允许消耗的算力金额上限。超额后即刻熔断阻断调用。
重置周期 (Reset Period)	周期配额	额度统计的时间窗口，支持按天（`1d`）、按周（`7d`）、按月（`30d`）或自然日历月。
日历对齐 (Calendar Aligned)	周期配额	开启后固定在每月 1 号零点对齐重置额度，贴合企业财务周期。
临时调额 (Override Amount)	临时调额	突发业务临时追加的额度，可设置自动生效周期数，免侵入策略基线。

触发拦截时的系统反馈

当业务系统的调用频次、Token 吞吐或周期消费额度超出设定阈值时，网关在入口处即刻拦截请求并返回明确响应：

1. 瞬时速率超限响应 (HTTP 429)

当请求频次或 Token 吞吐超出限制时，返回标准 HTTP 429 Too Many Requests：

json

{
  "error": {
    "message": "Rate limit exceeded: request limit exceeded (601/600, resets every 1m)",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

响应信息中会明确告知是请求频次超标（request limit exceeded）还是 Token 吞吐超标（token limit exceeded），且响应头中会附带 Retry-After 提示建议等待重试的秒数（待下一个自然分钟自动重置）。

2. 周期配额耗尽响应 (HTTP 403 / 429)

当该密钥在当前周期内的累计消费已达到最高限额时，网关即时熔断阻断调用：

json

{
  "error": {
    "message": "Budget exceeded for virtual key (current usage: $100.25, limit: $100.00)",
    "type": "budget_exceeded_error",
    "code": "budget_exceeded"
  }
}

响应中清晰呈现当前已消耗金额与限额数值。业务方收到该报错后，应联系管理员在控制台核查用量，或通过「临时调额」为该密钥追加额度。

常见问题与排查指南

异常现象 / 错误信息	根本原因排查 (Root Cause)	推荐处置方案
请求返回 429 `request limit exceeded (RPM)`	业务端瞬时并发发包频率过高，打满每分钟请求次数上限。	1. 检查客户端是否存在异常重试或高频轮询代码； 2. 若属业务高峰期正常增长，在策略集或密钥配置中调大 RPM 门限。
请求返回 429 `token limit exceeded (TPM)`	业务请求单次携带超长文本或上下文过大，分钟级 Token 吞吐池耗尽。	1. 检查客户端是否开启了 Prompt 自动截断或切片； 2. 若属大文档批处理业务，为其申请专用密钥并提高 TPM 配额。
请求返回 `budget exceeded`	该虚拟密钥在当前统计周期内的累计消费金额已达到最高限额，触发安全熔断。	1. 在密钥列表或详情抽屉中核查该周期的实际用量； 2. 紧急情况下点击「临时调额」快速追加指定额度恢复业务，或等待下一自然周期自动重置。
配置项在抽屉中置灰不可修改	虚拟密钥处于「策略集受管模式」，限额与限流规则由关联的模型访问策略统一固化。	1. 前往「模型访问策略」修改全局基线； 2. 若当前密钥确需个性化权限，在密钥编辑抽屉中解除策略集关联转为独立配置。
分布式多节点部署下偶发统计微小差异	网关各工作节点间存在瞬时网络抖动，导致节点间流量统计同步偶发滞后。	系统在进入下一统计周期后将自动拉平全局计数；同时排查多节点间的内部网络健康度。

动态限流 (RPM/TPM) 与周期配额 (Budget) ​

核心机制与业务场景 ​

1. 瞬时限流：RPM 与 TPM 双轨协同防护 ​

2. 周期限额：Budget 配额管控与自然月对齐 ​

3. 双层管控机制与未来演进路线 ​

4. 统计周期与自动平滑重置 ​

5. 流量与配额双重门禁判决流程 ​

企业控制台配置导览 ​

1. 模型访问策略中的基线配置 ​

2. 虚拟密钥中的应用与受管锁定态 ​

3. 生产紧急临时调额 (Budget Override) ​

4. 核心配置项速查 ​

触发拦截时的系统反馈 ​

1. 瞬时速率超限响应 (HTTP 429) ​

2. 周期配额耗尽响应 (HTTP 403 / 429) ​

常见问题与排查指南 ​