LLM API Virtual Keys
Expose Policy, Protect Provider Secrets
LLM API 虚拟密钥：向应用暴露策略，保护上游密钥
A virtual key is a gateway credential bound to identity and policy, not a copy of the upstream provider secret. Its value comes from scope, revocation and evidence.
虚拟密钥是绑定身份与策略的网关凭证，不是上游供应商上游密钥的副本。它的价值来自范围控制、可吊销性与证据。
TL;DR
Issue keys to a user, service or workload with tenant and environment boundaries.
Apply model allowlists, budgets, rate limits, region and data policy at the gateway.
Keep provider credentials in a vault and use them only inside the trusted gateway.
Support expiry, rotation and instant disable without changing provider credentials.
向 User、Service 或工作负载发放，并设置租户与 Environment 边界。
在网关执行模型 Allowlist、预算、限流、区域与数据策略。
把供应商凭证保存在密钥库中，只在可信网关内使用。
支持过期、轮换与即时停用，无需更改供应商凭证。
Virtual key versus provider key 虚拟密钥与供应商密钥
Applications present a virtual key to the gateway. The gateway authenticates it, resolves identity and policy, then selects an approved upstream route using a provider credential that never leaves the trusted boundary.
应用向网关提交虚拟密钥。网关验证后解析身份与策略，再使用从未离开可信边界的供应商凭证选择获批上游路由。
Do not encode sensitive policy in the key itself. Store a one-way identifier and versioned server-side policy so permissions can change and keys can be revoked without disclosure.
不要把敏感策略编码进密钥本身。保存单向标识与版本化服务端策略，使权限可变更、密钥可吊销且无需泄露。
Credential design choices 凭证设计选择
| Choice 选择 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Opaque random key 不透明随机密钥 | Server-to-server clients need simple bearer authentication. 服务到服务客户端需要简单 Bearer 认证。 | Use high entropy, one-time display, hashing and secure transport. 使用高熵、仅展示一次、哈希存储与安全传输。 |
| Short-lived token 短期 Token | Identity provider can mint workload-bound credentials. 身份提供方可签发绑定负载的凭证。 | Validate issuer, audience, expiry, nonce and signing-key rotation. 验证 Issuer、Audience、Expiry、Nonce 与签名密钥轮换。 |
| Service identity Service Identity | Cloud or mesh identity is available. Cloud 或 Mesh 身份可用。 | Map identity to policy explicitly and handle local development safely. 显式映射身份到策略，并安全处理本地开发。 |
| Provider key direct 直接供应商密钥 | Only for tightly controlled exceptional paths. 仅用于严控的例外路径。 | It exposes broad upstream scope and weakens central revocation and audit. 会暴露宽泛上游权限，并削弱集中吊销与审计。 |
Virtual key policy controls 虚拟密钥策略控制
Restrict use to approved projects, services, environments and owners.
Allow only required providers, models, tools, regions and data paths.
Set request, token, concurrency and spend guards with clear reset rules.
Track issue, use, policy decision, rotation, expiry, revocation and owner.
限制到获批 Project、Service、Environment 与 Owner。
只允许所需供应商、模型、工具、Region 与 Data Path。
设置请求、Token、并发与支出保护，并明确重置规则。
追踪签发、使用、策略决策、轮换、过期、吊销与 Owner。
Validate the control plane 验证控制平面
- Attempt cross-tenant, wrong-model, expired and revoked-key requests.
- Verify limits under bursts and ensure decisions are atomic across replicas.
- Rotate upstream credentials without changing application virtual keys.
- Trace every accepted and denied request to identity, policy version and route.
- 尝试跨租户、错误模型、过期与已吊销密钥请求。
- 在突发流量下验证限制，并确保副本间决策具备原子性。
- 在不更改应用虚拟密钥的情况下轮换上游凭证。
- 把每个接受或拒绝的请求关联到身份、策略版本与路由。
Terminate virtual keys at the gateway 在网关终止虚拟密钥
A user or service authenticates with a virtual key or identity token. The gateway resolves an internal principal, evaluates versioned policy and selects an allowed model route. Provider secrets are fetched from a protected vault and never returned to the application.
User 或 Service 使用虚拟密钥或身份 Token 认证。网关解析内部 Principal、评估版本化策略并选择获批模型路由。供应商上游密钥从受保护密钥库获取，永不返回应用。
Production rule: a virtual key must never contain or reveal an upstream provider credential.
生产规则：虚拟密钥绝不能包含或泄露上游供应商凭证。
Use separate scopes for models and external capabilities 为模型与外部能力使用独立范围
Model virtual keys govern inference access. QVeris governs external APIs, tools, services and live data through Discover → Inspect → Call. Bind both to the same identity where useful, but issue separate scopes, budgets and audit records.
模型虚拟密钥治理推理访问；QVeris 通过 Discover → Inspect → 调用治理外部 API、工具、服务与实时数据。两者可绑定同一身份，但应使用独立范围、预算与审计记录。
The Production Operating Model for LLM API virtual keysLLM API 虚拟密钥的生产运营模型
For LLM API Virtual Keys, reliability begins when reliable only when requirements, policy, failure behavior, evidence, and ownership are explicit. Turn the diagram into an operating contract that can be tested before launch and during every change.
针对“LLM API 虚拟密钥”，只有当需求、策略、失败行为、证据和责任都明确时，架构才会真正可靠。应把架构图转成运营契约，并在上线前和每次变更期间持续测试。
Inventory tenant, user, service, environment, model and provider allowlists, rate and spend limits, data policy, expiration, rotation, revocation, delegation, and emergency access. For each workflow, set quality, availability, p50 and tail latency, freshness, privacy, regional, cost, and recovery objectives instead of applying one global policy.
盘点租户、用户、服务、环境、模型与供应商白名单、速率与支出限制、数据策略、过期、轮换、撤销、委派和紧急访问。为每类工作流分别设置质量、可用性、常规与长尾延迟、新鲜度、隐私、区域、成本和恢复目标，而不是套用一个全局策略。
For LLM API Virtual Keys, first reject routes that fail capability, authorization, residency, safety, health, or budget constraints. Only then optimize among eligible candidates. Version the policy and record the reason for every decision and override.
针对“LLM API 虚拟密钥”，先排除不满足能力、授权、驻留、安全、健康或预算约束的路由，再在合格候选项中优化。版本化策略，并记录每次决策与覆盖的原因。
To validate LLM API Virtual Keys, inject rate limits, slow streams, malformed output, stale control data, credential loss, regional failure, quota exhaustion, schema drift, and dependent-tool outages. Verify bounded retries, semantic fallback, partial results, and safe recovery.
验证“LLM API 虚拟密钥”时，注入限流、慢速流、畸形输出、过期控制数据、凭证丢失、区域故障、配额耗尽、Schema 漂移和依赖工具中断，验证有界重试、语义故障切换、部分结果和安全恢复。
When operating LLM API Virtual Keys, trace request, policy version, candidate set, selected route, transformations, attempts, latency, usage, cost, validation, and final task result. Tie alerts to runbooks, assign owners, and use incidents to update tests and acceptance thresholds.
运营“LLM API 虚拟密钥”时，追踪请求、策略版本、候选集合、所选路由、转换、尝试、延迟、用量、成本、校验和最终任务结果，把告警连接到运行手册，明确负责人，并用事故更新测试与验收门槛。
FAQ
No. It is an internal credential resolved to gateway policy.
Yes, if policy explicitly allows a capability-equivalent provider pool.
Store only protected identifiers or hashes; keep plaintext out of logs and databases.
不是。它是解析到网关策略的内部凭证。
可以，前提是策略显式允许能力等价的供应商池。
只存储受保护标识或哈希，避免明文进入日志和数据库。