LLM API 虚拟密钥
虚拟密钥是绑定身份与策略的网关凭证，不是上游供应商上游密钥的副本。它的价值来自范围控制、可吊销性与证据。
速览快速结论
向 User、Service 或工作负载发放，并设置租户与 Environment 边界。
在网关执行模型 Allowlist、预算、限流、区域与数据策略。
把供应商凭证保存在密钥库中，只在可信网关内使用。
支持过期、轮换与即时停用，无需更改供应商凭证。
虚拟密钥与供应商密钥
应用向网关提交虚拟密钥。网关完成认证后解析身份与策略，再使用始终留在可信边界内的供应商凭证选择获批上游路由。
供应商密钥通常按照签发它的供应商账户或项目授予权限；虚拟密钥则是内部授权对象，可以代表某项服务、租户、环境、团队或临时工作负载，即使多个虚拟密钥最终共用同一个上游账户也不例外。正是这层额外身份，才让应用级预算、模型白名单与审计归属成为可能。
不要把敏感策略直接编码进密钥。应保存单向标识和版本化服务端策略，使权限能够调整、密钥能够吊销且无需披露内部规则。外部 Token 需要具备足够熵值以抵抗猜测，而所有者、权限范围、到期时间和预算应保存在服务端。
当虚拟密钥的生命周期比上游凭证更短、用途更明确时，它的价值最大。生产、预发布、CI 任务和本地开发应分别签发密钥，指定可追责的所有者，并在可行时设置到期时间；不要把个人用户密钥复制到长期运行的服务中。如果两项工作负载需要不同的数据区域或模型族，也不应为了方便而共用同一个虚拟密钥。
凭证设计选择
| 选择 | 最适合 | 选择前验证 |
|---|---|---|
| 不透明随机密钥 | 服务到服务客户端需要简单 Bearer 认证。 | 使用高熵、仅展示一次、哈希存储与安全传输。 |
| 短期 Token | 身份提供方可签发绑定负载的凭证。 | 验证 Issuer、Audience、Expiry、Nonce 与签名密钥轮换。 |
| Service Identity | Cloud 或 Mesh 身份可用。 | 显式映射身份到策略，并安全处理本地开发。 |
| 直接供应商密钥 | 仅用于严控的例外路径。 | 会暴露宽泛上游权限，并削弱集中吊销与审计。 |
虚拟密钥策略控制
限制到获批 Project、Service、Environment 与 Owner。
只允许所需供应商、模型、工具、Region 与 Data Path。
设置请求、Token、并发与支出保护，并明确重置规则。
追踪签发、使用、策略决策、轮换、过期、吊销与 Owner。
验证控制平面
控制面测试既要覆盖授权正确性，也要覆盖策略传播。在一个区域创建密钥、在另一区域修改策略，并在活跃流量中吊销密钥时，系统都应在承诺的时间范围内产生确定结果。测试需要跨多个副本执行，避免某个陈旧缓存继续接受已被其他副本吊销的密钥。
- 尝试跨租户、未授权模型、过期密钥与已吊销密钥请求。
- 在突发流量下验证额度，并确保多副本之间的决策具备原子性。
- 在不更改应用虚拟密钥的情况下轮换上游凭证。
- 把每个接受或拒绝的请求关联到身份、策略版本和路由。
预算测试不能只做顺序调用，还必须覆盖并发场景。当多个请求可能同时竞争同一额度时，应在分发前预留预算，完成后再按实际 Token 用量结算；同时明确预算耗尽时请求是被拒绝、排队，还是路由到更便宜的模型。还要验证重试不会让同一次逻辑调用被重复扣减虚拟密钥预算。
在网关终止虚拟密钥
用户或服务使用虚拟密钥或身份 Token 完成认证。网关解析内部主体、评估版本化策略并选择允许的模型路由。供应商密钥从受保护的密钥库中获取，永不返回应用。
在可行时只存储虚拟密钥的哈希或带密钥摘要，并仅在创建时展示一次明文。系统应在缓冲大体积请求或启动高成本工作前完成认证。认证后，把解析出的主体与策略版本附加到请求上下文中，使后续路由、日志和计费决策始终使用同一身份。
还要考虑控制面局部故障。运行时网关可以在短暂且有边界的时间内缓存已签名策略快照，但吊销操作和高风险策略变更需要快速失效通道。不同工作负载应分别定义故障时放行还是拒绝：低风险内部摘要任务可以短暂使用缓存策略，而受监管数据访问通常应在无法确认策略新鲜度时停止。
生产规则：虚拟密钥绝不能包含或泄露上游供应商凭证。
为模型与外部能力使用独立权限范围
模型虚拟密钥治理推理访问；QVeris 通过“发现 → 检查 → 调用”治理外部 API、工具、服务和实时数据。两者可以绑定同一身份，但应签发独立的权限范围、预算和审计记录。
例如，客服助手可以使用多个文本模型，但只能读取工单元数据和公开文档；金融 Agent 即使使用相同模型，也可能需要带不同授权的市场数据、监管申报文件和投资组合工具。仅靠模型访问权限无法表达这些差异，因此外部能力策略应明确允许的工具、数据分类、参数限制和必要的人工审批。
应在工作流层关联记录，而不是把两类权限强行塞进同一个凭证。一条共享调用链可以同时说明：虚拟密钥授权了模型推理，另一个独立授权的 QVeris 能力生成了实时结果。这样运营人员仍有统一的调查路径，同时保留独立吊销、成本归属和最小权限控制。
常见问题
不是。它是解析到网关策略的内部凭证。
可以，前提是策略显式允许能力等价的供应商池。
只存储受保护标识或哈希，避免明文进入日志和数据库。