# 预算、配额与限流

来源: https://platform.lyrouter.com/ai_gateway/docs/quota
更新日期: 2026-10-22

LYRouter 有两种用量上限：API Key 的「预算限额」只约束这一把 Key，由 Key 创建者或当前账号管理员在 Key 设置中填写；安全围栏的「配额管理」策略由当前账号管理员按工作空间、部门、组织成员或 API Key 设置，可以按信用点或百万 Token 计量、按月或按天清零，并给个别成员设例外。任一上限用完，之后的请求返回 429，到 `reset_at` 之后恢复。配额只限制用量，与组织的信用点余额是两回事。

## Key 预算与配额策略

| | API Key 预算 | 安全围栏配额策略 |
| --- | --- | --- |
| 在哪里设置 | **API 密钥** 页创建或编辑 Key 时的「预算限额」步骤 | **安全围栏** 的「配额管理」页签 |
| 谁能设置 | Key 的创建者（在该工作空间是编辑者或管理员）和当前账号管理员 | 当前账号管理员，团队版起可用 |
| 约束谁 | 这一把 Key | 工作空间、部门、组织成员或 API Key |
| 计量 | 「费用预算（元）」和「Token 预算（百万 Token）」 | 「信用点」或「Token」（按百万 Token 填写） |
| 周期 | 「每月」（每月 1 日 0 点重置）和「总计」（不重置），留空表示不限制 | 「每月」（可设清零日）、「每天」、「累计总量」 |
| 多人分摊与例外 | 无 | 「共享」「按用户」「按 API Key」，可给成员设例外 |
| 速率限制 | 无 | 可选每分钟请求数（RPM）、每分钟 Token 数（TPM） |
| 触顶后 | 拒绝请求 | 「阻断」拒绝请求，或「告警」只通知不拦截 |

- **同时生效**：Key 预算、各层配额策略和 BYOK 通道自身的额度相互独立，任一项用完都会拒绝调用。
- **费用预算换算**：「费用预算（元）」按平台汇率换算成信用点执行，所以触顶报错中的指标是 `credits`，`limit`、`used` 也以信用点为单位。
- **时间按北京时间**：每月、每天的清零时间都按北京时间计算。

## 配置配额策略

当前账号管理员在 **安全围栏** 的「配额管理」页签点「新建配额管理策略」：

1. **生效对象**：选择「工作空间」「部门」「组织成员」或「API Key」。选工作空间或部门时，还要选「配额模式」，见下节。
2. **策略规则**：
   - 「计量单位」：「信用点」直接按信用点填写；「Token」以百万 Token 为单位，填 `10` 即 1000 万 Token，下方显示「实际 Token 数」。
   - 「额度上限」：正整数。
   - 「统计周期」：「每月」在「清零日」00:00（Asia/Shanghai）清零，清零日可填 1～28，默认 1；「每天」每日 00:00 清零；「累计总量」不自动清零。
   - 「触顶预警阈值」：默认 80%，用量达到这个比例时发一次提醒：「按用户」「按 API Key」的配额同时提醒对应成员和管理员，「共享」配额只提醒管理员；填 0 关闭，最大 99。
   - 「例外成员」：见下文「配额例外」。
   - 「限流设置（可选）」：RPM、TPM 按每分钟计算，独立于主额度，不受例外影响。
   - 「执行动作」：「阻断」或「告警」。
3. **生效时间**：立即或定时生效，可设失效时间。

（截图：配额策略的规则：计量单位、额度上限、统计周期、清零日、触顶预警阈值与执行动作。）

### 计数方式

| 配额模式 | 含义 | 例：上限 5000 信用点 / 每月 |
| --- | --- | --- |
| 共享 | 范围内所有调用合计一份额度 | 全空间合计 5000，用完后范围内所有人都被拒绝 |
| 按用户 | 范围内每个成员各一份额度 | 每个成员每月各 5000 |
| 按 API Key | 范围内每把 Key 各一份额度 | 每把 Key 每月各 5000 |

- 生效对象是「组织成员」时，统计该成员创建的全部 Key 的用量合计；是「API Key」时，统计这把 Key 自己的用量。
- 生效对象是「部门」时，只统计创建人主部门恰好是该部门的 Key，不含子部门。
- 「共享」模式的策略可以在策略详情的「共享池用量」查看已用量；计数暂时读不到时显示「暂不可用」。

（截图：生效对象选择部门，并在「共享」「按用户」「按 API Key」三种配额模式中选择。）

### 配额例外

配额例外用来给少数成员一个不同于默认值的额度，可以更高，也可以更低。它只出现在生效对象为「工作空间」或「部门」、配额模式为「按用户」的策略中；「共享」是一个总额，不支持例外，要单独放开某人请改用「按用户」。

- **添加**：在「例外成员」中点「添加成员」或「按部门添加」，为每人填写「额度」。未列出的成员按默认额度执行。
- **有效期默认「到本周期结束」**：例外与配额清零同时到期，到期时用量也一起归零，不会有人因此被突然拒绝。也可以选「长期有效」，或选「指定日期」设置一个未来的到期时间。「累计总量」没有周期边界，没有设置「指定日期」时，例外一直有效，直到删除。
- **按部门添加是一次性快照**：默认包含子部门，把所选部门当下的成员逐一加为例外。之后新加入部门的人不会自动获得例外，调离的人仍保留例外并标注「已调岗」，可以点「重新同步该部门」。生效对象是部门时，只会加入主部门恰好是该部门的成员。
- **上限 80 条**：单条策略最多 80 条例外，已失效的也计入。已失效的例外折叠在列表底部，可以「延期」到下一个周期边界，或删除。
- **删除或调低立即生效**：上限马上回落，而本周期已用的量不清零。已用量超过新上限的成员，下一个请求就会被拒绝，直到本周期重置；控制台会在删除或调低前再确认一次。

### 修改统计周期会清零用量

修改「统计周期」或「清零日」后，本周期已统计的用量归零，所有人从 0 重新计算，保存前控制台会再确认一次。只调整「额度上限」或例外额度不会清零用量。

## 用完之后

阻断型配额或 Key 预算用完后，请求返回 429：

| 字段 | 含义 |
| --- | --- |
| `error.message` | `rate limit exceeded on <对象> <指标>/<窗口>`，例如 `rate limit exceeded on ws credits/month` |
| `limit`、`used` | 上限和已用量 |
| `reset_at` | 恢复时间；「总计」「累计总量」没有恢复时间 |
| `policy_code`、`policy_name` | 只在安全围栏配额策略触发时出现，可据此区分配额策略与 Key 预算 |

- 用量在请求完成后才计入，越过上限的那次请求会正常完成，下一次才被拒绝。
- 「告警」动作的配额触顶后不拦截，只记录安全事件并通知；同时适用的其他阻断型限制照常生效。
- 对象、指标、窗口的取值和重试方法见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。需要提高额度时，Key 预算请 Key 创建者或账号管理员修改，配额策略请账号管理员调高上限或添加例外。

## 成员查看「我的配额」

成员在控制台 **概览** 页的「我的配额」卡片查看适用于自己的配额，每个可访问的工作空间各一张卡片：

- 「按用户」的配额显示已用量、上限、「剩余 N」和重置时间，剩余比例最低的一条排在最前，有多条时可以「展开全部」。
- 「共享」的配额显示「共享」和「本空间共用 X 信用点 / 本月」，不显示个人用量。全空间额度用完后，范围内的调用都会被拒绝。
- 成员有例外时显示「专属额度」；例外到期时间与重置时间不同时，卡片会提示到期后上限回落到默认额度。
- 没有任何适用配额时显示「无限额」。挂在单个 API Key 上的配额和 Key 预算不在卡片中，「按 API Key」计数的配额也只显示上限，已用量位置显示「暂不可用」。
- 程序也可以读取响应头 `x-aigw-quota-<指标>-remaining` 等获取剩余量，见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

## 配额与余额

配额是调用上限，余额是组织的信用点余额，两者分别检查。配额还有剩余时，余额不足仍会返回 402 `insufficient credit balance`；余额充足时，配额用完照样返回 429。充值不会增加配额，调高配额也不会增加余额，见[计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing)。

## 常见问题

### 「我的配额」显示「无限额」，为什么还收到 429？

**答：** 看报错原文中的对象。`apikey` 表示这把 Key 自己的预算或挂在 Key 上的配额已用完，这些不显示在卡片中，请 Key 创建者在 **API 密钥** 页查看预算；`api_key_circuit_open` 是错误率熔断，与配额无关，见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)。

### 调高上限后多久生效？

**答：** 保存后几秒内同步到网关。调高上限不会清零已用量，已用量低于新上限后即可继续调用，不需要更换 API Key。