AI API 网关的控制平面协调

AI API 网关可以使运行时访问看起来统一，而上游提供商控制平面却不断变化。团队通常在网关上集中推理调用、计费、API 密钥管理和使用情况分析，然后将 OpenAI 项目、Anthropic 工作区、Google Cloud 项目、Gemini 密钥、服务帐户、预算和报告范围留给手动配置。这创建了一种安静的故障模式：网关表示存在一个租户策略，但提供商帐户强制执行或报告其他内容。

实际模式是控制平面协调。将上游提供商管理对象视为库存。将观察到的库存与网关中所需的租户策略进行比较。生成偏差结果，通过批准进行补救，并为明显的高风险状态保留自动操作。

本文将事实、建议和预测分开。事实是当今记录的提供者行为。建议是网关运营商的架构选择。随着多提供商 AI 堆栈的成熟，预测可能会带来运营压力。

采用网关后的漂移情况

运行时网关解决了一层问题：应用程序将请求发送到公共端点，租户获取范围内的网关密钥，并将使用情况记录在一个分类帐中。但上游提供商对象仍然很重要。他们决定哪个项目或工作区拥有密钥、哪些报告包含支出、适用哪些费率和资源限制以及可用的紧急控制措施。

常见的偏差示例包括：

• 租户映射到网关中的 OpenAI 项目，但运行时密钥仍然属于共享默认项目。
• Anthropic API 密钥在错误的工作区中创建，无法移动到预期的工作区。
• Google API 密钥是在外部创建的控制台流并保持不受限制，因为从未明确设置限制。
• 提供商支出阈值低于网关租户预算，导致提供商端在网关预期之前出现故障。
• 提供商支出阈值高于网关策略，使提供商帐户成为较弱的后盾。
• 使用情况报告包含空或继承的工作区字段，因此财务部门无法清楚地协调提供商成本与网关租户。
• 服务帐户在员工之后继续存在关闭，因为它不附加到网关所有权模型。

风险不仅仅是安全性。漂移破坏了归因、应急响应、成本控制和可审计性。

设计中要保留的事实

提供商控制平面不可互换。协调器应该标准化足够的数据，以便操作员高效工作，但它应该保留特定于提供商的语义。

OpenAI 项目

事实：OpenAI 项目让组织可以组织工作、管理访问和限制、配置服务帐户以及跟踪项目范围内的使用情况。使用情况可以按项目进行细分，并且可以为每个项目设置支出限制。

事实：OpenAI 项目服务帐户对于创建它们的项目来说是唯一的。他们生成的密钥只会显示一次，丢失密钥需要生成新密钥。

事实：OpenAI API 密钥支持“全部”、“受限”和“只读”等权限级别。服务帐户 API 密钥权限默认为对所有项目 API 资源的读写访问权限。

事实：OpenAI 文档在一篇帮助文章中将项目每月支出限制描述为软阈值，而故障排除材料还记录了硬限制错误，例如 project_spend_limit_exceeded。网关不应假设每个配置的提供商支出限制在每个帐户配置中都表现为同步硬上限。

Anthropic Workspaces

事实：Anthropic Workspaces 组织 API 密钥、团队访问权限和成本。其他工作区可以包含成员、服务帐户、API 密钥和资源限制。

事实：API 密钥与创建它们的工作区相关联，并且无法在工作区之间移动。 Anthropic 会根据每个请求评估适用的工作空间和组织限制因素。

事实：默认工作空间具有特殊的报告行为。使用情况和成本报告可能会显示空的workspace_id，这在网关尝试将提供商报告映射回租户时很重要。

事实：Anthropic Admin 和 Analytics API 涵盖组织和工作区管理、API 密钥、使用情况报告、成本报告和相关分析，但访问权限取决于管理员密钥以及帐户或角色资格。

Google Cloud 和 Gemini 密钥

事实：Google Cloud API 密钥指南指出不受限制的 API 密钥是没有安全感。 API 限制限制了可以调用哪些 API，应用程序限制则限制了可以使用密钥的位置。Google 建议在适用的情况下同时设置这两项。

事实：Google Cloud 文档称，通过控制台创建的 API 密钥需要至少一项 API 限制，而通过 gcloud 或 REST 创建的密钥则不受限制，除非明确指定限制。

事实：Google AI for Developers 文档称，Gemini API 正在从标准密钥转向授权密钥，不受限制的标准密钥将被拒绝，并且标准密钥必须在 2026 年 9 月之前迁移到授权密钥，以避免服务中断。

事实：带有提醒的 Google Cloud Billing 预算不会自动限制支出。编程式 Pub/Sub 通知可以自动执行成本控制响应，但 Pub/Sub 交付至少一次，并且消息可能会无序到达。

参考架构

建议：将协调构建为运行时网关旁边的控制平面服务，而不是在热请求路径内。它应该读取提供商管理界面，将其与网关租户策略进行比较，并发出漂移事件。

实用的架构有五个部分：

• 期望状态存储：网关租户策略：租户、所有者、允许的提供商、模型配置文件、预算策略、费率策略、允许的上游项目或工作区、密钥所有权和紧急状态。
• 观察状态库存：通过管理 API 发现的提供商对象，计费导出、控制台导出或计划扫描。
• 提供商适配器：OpenAI、Anthropic、Google Cloud 以及其他保留本机标识符和语义的特定于提供商的收集器。
• 漂移引擎：产生结果的确定性比较，而不是默默地更改提供商状态。
• 补救工作流程：票证、审批、聊天警报和小范围针对高风险漂移的自动化操作。

网关仍然是租户计费真相的来源。提供商成本和使用报告成为结算输入和异常信号。这种区别很重要，因为提供商报告可能会滞后、使用不同的维度，或者公开无法完全映射到网关租户的报告字段。

标准化库存，而不是失去意义

建议：使用标准化库存表，但包括提供商本机字段。不要假装 OpenAI 项目、Anthropic 工作区和 Google Cloud 项目是同一个对象。

有用的清单模型包括：

• 提供商： openai、anthropic、google、azure 或其他适配器名称。
• provider_account_id： 组织、结算帐户或云帐户标识符。
• container_type：项目、工作区、云项目、文件夹或帐户。
• container_id：提供商本机项目或工作区标识符。
• container_name：来自提供商的人类可读标签。
• tenant_id：映射的网关租户，或在以下情况下为 null未映射。
• service_account_id：提供商服务帐户或工作负载身份（如果可用）。
• api_key_id：密钥指纹、密钥 ID 或散列密钥标识符。请勿在此表中存储原始提供程序机密。
• key_scope：项目、工作区、组织、应用程序限制、API 限制或等效的提供程序特定范围。
• 权限：本机权限级别、角色绑定、受限功能列表或读/写状态。
• model_allowlist：密钥可以访问的模型或 API 系列，提供程序公开该模型或 API 系列控制。
• rate_policy：观察到的提供商限制及其预期支持的网关策略。
• spend_policy：观察到的提供商阈值或预算以及网关租户预算策略。
• reporting_scope：提供商报告中预期的维度，包括已知的 null 或继承字段。
• last_seen_at：来自最近的时间戳扫描。
• 所有者：网关租户、团队、服务所有者或人员所有者。
• 来源：管理 API、计费导出、控制台导出、配置导入或手动证明。

此表应易于追加。操作员需要历史记录：密钥何时首次出现、何时停止出现、其权限何时更改以及哪个扫描程序观察到更改。

显式定义所需状态

建议：仅当所需状态具体时，协调才有效。像租户 A 可能使用 Anthropic 这样的策略过于模糊。诸如租户 A 之类的策略必须使用工作区 ws_123、服务帐户 svc_billing_prod、无人工拥有的运行时密钥、模型配置文件快速支持以及网关预算的 80% 到 110% 之间的提供商支出阈值是可行的。

所需状态应包括：

• 每个租户可以使用哪些上游容器。
• 租户是否使用网关拥有的凭据、租户 BYOK 凭据、或两者兼而有之。
• 运行时密钥是否必须由服务帐户拥有。
• 允许使用哪些提供商 API 和模型。
• 可接受的上游支出阈值。
• 预期的提供商报告结算维度。
• Google 密钥所需的应用程序和 API 限制。
• 每个提供商和租户的紧急禁用行为。

将所需状态存储在版本化版本中政策表。每个偏差发现都应参考用于比较的策略版本。当策略更改产生许多新发现时，这使得审查和回滚成为可能。

实现运营商可以采取行动的漂移类

建议：发出类型化的漂移结果。避免通用不匹配警报。操作员应该知道发生了什么问题、为什么重要以及允许执行哪些操作。

有用的漂移类包括：

• missing_container：租户策略期望提供程序项目或工作区不存在或扫描仪不可见。
• unmapped_container：提供程序项目、工作区或云项目存在但没有租户映射。
• wrong_container：租户流量使用的密钥属于策略允许的不同项目或工作区。
• stale_key：提供商密钥在定义的时间段内未在网关流量中出现，但在上游仍处于活动状态。
• orphaned_owner：密钥或服务帐户由离线用户拥有或未映射身份。
• excessive_permission：密钥拥有比网关策略要求更广泛的提供商权限。
• unrestricted_google_key：Google 密钥缺乏所需的 API 限制、应用程序限制或与 Gemini 兼容的授权迁移状态。
• limit_below_policy：提供商限制可能会在网关策略之前阻止流量
• limit_above_policy：提供商限制过于宽松，无法作为后盾。
• reporting_unreconcilable：提供商使用情况或成本报告无法清晰地映射到租户、密钥、项目或工作区。
• scanner_blind：缺少所需的管理 API 或角色，因此协调器无法生成声明。

每个发现应包括严重性、置信度、受影响的租户、提供商本地标识符、首次观察时间、最后观察时间、建议操作、允许的自动操作和回滚元数据。

补救措施：开始干燥，小范围自动化

建议：默认在突变前进行试运行发现。提供商管理凭据非常强大。错误的映射可能会禁用生产工作负载、删除归因或造成代价高昂的中断。

两阶段模型效果很好：

• 通知和票证：适用于低风险或不明确的偏差，例如缺少所有者标签、未映射的报告字段或支出阈值稍微超出政策。
• 预先批准的自动操作：适用于狭窄的高风险情况，例如密钥泄露、离线用户拥有的密钥、不受限制的 Gemini 功能密钥或与已在网关中禁用的租户绑定的密钥。

如果可能，自动化应该是可逆的。例如，禁用网关密钥比删除上游密钥更容易逆转。暴露后可能需要轮换上游提供者密钥，但这需要下游部署协调。将网关预算降低到零是立即且可审核的，而提供商预算警报可能会滞后或异步运行。

紧急关闭运行手册

建议：在需要之前编写紧急提供商关闭运行手册。它应涵盖网关控件和提供商控件。

实际的顺序是：

1. 将受影响的网关密钥标记为禁用，以便新的运行时请求在网关处停止。
2. 将租户网关预算或支出预留限制设置为零。
3. 阻止租户路由到受影响的提供商或模型配置文件。
4. 在支持的情况下撤销、禁用或轮换上游提供商密钥。
5. 降低提供商端阈值（如果可用）并且对于帐户配置很有用。
6. 记录每个操作，包括参与者、时间戳、原因、提供程序对象和回滚指令。
7. 在报告传播延迟后协调提供程序端的使用情况和成本。
8. 进行事件后偏差审查：对象是如何变得不受管理的，以及哪个策略检查应该更早地捕获它？

此序列有意首先阻止网关处的流量。提供程序控制仍然很重要，但它们在速度、可用性和强制语义方面可能会有所不同。

权衡

自动协调可减少偏差，但需要管理员凭据。建议：将管理凭据与运行时凭据隔离，将它们存储在单独的保管库路径中，限制突变权限，并审核每次读写。

每个租户一个上游项目或工作区可改善归因和爆炸半径控制。权衡是对象蔓延、提供程序限制、操作开销以及共享缓存、预配置容量或池吞吐量策略的复杂性。

提供程序限制提供了有用的支持，但它们不能替代网关端预算预留。提供程序限制可能是软性的、异步的、依赖于计划的，或者根据请求和报告进行不同的评估。

频繁扫描可以更快地检测偏差，但它们会增加管理 API 的使用、配额压力和警报量。更好的模式是事件驱动的更新（如果可用），以及为了完整性而安排的协调。

标准化使仪表板可用，但过度标准化隐藏了重要的差异。让原生提供商字段在调查结果和报告中保持可见。

预测

预测：AI API 网关运营商将越来越多地将提供商管理对象视为受监管的配置，类似于云 IAM 和计费帐户配置。一旦在许多租户中进行支出和访问规模，仅运行时代理将无法满足财务、安全或平台团队的要求。

预测：关键模型将不断变化。 Gemini 从标准密钥转向授权密钥就是一个明显的例子。存储提供者本机对象类型、迁移状态和上次看到的源的协调系统将比仅存储原始机密和提供者名称的系统更好地处理这些更改。

预测：提供者报告对于结算仍然有用，但对于实时执行来说并不均衡。保留自己的请求分类账、预订模型和租户归属的网关比等待提供商计费导出的网关更具可预测性。

实施清单

• 为租户到提供商的映射创建所需状态策略表。
• 使用提供商本机标识符和哈希密钥 ID 创建观察清单表。
• 构建只读提供商适配器首先。
• 将扫描仪故障分类为发现结果，而不是隐藏它们。
• 严肃而自信地发出键入的偏差事件。
• 将发现结果路由到票证、警报或审批队列。
• 仅针对范围较小的预先批准的高风险类别启用自动操作。
• 将管理员凭据与运行时凭据分开。
• 将网关分类账记录加入提供商报告中以进行结算和异常情况检测。
• 在依赖非生产租户之前测试紧急关闭。

可操作的结论

不要停留在通过公共端点路由推理调用上。如果上游控制平面发生偏差，网关仍然可能会丢失归因、错过过时的密钥、误读提供商的支出行为或在紧急情况下发生故障。

最强大的模式很简单：在网关中写入所需的租户策略，扫描观察到的提供商对象，保留提供商特定的含义，发出类型化的偏差结果，并通过受控工作流程进行修复。开始只读。证明库存。然后仅自动执行风险低于其修复的偏差的操作。

相关阅读

• 单独的运行时、管理、计费和 BYOK 凭据
• 网关端计费账本和预算预留
• 关闭和服务帐户所有权规则