AI API 网关的 BYOK 提供商密钥加入：在路由流量之前验证客户凭据

请勿将 BYOK 加入视为接受上游 API 键并立即启用路由的文本框。在生产 AI API 网关中，客户提供的凭据需要控制平面工作流程：收集提供程序绑定、隔离密钥、运行特定于提供程序的探测、构建功能矩阵，然后才将凭据附加到租户路由策略。

读取器问题是可操作的：客户粘贴看似有效的 OpenAI、Anthropic、Gemini 或 Azure OpenAI 凭据，但第一个实际请求失败，因为密钥属于错误的项目、缺乏模型访问权限、无法调用所选端点、配额较弱或未公开计费和对账所需的使用数据。网关应在客户流量依赖这些限制之前发现这些限制。

将 BYOK 凭据设计为有状态的控制平面对象

BYOK 凭据应与应用程序使用的网关颁发的密钥分开。应用程序应使用稳定的虚拟密钥调用网关，而网关则将该租户、产品计划、模型配置文件和策略映射到经过验证的上游凭证。当客户轮换上游密钥、更改提供商项目或失去特定模型功能时，这种分离可以保持应用程序集成稳定。

至少使用以下状态对上游凭据进行建模：

• 已提交：已由控制平面接收，但尚未可用。
• 隔离：存储在保管库中，并在探测运行时阻止实时流量。
• 已验证：允许通过验证的特定功能。
• 已降级：对于某些流量仍然可用，但一项或多项功能、配额信号或使用情况报告预期失败。
• 已暂停：在身份验证、权限、配额、结算或政策错误后暂时被阻止。
• 需要旋转： 网关仍已知，但必须在继续生产使用之前进行更换。
• 已撤销：已从路由中删除，并且不再接受作为备用方案。

此状态机对于构建多提供商 LLM API网关 的团队很重要，因为单个标准化“有效密钥”标志会隐藏特定于提供商的行为。网关需要了解哪些端点、模型、区域、模式和报告模式对于每个租户来说是安全的。

在请求机密之前收集提供商绑定字段

加入表单应要求在机密之前或旁边提供非机密路由上下文。该上下文可以防止不明确的探测并生成更好的错误消息。

OpenAI

收集预期的组织和项目、请求的模型配置文件以及密钥是用户密钥还是服务帐户密钥。有用的验证程序应该检查项目绑定和权限，因为 OpenAI 记录了组织和项目级别基于角色的访问控制，并且 API 权限由该模型管理。诸如模型列表之类的调用可能需要相关密钥和角色的模型读取权限。

对于服务帐户，请将范围视为限制，而不是独立的权限。 OpenAI 服务帐户密钥范围可以限制服务帐户可以执行的操作，但它们无法授予分配的项目角色之外的权限。实际上，密钥可能看起来范围狭窄，但仍然会失败，因为项目角色不允许所请求的模型或端点。

Anthropic

当客户拥有多个工作区或使用与身份相关的流程时，收集预期的工作区 ID。 Anthropic 工作区可以包含成员、服务帐户、API 密钥和资源限制，它们旨在在集中计费和管理下分隔项目、环境或团队。

验证程序应保留请求是否需要 anthropic-workspace-id 标头。 Anthropic 文档称身份关联或多工作空间 API 关键流程可能需要该标头。还要避免假设运行时工作区范围的密钥可以检查组织级别的资源限制。工作区范围的密钥对于某些组织级管理 API 操作（例如工作区速率限制检查）无效。

Gemini

收集密钥是来自 AI Studio 还是 Google Cloud 项目、预期的项目上下文、允许的 API 以及客户期望的任何限制。 Google 的 Gemini API 密钥文档称每个 Gemini API 密钥都与 Google Cloud 项目关联，并且新的 AI Studio 密钥将创建为身份验证密钥。它还表示，Gemini API 会拒绝不受限制的标准密钥，作为远离不安全的不受限制密钥的一部分。

入门用户界面应标记不安全的无限制标准密钥，而不是鼓励客户在调查通过之前放松限制。 Google Cloud API-key 指南建议 API 限制，避免查询参数中的键、删除不需要的键以及不将键提交到存储库。 Gemini 身份验证密钥是一种特殊的生产异常，因为Gemini API 不会创建Google Cloud 项目资源，但验证者仍应记录密钥类型和限制状态。

天蓝色OpenAI

收集端点、部署名称、API版本、区域和订阅上下文（如果客户可以提供）。 Azure OpenAI 通过客户创建的部署进行路由，因此通用模型名称是不够的。当请求的部署名称缺失、位于不同区域或绑定到网关不期望的模型版本时，密钥可能对资源有效。

Azure OpenAI 配额是按 TPM 单元中的订阅、区域、模型和部署类型分配的。分配的 TPM 映射到部署速率限制，同时 RPM 也被强制执行。运行时响应可以公开有用的速率限制标头，例如剩余请求、剩余令牌和毫秒后重试。在探测和运行时监控期间捕获这些信号。

分层运行验证

良好的预检套件一开始成本低廉且风险低，然后仅在客户同意的情况下才使用一次最少的计费探测。一些提供商没有通过运行时密钥进行足够的自省，因此成功的入门结果应包括置信度，而不仅仅是通过或失败。

1.静态检查

在调用提供商之前验证明显的格式问题、缺失字段、不兼容的端点形状、不受支持的区域以及格式错误的部署名称。静态检查不应该记录原始秘密。而是存储指纹、创建源、租户 ID、提供商和保管库引用。

示例：

• Azure 端点与预期的资源 URL 模式不匹配。
• 即使请求的模型配置文件映射到 Azure OpenAI.
，Azure 部署名称仍为空
• Anthropic 多工作空间加入路径缺少工作空间 ID。
• Gemini 键在需要限制时被标记为不受限制的标准键。
• 请求的配置文件包括映像生成，但提供商适配器不支持该 BYOK 凭据模式。

2.低风险读取探针

在提供商允许的情况下使用只读探测。模型列表调用、部署元数据检查或帐户功能端点可以揭示身份验证、项目绑定和权限失败，而无需生成模型输出。记录标准化结果和原始提供商状态代码。

建议的标准化结果包括：

• auth_failed：凭据无效、已撤销、已过期或已禁用。
• wrong_project_or_workspace：有效密钥，但未绑定到预期项目或工作区。
• permission_denied：已通过身份验证，但缺少端点、模型或管理员权限。
• model_unavailable：密钥有效，请求的模型或部署无效。
• quota_unknown：运行时可以运行，但无法检查配额。
• usage_reporting_unavailable：网关无法通过提供的凭据协调提供商端的使用。

3.最小推理探针

每个请求的模型配置文件通常至少需要一个真实推理探针，因为列出模型并不等同于允许运行该模型。征求客户的明确同意，设置较小的探测预算，并使用执行所需功能的最便宜的端点。

保持探测的确定性和无聊性。对于文本配置文件，请发送具有低输出上限的简短提示。对于流式传输，请验证提供程序是否按预期返回流事件和最终使用元数据。对于支持工具的配置文件，请使用综合工具定义并确认提供者是否接受工具架构。对于视觉，如果提供商和政策允许，请使用已知的微小测试图像。避免使用存储敏感客户数据或需要特定业务提示的探测。

4.阴性测试

负面测试证明政策边界是真实的。如果只允许租户使用定义的模型配置文件，则验证者应尝试明确禁止的模型、端点、工具或区域，并确认网关在提供者看到它之前将其阻止。这些是网关策略测试，而不是提供商滥用测试。

这对于经销商和 SaaS 设置尤其重要，其中 AI API 客户配置 自动创建下游密钥。客户提供的上游密钥不应仅仅因为具有更广泛的提供商权限而绕过租户的网关政策。

存储能力矩阵，而不是布尔值

入职的输出应该是附加到凭据版本的能力矩阵。该矩阵应可通过路由、支持、结算和面向客户的状态页面进行查询。

实用矩阵包括：

• 提供商、凭据版本、保管库参考、租户和环境。
• 观察到的组织、项目、工作区、端点、区域或部署绑定（如果可用）。
• 支持的端点：聊天、响应、消息、嵌入、批量、实时、图像、音频或特定于提供商的等效端点。
• 支持的模型和部署名称。
• 支持的请求功能：流式传输、工具、JSON 模式、结构化输出、视觉、音频、提示缓存、批处理作业。
• 观察到的速率限制标头和重试标头。
• 已知配额来源：管理 API、运行时标头、客户声明或未知。
• 使用情况报告模式：提供商报告可用、仅网关计量、部分协调或不受支持。
• 验证置信度：深度、浅度、仅运行时或客户声明。
• 上次成功的探测、上次失败的探测以及原始错误证据。

路由应使用此矩阵。如果矩阵表明密钥支持文本推理但不支持批处理作业，则网关应允许文本流量并拒绝批处理流量，并提供明确的面向客户的消息。如果无法检查配额但运行时探测有效，则可以以有限的置信度将凭据标记为已验证，而不是假装网关具有完整的容量可见性。

将验证结果映射到路由政策

网关不应直接从“租户选择的提供商”路由到“使用此机密”。从租户政策到模型配置文件、从模型配置文件到功能要求以及从要求到符合条件的凭据版本的路由。

例如：

tenant: acme-prod
virtual_key: mgk_live_...
model_profile: support-chat-standard
requirements:
  endpoint: chat
  provider_candidates: [openai, anthropic, azure_openai]
  features: [streaming, tools]
  max_region: customer_approved_regions
  usage_mode: gateway_metered_with_provider_reconciliation_preferred
eligible_credentials:
  - byok_openai_project_key_v3: verified, tools=true, streaming=true, usage_report=partial
  - byok_azure_openai_v2: degraded, deployment_found=true, quota_low=true
routing_decision:
  primary: byok_openai_project_key_v3
  fallback: none unless customer permits provider-managed spillover

此策略层还可以保护统一 AI API计费。如果网关只是简单地传递请求并稍后信任提供商发票，BYOK 可能会削弱集中计费。即使提供商端使用情况报告不可用，网关也应记录租户级使用情况、请求 ID、模型配置文件、标准化令牌计数（如果可用）、协调置信度以及任何不支持的报告模式。

使用面向客户的语言处理故障

原始提供商错误对于支持很有用，但大多数客户需要直接的补救指导。在内部存储原始错误代码和标头，然后将失败转换为稳定的消息。

验证程序结果	面向客户的消息	可能采取的操作
wrong_workspace	密钥有效，但未绑定到所选工作区。	选择正确的工作区或创建工作区范围的密钥。
missing_model_permission	密钥无法使用请求的模型。	授予模型访问权限或选择其他模型配置文件。
deployment_not_found	在此端点找不到 Azure OpenAI 部署名称。	检查端点、区域、部署名称和 API 版本。
quota_too_low	凭据有效，但观察到的配额低于所选生产配置文件。	增加配额或选择吞吐量较低的配置文件。
usage_reporting_unavailable	密钥可以运行推理，但无法通过此凭据协调提供程序使用情况报告。	使用仅网关计量或提供管理/报告访问权限。
unsafe_key_type	生产路由不接受密钥类型或限制状态。	创建适合生产的受限密钥。

入职后重新检查凭据

成功的预检只是一个快照，而不是保证。项目角色、工作区策略、配额、计费状态、模型可用性和区域容量在加入后可能会发生变化。网关应运行计划的运行状况检查和事件驱动的重新检查。

在以下时间后触发重新检查：

• 401 或提供商身份验证失败。
• 403 或权限被拒绝的响应。
• 404 模型、部署或端点未找到响应。
• 429、超出配额或超出正常流量模式的速率限制响应。
• 提供商结算、组织、工作区或项目错误。
• 客户对请求的模型配置文件、区域、工具或数据政策进行更改。

当一项功能中断时，不要立即暂停整个租户。如果流式传输失败但非流式推断仍然有效，请将流式传输功能标记为降级，并在策略允许的情况下路由符合条件的非流式工作负载。如果缺少单个 Azure 部署，请阻止该部署而不是所有客户的提供商凭据。

将轮换构建为并行验证工作流程

轮换不应该是盲目覆盖。创建新的凭证版本，将其存储在隔离区中，运行与原始登录相同的探测，并仅在验证通过后自动切换路由。仅当客户明确允许并且政策允许继续存储时，才将旧密钥保留在较短的回滚窗口中。

安全轮换工作流程如下所示：

1. 客户提交替换凭据和绑定字段。
2. 网关将密钥存储为隔离区中的新凭据版本。
3. 验证程序运行静态检查、读取探测、推理探测和策略测试。
4. 将功能矩阵与活动版本进行比较。
5. 客户会看到任何回归，例如缺少批次支持或配额置信度较低。
6. 网关在一次控制平面更新中将路由切换到新版本。
7. 旧版本会立即撤销或保留一段短暂、明确的回滚窗口。

比较步骤很重要。如果失去工具支持、使用情况报告、区域配额或对生产部署的访问权限，可以调用基本文本模型的替换密钥可能仍然是回归。

为了明确而做出的权衡

验证可能会产生少量提供商费用。建议征求同意、显示最大探测预算并使用最少的提示和输出上限。不要将计费探针隐藏在“验证”中。

管理员自省可提高信心，但会增加影响范围。一些客户会提供管理员或报告凭据以进行更深入的验证。其他人只会提供运行时密钥。两者都支持，但要清楚地标记结果的置信度。

提供程序语义不会完全规范化。单个状态枚举对于产品流很有用，但支持团队需要原始提供程序代码、标头、请求 ID 和适配器级证据。保留规范化记录和原始记录。

BYOK 更改计费责任。BYOK 为客户提供提供商合同控制权，但会降低网关核对提供商发票的能力。网关应公开计费是由提供商协调、由网关计量、部分计费还是由客户声明。

严格的入职流程会减慢一些以销售为主导的设置。有限的沙盒模式会有所帮助，但应对其进行明确标记、限制并阻止其自动生产促销。生产路由应需要经过验证的功能和策略映射。

实施清单

• 创建具有显式生命周期状态和不可变凭据版本的 BYOK 凭据对象。
• 在验证之前收集提供商特定的绑定字段。
• 仅将机密存储在凭证保险库中；记录指纹和保管库引用，而不是原始密钥。
• 在提供程序调用之前运行静态检查。
• 在允许的情况下运行读取探测并保留原始提供商证据。
• 在获得客户同意和探测预算的情况下，针对所请求的模型配置文件运行一次最小推理探测。
• 对不允许的模型、工具、端点和区域运行网关策略否定测试。
• 保留具有置信水平的能力矩阵，而不是布尔值。
• 通过租户政策和模型配置文件要求进行路由，而不是直接通过选定的密钥进行路由。
• 通过具体的补救步骤公开面向客户的失败消息。
• 安排运行状况检查并根据运行时错误触发重新检查。
• 将轮换实现为并行验证，然后进行原子路由切换。

结论

最安全的 BYOK 入门流程是验证程序，而不是表单。客户提供的提供商密钥应进入隔离区，证明其绑定、权限、模型访问、配额信号、端点行为和报告限制，然后仅具有其实际支持的功能的资格。

实际建议是将验证存储为功能矩阵，通过租户策略进行路由，并在生产流量开始后继续重新检查。预测很简单：随着提供商密钥类型、工作区控制、区域配额和特定于模型的权限变得更加精细，将 BYOK 视为一次性秘密上传的网关将看到更多可避免的生产故障。将凭据验证作为控制平面一部分的网关一开始会更慢地吸引客户，但流量开始后不会出现太多意外。

相关阅读

• 用于分离运行时、管理、计费和 BYOK 访问的凭据保险库模式