跳到主要内容

虚拟密钥

/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错误码响应头
小时请求数超限429rate_limit_exceededX-RateLimit-Limit-Requests
并发超限429concurrency_exceededX-Concurrency-Limit
日限额用满402budget_exceededX-Budget-Limit、X-Budget-Used
月限额用满402budget_exceededX-Budget-Limit、X-Budget-Used

小时请求数和并发都是进程内计数,进程重启清零,多实例各自计数、不共享。日/月额度落库,多实例共享同一份数据库时按库里的已用金额判断。

额度到达阈值或刚好用满时,会按 通知与告警 的配置推送提醒;提醒是软性的,不会因为告警失败而放行或拦截请求。

用量与重置​

  • 管理台虚拟密钥页可以查看当日/当月已用金额,并重置预算
  • 历史消耗从请求日志按密钥汇总,不在密钥行上保留累计额
  • 门户里使用者可以查看自己的用量,见 密钥门户

定价和汇率在 运行设置 与模型的计费字段里配。额度按折算后的美元累计。

授权路由与白名单​

  • 空授权 = 不限制:所有逻辑路由和 provider/model 直达都可用
  • 非空 = 只能调用白名单里的逻辑路由名;不能用 provider/model 绕过
  • allowed_routes 解析失败时,管理台会显示「配置异常」。此时不是「不限路由」,而是该密钥的全部逻辑路由都会被拒绝,需要修好配置

和路由的关系​

  • 请求 model: "glm" → 命中名为 glm 的路由 → 按权重选物理模型 → 再按密钥权重选一把 key
  • 请求 model: "openrouter/anthropic/claude-3.5-sonnet" → 没有同名路由时,直达该提供商下的物理模型
  • 受限虚拟密钥不能用第二种写法绕过授权路由

具体 curl 和协议差异见 调用与端点。