多模型 AI 网关的提供商凭证库：单独的运行时、管理、计费和 BYOK 访问

下游 API 密钥和上游提供商凭据解决不同的问题。您的网关颁发的开发人员密钥可识别应用程序、团队、租户、预算和策略上下文。上游提供商密钥允许网关花钱并访问提供商帐户中的模型。将这些视为同一类秘密，导致团队最终会在共享项目中获得一个不受限制的密钥，在运行时服务中获得管理员凭据，并且没有可靠的方法来回答哪个租户导致了哪个提供商方收费。

实用模式是提供商凭证库：用于导入、分类、存储、选择、轮换和审核上游凭证的专用控制平面。它应该位于路由器、计费账本、策略引擎和操作工作流程后面，而不是位于应用程序代码、模型配置文件、租户记录或分析事件内。

读者问题：上游凭证成为隐形基础设施

大多数多模型部署都是从一个简单的目标开始：将一个与 OpenAI 兼容的请求路由到最佳的可用提供商。然后会出现更多帐户：一个用于生产的提供商项目、另一个用于评估的提供商项目、一个用于业务部门的 Anthropic 工作区、一个用于 Gemini 的 Google Cloud 项目以及多个客户提供的用于 BYOK 合约的密钥。

风险不仅仅是秘密泄露。这是授权上下文的丢失。有效的提供商密钥在技术上可能能够调用端点，但网关仍然需要知道该密钥是否允许用于该租户、该模型系列、该数据保留策略、该预算、该区域和该自动化路径。

事实：提供商平台公开不同的帐户边界和凭证类型。 OpenAI 记录项目和服务帐户，服务帐户 API 密钥权限默认为项目 API 资源的读写访问权限。 OpenAI 还公开了与普通项目/运行时 API 使用分开的管理 API 密钥对象。 Anthropic 将工作空间记录为组织边界，并指出管理 API 端点需要与标准 API 密钥不同的管理 API 密钥； Anthropic 还指出，API 密钥与创建它们的工作区相关联，并且不能在工作区之间移动。 Google 的 Gemini API 密钥文档表示，每个 Gemini API 密钥都与 Google Cloud 项目相关联，并建议对 API 进行限制，以减少密钥泄露时造成的损失。

建议：不要构建一个通用的“provider_key”字段并称其完成。构建一个凭证清单，保留特定于提供商的边界，同时向网关公开规范化的策略模型。

在接受密钥之前定义凭证分类

保险库应拒绝不明确的凭据。在导入时，操作员或自动化工作流程必须对凭证进行分类。至少使用以下类别：

• 运行时推理凭据：由网关用来调用模型推理端点，例如聊天、响应、嵌入、审核、转录或图像生成，具体取决于提供商的支持。
• 管理自动化凭据：用于管理提供商方组织、工作区、项目、用户、密钥或管理资源。这些永远不应该出现在运行时请求路径上。
• 计费和报告凭据：用于检索提供商支持这些 API 的使用情况、发票、成本或组织报告。将它们与推理键分开，以便报告作业无法生成模型使用情况。
• 仅评估凭据：由基准测试、QA、迁移或暂存工作流程使用。它们应该具有较低的配额、明确的环境标签，并且没有生产后备资格。
• 客户 BYOK 凭据：客户提供的密钥绑定到特定租户、提供商帐户、合同和数据策略。除非客户明确选择加入，否则不应将它们汇集到共享路由中。

此分类不仅仅是文档。它应该驱动访问控制、路由资格、警报和轮换工作流程。如果导入的凭据没有类别、所有者、提供商帐户边界和允许使用，则该凭据应保持禁用状态。

将机密存储在保管库中，而不是产品记录中

保管库应该是唯一可以解密上游凭据的组件。其他系统可能会存储引用、哈希值、状态字段和策略元数据，但不会存储凭证值本身。

不要在这些地方存储上游机密

• 租户资料行。
• 模型路由配置文件。
• 提示日志或跟踪范围。
• 分析事件负载。
• 面向开发者的 CI 变量。
• 支持票证、聊天工具或屏幕截图。

可用的拱顶设计有两个平面。 秘密平面存储加密的凭证材料并严格控制解密操作。 元数据平面存储路由和治理使用的非秘密属性。路由器通常只需要一个凭证 ID 和调度时的短期内存中秘密检索，而不需要对每个提供者密钥进行广泛的数据库访问。

将保管库作为高价值基础设施进行保护：信封加密或托管 KMS、严格的服务身份、打破玻璃程序、备份和恢复测试、访问审查以及异常解密量警报。中央金库简化了治理，但也集中了风险。这就是权衡。

将策略元数据附加到每个凭证

元数据模型应该足够明确，以便网关可以在接触提供者端点之前决定凭证是否合格。

实用的凭证记录包括：

• credential_id：内部不可变标识符。
• 提供商：OpenAI、Anthropic、Gemini、Azure OpenAI 或其他适配器。
• provider_account_boundary：组织、项目、工作区、云项目、订阅或同等内容。
• credential_class：运行时、管理、计费、评估或 BYOK。
• 环境：生产、暂存、开发、评估、沙盒。
• tenant_binding：共享平台凭据、单一租户、租户组或客户 BYOK 租户。
• allowed_model_families：例如，文本生成、嵌入、视觉、图像、音频或特定模型配置文件。
• allowed_endpoints：映射到提供商端点的标准化网关功能。
• data_policy：允许的保留类别、日志记录类别、驻留要求和功能限制。
• budget_scope：成本中心、经销商客户、内部部门或合同。
• 所有者：指定团队或负责人。
• 创建时间、过期时间、旋转_到期时间、最后使用时间。
• health_status：未知、健康、降级、未经授权、quota_exhausted、已禁用。
• emergency_disable：独立于正常策略状态的立即路由阻止。

保持此模型与提供商中立，但不要抹去提供商的现实。 Anthropic 工作区绑定密钥和与 Google Cloud 项目绑定的 Gemini 密钥不能互换，因为两者都可以生成文本。网关需要该来源来进行审核、退款和安全故障转移。

独立的运行时、管理和计费访问权限

最重要的规则很简单：用于运行时推理的密钥不应管理提供者组织、工作区、用户、项目或管理资源。

运行时流量很大，并且暴露于最大的操作表面。它通过请求路由器、重试逻辑、流处理程序、模型适配器和事件工作流程。管理员凭据频率低且影响大。它们应该存在于一个单独的批准路径后面，该路径具有较短的 TTL，在适当的情况下称为人工批准，具有强大的日志记录，并且没有运行时路由资格。

计费凭证也应该分开。核对发票的报告作业不应该能够生成完成结果，并且运行时推断密钥不应该是检索使用情况报告的唯一方法。当提供商不提供细粒度的分离时，请在网关中进行补偿：隔离凭证，限制哪些内部服务身份可以检索它，并记录每次使用。

建议：使凭证类成为硬授权边界，而不是标签。即使配置错误引用了管理凭据的 ID，运行时调度程序也应该无法请求解密。

构建凭证选择策略引擎

凭证选择应该在网关对下游调用者进行身份验证之后、尝试任何提供者调用之前进行。策略引擎应连接多个输入：

• 租户 ID 和下游 API 密钥范围。
• 请求的型号配置文件或提供商特定的型号 ID。
• 端点功能：聊天、嵌入、图像、音频、批处理、文件、工具或管理自动化。
• 数据保留和居住要求。
• 预算、信用预留和成本中心。
• 速率限制状态和配额压力。
• 凭据元数据、运行状况、环境和租户绑定。

引擎应返回三个结果之一：使用选定的凭据允许、使用策略原因拒绝或需要批准。否认应该足够精确，以便运营团队能够解决问题，而无需向开发人员透露秘密材料。

决策示例：

<前><代码>{ “tenant_id”：“tenant_42”， "requested_profile": "快速文本产品", “端点”：“聊天完成”， "data_policy": "no_prompt_logging", “凭据要求”：{ “类”：“运行时”， “环境”：“生产”， “租户绑定”：“租户_42”， "allowed_model_family": "文本", “health_status”：“健康” }, “决定”：“允许”， "credential_id": "cred_8f2...", "audit_reason": "租户 BYOK 凭证与运行时文本配置文件和数据策略匹配" }

不要将后备实现为“尝试下一个键”。回退必须重新运行策略。共享平台凭证可能对提供商访问有效，但对仅 BYOK 客户无效。另一个项目中的凭证可能有配额，但可能违反成本归属或保留要求。

将 BYOK 视为租户拥有的访问权限，而不是备用容量

BYOK 改变了信任模型。客户提供凭证，以便他们的流量可以在其提供商帐户中进行收费、管理或隔离。该凭证应与客户租户和提供商帐户来源绑定。

推荐的 BYOK 控件：

• 每个客户、提供商、帐户边界和环境一个保管库记录。
• 无法通过 BYOK 凭据进行跨租户路由。
• 除非客户明确选择加入，否则不得用作共享后备容量。
• 客户可见的健康状态，但不会泄露原始密钥。
• 独立的轮换工作流程，允许客户在旧钥匙被停用之前添加替换钥匙。
• 使用情况分析和发票中的清晰归属：网关租户、提供商帐户边界、凭据 ID、模型配置文件和请求跟踪 ID。

对于代理机构、经销商和合作伙伴 API 自动化，BYOK 可能更加复杂，因为服务可能会以编程方式提供租户和凭据。同样的规则仍然适用：自动化可以导入和绑定凭据，但它不应该模糊租户所有权。

添加飞行前健康检查而不泄露提示

凭证可能因多种原因而失败：撤销密钥、错误的工作区、缺少模型访问权限、禁用计费、配额耗尽、端点限制、区域策略不匹配或提供商中断。发现只有在生产请求到达后才会产生噪音事件。

使用运行状况检查来验证功能，而无需发送客户提示。综合检查可能会调用最小端点，在适当的情况下列出允许的模型，或者发送无害的固定提示（如果这是唯一实用的选项）。保持这些检查便宜、速率受限，并在遥测和计费中标记为合成流量。

应该运行健康检查：

• 在凭证导入时。
• 在启用生产路由凭据之前。
• 提供商方限制发生变化后。
• 在轮换切换期间。
• 定期获取具有生产资格的证书。

权衡：自动检查可以尽早捕获过期或范围不足的密钥，但设计不当的检查可能会在提供商中断期间造成不必要的提供商呼叫、计费噪音或误报。存储带有时间戳、提供程序错误类、测试的端点和测试的模型系列的运行状况结果。不要存储秘密值或敏感提示。

轮换两个插槽，而不是一个有风险的替换

凭据轮换不应是删除并请求操作。使用两槽旋转模型：

1. 将替换凭据导入为非活动状态，并具有完整的元数据和所有者。
2. 针对预期端点、模型系列和帐户边界运行综合运行状况检查。
3. 在适当的情况下为一小部分安全合成或低风险流量启用影子资格。
4. 逐渐将生产流量从旧凭据转移到新凭据。
5. 通过凭据 ID 监控错误、延迟、配额和成本归因。
6. 一旦新凭据稳定，就冻结回退到旧凭据。
7. 撤销提供商处的旧凭据并将保管库记录标记为已撤销。
8. 验证撤销后旧凭证没有发生解密或提供商调用。

轮换截止日期应在操作视图和警报中可见。紧急轮换需要更短的路径：禁用凭据、阻止路由、启用经批准的替换，并保留所有审核记录以供事件审查。

在提供商支持的情况下限制提供商密钥

网关策略是必要的，但如果密钥被泄露或滥用，提供商端的限制会减少传播半径。对于 Gemini 和其他云平台 API 密钥，请使用 API/服务限制和合适的应用程序限制（如果可用）。对于提供程序项目、工作区和服务帐户，当项目范围的运行时密钥就足够时，请避免广泛的组织权限。

建议：为每个凭证类别维护提供商端限制清单。检查表应该是进口审批和轮换审批的一部分，而不是在压力下可能被跳过的单独安全任务。

权衡：提供商方限制增加了运营开销。新的端点、模型系列、区域或自动化功能可能需要更改策略和限制。这比在泄漏后发现一个密钥可以访问共享项目中的每个工作负载更好。

保留仅附加凭证审核日志

审计跟踪应该回答谁导入了凭证、允许它做什么、哪个路由决策选择了它、它何时失败以及何时轮换或撤销。

记录这些事件：

• 已创建或导入凭据。
• 元数据已更改，包括允许的端点、租户绑定或数据政策。
• 执行健康检查并记录结果。
• 由路由策略为请求选择的凭据。
• 内部服务身份请求的凭据解密。
• 由于身份验证、授权、配额或限制错误，提供商调用失败。
• 轮换开始，流量转移，旧凭证被吊销。
• 已启用或清除紧急禁用。
• 已访问管理员或碎玻璃凭据。

不要将原始凭据值放入审核事件中。使用凭证 ID、提供商帐户边界、请求跟踪 ID、参与者身份和策略决策原因。对于大容量运行时流量，您可以对详细的解密遥测数据进行采样，但路由选择和成本归因应保持足够完整，以便进行计费和事件响应。

实施清单

• 创建凭证分类并拒绝未分类的导入。
• 将所有提供商机密移至专用的加密保管库中。
• 将路由元数据与秘密材料分开存储。
• 将运行时、管理、结算、评估和 BYOK 凭据设为独立的授权类。
• 将 BYOK 凭据与租户和提供商帐户来源绑定。
• 在选择任何上游凭据之前需要策略引擎批准。
• 在达到生产资格之前进行及时安全的健康检查。
• 使用两个时隙轮换，逐步进行流量转移和提供商端撤销。
• 尽可能应用提供商方限制。
• 维护导入、使用、失败、轮换和撤销的仅附加审核日志。
• 将管理员凭据保留在打破玻璃控制之下：短 TTL、命名批准、强大的日志记录、无运行时使用。

可行的结论

首先清点网关、脚本、CI 作业、评估工具和合作伙伴自动化当前使用的每个上游提供商凭据。对于每一个，分配一个类、所有者、提供商帐户边界、租户绑定、允许的端点、允许的模型系列、轮换截止日期和紧急禁用状态。任何无法分类的内容都应该被禁用或隔离，直到它有明确的用途为止。

然后强制执行一项架构规则：下游开发人员接收网关范围的密钥；网关单独控制上游提供商的访问。即使提供商、项目、工作区和 BYOK 客户成倍增加，这种分离也能让您保留最低权限、租户归属、计费准确性、数据策略路由和安全自动化。

相关阅读

• 面向团队的 API 密钥管理和泄漏响应
• 数据保留感知路由策略
• 计费账本和成本归因控制