虚拟密钥
/v1 调用用虚拟密钥鉴权,不是提供商那把上游 key。在管理台 虚拟密钥 页创建,创建时弹窗给出完整 vk-...,列表默认脱敏,可再查看或复制。
字段
| 字段 | 说明 |
|---|---|
| 名称 | 统计和日志里的标识 |
| 每小时请求数 | rph_limit,按墙钟小时计数,0 表示不限;被拒绝的请求不计数 |
| 并发上限 | concurrency_limit,同时在飞的请求数,0 表示不限;流式请求占到响应结束 |
| 日限额 | daily_budget_usd,美元,跨日后重新从 0 计;0 表示该窗口不限额 |
| 月限额 | monthly_budget_usd,美元,跨月后重新从 0 计;0 表示该窗口不限额 |
| 告警阈值 | warn_threshold_pct,百分比,0 表示继承全局值 |
| 授权路由 | 空 = 所有逻辑路由和 provider/model 直达;非空 = 只能打白名单里的逻辑路由名,不能用直达语法绕过 |
| 状态 | 可停用,停用后立即不能调 /v1 |
客户端这样带:
Authorization: Bearer vk-xxxx
管理台登录账号(config.yaml 里的 admin.username / password)管的是 Web 界面,和虚拟密钥是两套凭证。本地免登录时,管理台不用密码,但 /v1 仍然必须用虚拟密钥。
超限时的行为
| 情况 | HTTP | 错误码 | 响应头 |
|---|---|---|---|
| 小时请求数超限 | 429 | rate_limit_exceeded | X-RateLimit-Limit-Requests |
| 并发超限 | 429 | concurrency_exceeded | X-Concurrency-Limit |
| 日限额用满 | 402 | budget_exceeded | X-Budget-Limit、X-Budget-Used |
| 月限额用满 | 402 | budget_exceeded | X-Budget-Limit、X-Budget-Used |
小时请求数和并发都是进程内计数,进程重启清零,多实例各自计数、不共享。日/月额度落库,多实例共享同一份数据库时按库里的已用金额判断。
额度到达阈值或刚好用满时,会按 通知与告警 的配置推送提醒;提醒是软性的,不会因为告警失败而放行或拦截请求。
用量与重置
- 管理台虚拟密钥页可以查看当日/当月已用金额,并重置预算
- 历史消耗从请求日志按密钥汇总,不在密钥行上保留累计额
- 门户里使用者可以查看自己的用量,见 密钥门户
定价和汇率在 运行设置 与模型的计费字段里配。额度按折算后的美元累计。
授权路由与白名单
- 空授权 = 不限制:所有逻辑路由和
provider/model直达都可用 - 非空 = 只能调用白名单里的逻辑路由名;不能用
provider/model绕过 allowed_routes解析失败时,管理台会显示「配置异常」。此时不是「不限路由」,而是该密钥的全部逻辑路由都会被拒绝,需要修好配置
和路由的关系
- 请求
model: "glm"→ 命中名为glm的路由 → 按权重选物理模型 → 再按密钥权重选一把 key - 请求
model: "openrouter/anthropic/claude-3.5-sonnet"→ 没有同名路由时,直达该提供商下的物理模型 - 受限虚拟密钥不能用第二种写法绕过授权路由
具体 curl 和协议差异见 调用与端点。