如何在不暴露原始提供商密钥的情况下构建合作伙伴 LLM API

用于 LLM 访问的

合作伙伴 API 不应是提供商密钥的薄包装。如果合作伙伴、经销商或客户应用程序需要对语言模型进行委派访问，则平台需要自己的控制平面、网关、策略层、计量管道和操作运行手册。否则，提供商级计费、提供商级限制和共享凭据将成为一个合作伙伴集成与代价高昂的事件之间的唯一控制措施。

目标很简单：让外部各方通过您的平台使用 LLM 功能，同时您将上游提供商凭据保密、实施特定于合作伙伴的权利、衡量计费使用情况，并为合作伙伴提供足够的透明度以建立可靠的客户。

参考架构

实用的合作伙伴API有两个主要部分：控制平面和请求网关。

控制平面管理合作伙伴组织、应用程序、环境、委托的API密钥、模型权利、速率限制层、支出上限、结算条款、网络钩子端点和审核记录。在这里，商业和运营规则成为机器可读的政策。

请求网关接收合作伙伴流量、验证委托密钥、评估政策、应用配额、路由到所选模型提供商、记录使用情况并返回合作伙伴可见的响应元数据。在成熟的企业 LLM API 中，此网关也是一致执行模型路由、重试、故障转移、内容控制和可观察性的地方。

重要的界限是：合作伙伴仅收到您的平台颁发的密钥。他们永远不会收到原始的提供商凭据。上游提供商密钥保留在您的平台秘密存储中，仅由网关或后端工作人员使用。

围绕事实模式构建

以下是公共平台和云文档支持的事实，而不是对任何一种部署的假设：

• 一些 LLM 提供商支持项目范围的密钥、服务帐户、项目级模型访问权限和项目级速率限制。
• 多租户 SaaS API 的云指南通常将策略管理、策略决策和策略执行分开，以减少意外的跨租户访问。
• API网关和 SaaS 控制平面可以应用特定于租户的限制和配额控制，包括速率、突发和配额层。
• 基于使用情况的 SaaS 计费取决于收集租户活动、聚合活动并将其与计费记录进行核对。
• 幂等密钥是一种记录在案的模式，用于安全地重试状态更改的 API 请求，而不会产生重复的副作用。
• 标准化速率限制响应标头可以帮助客户端了解限制、剩余限额、重置时间和重试行为。

建议将这些模式合并到您拥有的面向合作伙伴的 LLM 访问层中，而不是要求每个合作伙伴直接与每个上游模型提供商集成。

第 1 步：定义租户和身份模型

请勿仅使用一个 API 键字符串来识别合作伙伴流量。有用的合作伙伴 API 需要单独的标识符，因为计费、滥用审核、配额调试和支持调查通常会提出不同的问题。

至少为以下对象创建标识符：

• 合作伙伴组织：签约的外部公司。
• 合作伙伴应用程序：特定集成、产品、插件或经销商应用程序。
• 环境：生产、暂存、沙盒或开发。
• 最终客户：合作伙伴的客户、工作区、帐户或租户（如果合同允许并且技术上可用）。
• API key:用于验证请求的委托凭据。
• 请求 ID：用于跟踪网关上的一个请求、提供商调用、使用事件和支持日志的唯一标识符。

这种结构避免了常见的故障模式，即一种受损或有噪音的集成只能被描述为“合作伙伴 X 流量”。它还允许您暂停一个应用程序或环境，而无需停用合作伙伴的整个业务。

第 2 步：颁发委托合作伙伴密钥

合作伙伴密钥应该是一流的平台对象，而不是电子表格中的静态令牌。每个密钥都应具有元数据和策略绑定：

• 合作伙伴组织 ID
• 应用程序 ID
• 环境
• 允许的API界面，例如聊天、嵌入、批量或图像生成
• 允许的模型别名
• 适用的区域或数据驻留限制
• 速率限制层
• 支出上限或预付余额规则
• 创建时间、上次使用时间、所有者和轮换状态

尽可能仅存储散列密钥材料，在创建时仅公开一次完整机密，并支持轮换而无需停机。实用的轮换模型允许在短暂的转换窗口内使用两个活动密钥，审核日志会显示每个请求使用了哪个密钥。

第 3 步：将权利与路由分开

当前支持的任何路由代码均不应暗示合作伙伴使用模型的权利。保持权利检查明确并与提供商选择分开。

例如，model: premium-reasoning 的请求应首先通过政策决策：

• 该合作伙伴是否可以使用模型别名？
• 合作伙伴应用程序是否允许在此环境中使用它？
• 请求是否在允许的区域或数据边界内？
• 合同是否有效且信誉良好？
• 合作伙伴是否符合支出、配额和滥用阈值？

只有在做出决定后，路由才应选择上游提供商、提供商项目、部署或后备路径。这很重要，因为模型路由更改在操作上很频繁。权利变更应经过深思熟虑且可审核。

第 4 步：发布稳定的合作伙伴 API Surface

即使您的上游提供商发生变化，合作伙伴也需要稳定的行为。使用您自己的模型别名和功能描述，而不是直接公开每个提供程序模型名称。

一个小例子：

POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123

{
  "model": "standard-chat",
  "messages": [
    {"role": "user", "content": "Summarize this support thread."}
  ],
  "metadata": {
    "ticket_id": "T-44821",
    "workflow": "support_summary"
  }
}

合作伙伴要求standard-chat。您的网关将该别名映射到当前批准的提供商和模型，并受权利、可用性、价格、延迟、区域和质量规则的约束。

不过，请避免隐藏所有提供商差异。如果两个模型别名具有不同的上下文窗口、结构化输出支持、工具调用行为、延迟配置文件或区域可用性，请清楚地记录这些差异。抽象应该简化集成，而不是创造意外的行为。

第 5 步：在调用提供商之前强制执行配额

提供商限制是有用的护栏，但合作伙伴级别的强制执行属于您的平台。一个上游提供商项目可能为许多合作伙伴提供服务，或者一个合作伙伴可能拥有多个具有不同合同的应用程序。仅依靠提供商级别的速率限制无法清楚地表达这些区别。

在进行上游调用之前应用配额检查：

• 合作伙伴密钥每分钟的请求数
• 合作伙伴组织每分钟的令牌
• 应用程序的并发请求
• 每日或每月计费单位配额
• 预付余额或信用额度
• 如有需要，每最终客户上限

对于同步请求，当请求无法接受时明确拒绝。对于异步和批处理工作负载，请分别考虑队列准入和执行配额。可以接受批量上传，但仍应计量单个作业，并在达到合作伙伴限制时停止。

第 6 步：返回可预测的速率限制信号

不透明429 Too Many Requests响应会产生可避免的支持请求。针对成功响应和受限响应返回合作伙伴可见的配额信号。

有用的回复可以包括：

RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...

建议：

• 记录限制是否适用于每个密钥、应用程序、组织、模型或端点。
• 返回客户端可以执行操作的重置时间。
• 使用 Retry-After 来限制响应。
• 保持错误体稳定且机器可读。
• 请勿公开上游提供商的内部结构，除非合作伙伴需要它们来调试行为。

这使得合作伙伴客户端更容易构建，并减少流量高峰期间的重试风暴。

第 7 步：使用幂等性进行计费工作

任何创建状态或计费工作的端点都应支持幂等性密钥。这对于异步生成作业、批量提交、信用购买、网络钩子触发的重试和长时间运行的任务尤其重要。

实现规则很简单：当合作伙伴在保留窗口内使用相同的幂等键重复相同的请求时，返回原始结果而不是创建重复的工作。

明确边缘情况：

• 幂等记录保留多长时间
• 幂等性密钥的范围为哪个端点和合作伙伴密钥
• 如果同一密钥与不同的请求参数重复使用会发生什么情况
• 是否缓存失败的请求
• 幂等性如何应用于部分完成的批处理作业

对于可计费的 LLM 工作，请存储足够的请求指纹数据以检测参数不匹配，而不保留不必要的敏感负载内容。

第 8 步：发出不可变的使用事件

不要将提供商发票视为合作伙伴计费的真实来源。提供商发票通常不知道您的合作伙伴合同、加价规则、经销商等级、最终客户 ID 或争议工作流程。相反，当每个请求达到最终状态时发出不可变的使用事件。

使用事件应包括：

• 合作伙伴组织 ID
• 应用 ID 和环境
• API密钥 ID，而不是原始密钥
• 最终客户 ID（如果提供且允许）
• 请求 ID 和提供商相关 ID
• 模型别名和上游提供商模型
• 输入令牌、输出令牌、缓存令牌或其他计费单位
• 提供商成本基础（如果可用）
• 合作伙伴结算单位、加价、信用提款或合同费率
• 状态、错误类别、延迟时间和重试次数
• 时间戳和架构版本

这些事件为合作伙伴信息中心、结算导出、异常检测、配额计数器和调节提供数据。保持事件流仅附加。更正应该是调整事件，而不是静默编辑。

第 9 步：每日协调

计量只有在协调时才有用。构建每日流程，将您的使用事件与上游提供商的使用情况、提供商发票、信用余额和面向合作伙伴的结算记录进行比较。

调节流程应确定：

• 网关接受但缺少终端使用事件的请求
• 无法映射到合作伙伴请求的提供商使用情况
• 提供商报告和网关记录之间的令牌计数差异
• 计费错误的重试
• 手动积分、退款和帐单更正
• 合作伙伴即将承诺支出、预付费用尽或异常增长

这也是财务、支持和工程需要相同 ID 的地方。如果信息中心、发票行项目、日志事件和提供商记录无法关联在一起，争议就会变成手动调查。

第 10 步：构建操作运行手册

合作伙伴API 是外部产品表面，因此必须在事件发生之前规划操作行为。至少，为这些情况编写操作手册：

• 合作伙伴密钥遭到泄露：撤销或暂停一个密钥、通知合作伙伴、保留审核日志并提供轮换路径。
• 失控使用：应用紧急上限、暂停应用或需要批准才能进一步使用。
• 提供商中断：故障转移到批准的提供商或返回稳定错误并提供重试指导。
• 配额耗尽：显示合作伙伴是否需要等待、升级、购买积分或减少流量。
• Webhook 重播：验证签名、使用幂等性并跟踪事件传送尝试。
• 帐单更正：创建调整事件并保留原始使用记录。

运行手册应定义谁可以执行每项操作。暂停一个密钥与禁用合作伙伴组织不同。提高配额与更改合同不同。紧急控制需要审核跟踪。

权衡

合作伙伴API网关增加了延迟和运营责任。这是在合作伙伴合同级别控制凭据、配额、路由、结算和可见性的成本。

严格的配额可以保护利润并减少滥用，但如果突发行为和重试指南设计不当，可能会造成不必要的失败。有用的配额系统既具有硬性限制，又具有记录的突发行为。

详细的计量可提高结算透明度并支持结果，但会增加保留、隐私和对账义务。收集操作和结算所需的标识符，但避免在结算记录中存储原始提示和响应内容，除非有明确的合同和合规依据。

模型抽象使合作伙伴集成更加简单，但过度抽象可能会隐藏实质性差异。合作伙伴不需要了解每个提供程序实现细节，但他们确实需要知道模型别名何时更改上下文限制、输出格式、延迟预期或区域可用性。

实施清单

• 颁发平台拥有的合作伙伴密钥，而不是共享提供商凭据。
• 将每个键映射到合作伙伴、应用程序、环境、权利、配额和结算记录。
• 将授权和权利检查与路由逻辑分开。
• 使用具有记录的功能和限制的稳定模型别名。
• 在调用上游提供商之前应用配额检查。
• 返回速率限制标头和机器可读错误。
• 创建状态或计费工作的端点需要幂等密钥。
• 请求完成时发出不可变的使用事件。
• 根据提供商记录和合作伙伴发票协调使用情况。
• 维护针对密钥泄露、失控使用、提供商中断、配额耗尽、网络钩子重播和帐单更正的操作手册。

可行的结论

LLM 访问最安全的合作伙伴API不是使用隐藏凭据转发请求的代理。它是一个委托访问系统，拥有自己的身份模型、政策层、配额执行、使用计量、协调流程和面向合作伙伴的透明度。

从控制边界开始：合作伙伴密钥、显式权利、调用前配额检查、幂等状态更改端点和不可变使用事件。然后添加操作成熟度：仪表板、协调、速率限制语义和事件运行手册。此架构让合作伙伴无需接收原始提供商密钥即可构建 LLM 功能，同时为平台提供足够的控制权来管理成本、滥用、可靠性和计费争议。

相关阅读

• 为团队和合作伙伴集成设计受管理的 API 密钥