迁移到兼容 OpenAI 的 API 网关：在翻转基本 URL 之前构建兼容性合同

更改 base_url、api_key 和 model 通常足以使简单的聊天演示针对 OpenAI 兼容 API 进行工作。仅仅证明生产迁移是安全的还不够。

失败通常会稍后出现：流式工具调用以不同的形状到达、JSON 模式模式被忽略、嵌入模型返回不同的向量大小、缺少使用字段、重试双重提交副作用或特定于提供程序的推理选项默默地不执行任何操作。实际目标不是询问端点是否抽象地“兼容 OpenAI”。目标是定义您的应用程序依赖于 OpenAI 型合同的哪些部分，测试这些部分，并仅在合同明确后通过网关进行路由。

本指南展示了如何将团队从特定于提供商的 SDK 或分散的兼容端点迁移到一个 OpenAI 兼容网关，同时保留可靠性、使用归因和回滚选项。

此迁移中的事实、建议和预测是什么？

事实：一些提供商记录了其部分 API 的 OpenAI 兼容路径或 SDK 使用情况。 Google 通过更改 API 密钥、基本 URL 和模型记录了通过 OpenAI Python 和 TypeScript 库以及 REST 进行 Gemini 访问，同时还建议尚未使用 OpenAI 库的应用程序直接使用 Gemini API。 Gemini 的兼容性文档涵盖聊天完成、流媒体、函数调用、图像理解、嵌入、推理工作映射以及通过额外请求主体提供的特定于提供者的选项。 AI 共同记录了 OpenAI REST 和 SDK 对多种模式的兼容性，但其矩阵还列出了不受支持的 OpenAI 形状的表面，例如助手、线程和运行。 Mistral 通过更改基本 URL 和模型名称来记录 OpenAI 兼容客户端的迁移路径。 Groq 公开 OpenAI 路径聊天完成端点。 vLLM 提供了一个与 OpenAI 兼容的服务器，用于完成和聊天，同时记录参数差异。 OpenAI Agents SDK 文档警告说，许多非 OpenAI 提供商尚不支持较新的 Responses API，并且聊天完成模式通常是更安全的兼容性目标。

建议：将兼容性视为经过测试的应用程序合同。清点应用程序使用的确切端点和功能，创建提供程序和模型功能矩阵，在流量迁移之前编写一致性测试，规范网关边界处的已知请求和响应差异，并使用每个应用程序密钥和回滚配置文件进行部署。

预测：OpenAI 兼容表面将仍然作为摩擦最低的集成层发挥作用，但提供商的原生功能将继续出现分歧。维持兼容性合同的团队将能够比依赖非正式“直接替换”假设的团队更快地采用新模型。

第 1 步：盘点当前每个 AI 调用

从清单开始，而不是更改代码。当团队假设所有 AI 调用看起来都像聊天完成并仅在发布后才发现隐藏的依赖项时，迁移就会失败。

每个调用站点创建一行。包括计划作业、内部工具、笔记本、后台工作人员、评估工具和面向客户的服务。

应用程序：支持助理
所有者：客户平台
当前提供者：提供者_a
当前_sdk：provider_a_python_sdk
端点形状：聊天完成
型号：provider-a-large-2026
特点：
  - 流媒体
  - 工具调用
  - json_schema_output
  - 使用情况_会计
延迟预算毫秒：8000
重试策略：retry_429_5xx_no_tool_side_effects
Monthly_volume_estimate: 240 万个请求
rollback_contact：oncall-客户-平台

按端点和功能（而不仅仅是按型号）对每个呼叫进行分类。单个型号名称可能隐藏非常不同的兼容性要求，具体取决于其使用方式。

库存清单

• 聊天：消息、系统指令、温度、top-p、最大令牌、停止序列。
• 流式处理：服务器发送的事件解析器、最终块、流中的使用情况、取消行为。
• 工具：函数架构、并行调用、参数 JSON、工具结果消息、副作用安全性。
• 结构化输出：JSON 模式、JSON 架构、严格验证、回退修复逻辑。
• 视觉或多模式输入：图像 URL、base64、MIME 处理、详细参数。
• 嵌入：模型 ID、向量维度、标准化期望、索引兼容性。
• 文件和批处理：上传 API、作业轮询、取消、输出格式。
• 推理控制：推理工作、思维预算、隐藏令牌、特定于提供商的设置。
• 错误：速率限制形式、超时形式、内容政策错误、可重试状态代码。
• 使用和计费：提示令牌、完成令牌、缓存令牌、推理令牌、成本分配标签。

此步骤的输出是依赖关系图。它告诉您哪些应用程序可以使用简单的 OpenAI 兼容 API 配置文件进行迁移，以及哪些应用程序需要适配器工作。

第2步：构建兼容性契约表

兼容性合同是一个表格，其中说明了对于每个应用程序功能，网关必须保证什么以及如何测试它。它应该足够具体，以便工程和产品团队做出部署决策。

<表> <标题> 功能 所需行为 网关决策 需要测试吗？ <正文> 聊天完成 接受 OpenAI 风格的消息并返回助手文本 标准化请求和响应字段 是 流媒体 发出可解析的增量和可靠的完成信号 尽可能标准化流块格式 是 工具调用 返回工具名称和有效的 JSON 参数 仅通过明确的策略进行验证和修复 是 工具调用流 参数可以确定性地重建 如果提供程序块不兼容，则缓冲区增量 是 结构化输出 响应必须根据预期架构进行验证 使用模型配置文件支持和应用程序验证 是 视觉输入 以应用程序使用的格式接受的图像 尽早拒绝不支持的参数 是 嵌入 目标索引的稳定向量维度 引脚嵌入模型轮廓和尺寸 是 文件 已知的上传、引用、保留和删除行为 除非映射，否则不要声明支持 是 批次 作业提交、轮询和输出解析稳定 将配置文件与实时推理分开 是 推理控制 每个模型记录的努力或思考设置 使用受控传递字段 是 使用情况统计 可用于归因的令牌和成本字段 标准化网关的使用分类帐 是 错误语义 可重试和不可重试错误分类 地图状态、代码和提供商元数据 是

此表还可以防止过度承诺。如果提供商支持聊天和嵌入，但不支持文件或类似助手的工作流程，则合同中应注明。当避免生产意外时，“不受支持”是有效的迁移结果。

第 3 步：创建模型配置文件而不是分散模型 ID

请勿在每个应用中将一个硬编码模型 ID 替换为另一个硬编码模型 ID。使用模型配置文件。

个人资料：support-chat-fast
openai_model_alias：支持快速聊天
提供者：provider_b
提供商模型：提供商-b/聊天-大型-快速
端点：chat.completions
特点：
  流媒体：真实
  工具：真实
  结构化输出：模式验证
  愿景：假
  嵌入：假
请求策略：
  drop_unsupported_params: false
  拒绝未知参数：true
  pass_through_extra_body：[“reasoning_effort”]
Fallback_profile：支持聊天安全
cost_center_required：true

此配置文件为应用程序提供了稳定的名称，而网关拥有提供商映射。它还处理使用命名空间模型 ID 而不是平面模型命名空间的提供程序。该应用程序要求support-chat-fast；网关决定当前是否映射到 Together 样式命名空间模型、Gemini 兼容模型、Mistral 兼容模型、Groq 聊天模型、自托管 vLLM 端点或其他批准的目标。

权衡是治理开销。必须对配置文件进行记录、审查和版本控制。好处是迁移、回滚和模型替换不需要重新部署每个应用程序。

第 4 步：在迁移之前编写一致性测试

一致性测试是小型、可重复的检查，可根据每个目标配置文件验证您的合同。它们应该在首次推出之前以及每当提供程序、模型、SDK 或网关适配器发生更改时运行。

最小测试套件

• 黄金提示测试：发送确定性提示并验证响应形式、完成原因、安全行为和基本语义要求。除非应用程序真正依赖它，否则不需要精确的措辞。
• 流解析器测试：确认您的客户端可以解析每个块、重建最终文本、处理取消并检测流完成。
• 工具调用往返：强制工具调用、解析参数、执行假工具、返回工具结果，并确认模型正确继续。
• 工具调用流测试：验证部分参数增量可以在工具执行之前缓冲和重建。如果没有，请禁用该配置文件的增量工具执行。
• JSON 架构验证：测试有效输出、无效输出、缺失字段、额外字段以及拒绝或错误情况。
• 嵌入维度检查：在重用现有索引之前确认向量长度、数字类型以及与目标向量索引的兼容性。
• 重试和幂等性测试：模拟 429、500、超时和部分流故障。确保工具的副作用不会意外重复。
• 使用情况调节：将网关使用记录与提供商报告的使用字段以及您的帐单期望进行比较。

使测试接近生产流量模式。单个“写一首诗”提示几乎无法证明依赖于工具、JSON、嵌入和使用情况统计的工作流程。

第 5 步：规范网关边界的怪癖

兼容 OpenAI 的网关应该减少应用程序代码更改，但不应假装每个提供商的行为都相同。使用适配器来解决已知差异并使行为可见。

请求规范化

• 模型别名：将面向应用的稳定配置文件名称映射到特定于提供商的模型 ID。
• 不支持的参数：默认情况下拒绝不支持的参数并显示明显错误。无声掉落在演示过程中很方便，但在生产过程中很危险。
• 特定于提供商的选项：仅在记录的模型配置文件中允许受控传递字段，例如推理或思维控制。
• 消息转换：标准化系统、开发人员、用户、助手和工具消息，其中目标提供商期望采用不同的形式。
• 超时预算：应用一个应用程序级别的截止时间，而不是让 SDK 默认值累积。

响应标准化

• 文本和工具选择：为辅助文本、工具调用和完成原因返回一致的形状。
• 流式传输块：标准化常见增量并记录需要缓冲的位置。
• 使用字段：存储提供商本机使用情况以及标准化提示、完成和可用的令牌总数。
• 错误形状：将状态代码、可重试性、提供程序错误代码和请求 ID 映射到一个错误架构中。
• 成本元数据：附加应用、团队、配置文件、提供商、模型和环境标签以供以后分析。

主要的权衡是可移植性与提供商的能力。标准化为最小公共表面可提高互换性。允许特定于提供商的字段保留了高级功能，但每个传递选项都成为配置文件文档和测试矩阵的一部分。

第 6 步：使用每个应用密钥和回滚配置文件进行部署

迁移应该是可逆的，无需重新部署代码。为每个应用程序、环境和团队使用单独的 API 密钥。单个共享密钥使使用归因和紧急回滚变得更加困难。

安全的推出顺序如下所示：

1. 开发简介：仅通过网关路由本地和临时流量。修复请求形状和解析器问题。
2. 影子测试：将代表请求重播到新配置文件，而不影响用户可见的输出。比较架构有效性、工具行为、延迟类别和使用字段。
3. 小型生产切片：移动少量流量或一个内部租户。观察错误、重试、面向用户的质量信号和成本。
4. 按应用扩展：一次迁移一个应用。请勿将聊天、嵌入、批处理和文件一起迁移，除非它们具有相同的风险状况。
5. 回滚配置文件：在同一面向应用的别名或快速配置开关后面保留已知良好的提供商/模型配置文件。
6. 迁移后锁定：稳定后，从应用程序环境中删除直接提供商密钥，以便流量无法绕过网关控制。

回滚应该像任何其他路径一样进行测试。如果模型配置文件可以在网关中切换，请在安静期间测试该切换，并确认应用程序日志、使用情况分析和计费归属保持一致。

示例：用一个网关合约替换分散的端点

假设一个团队拥有三个应用：

• 使用流式聊天和工具的客户支持助理。
• 需要严格 JSON 输出的内容分类器。
• 使用矢量数据库中存储的嵌入的搜索服务。

有风险的迁移会将所有三个应用更改为相同的基本 URL，并选择三个新的模型 ID。更安全的迁移将合约分开：

• 支持聊天配置文件：需要流式传输、工具调用、缓冲的工具调用增量、重试分类和使用情况日志记录。
• classifier-json 配置文件：需要架构验证、拒绝处理，并且不能静默删除参数。
• 搜索嵌入配置文件：需要固定的向量维度和索引迁移计划（如果维度发生变化）。

每个配置文件都有自己的一致性测试和部署。支持助理可能需要流适配器工作。如果模式验证位于模型外部，则分类器可能会快速通过。嵌入服务可能需要新索引而不是就地模型交换。网关为团队提供了一个与 OpenAI 兼容的基本 URL，但兼容性合同使迁移保持诚实。

迁移清单

• 列出每个 AI 调用站点，包括后台作业和内部脚本。
• 按端点、功能、模型、所有者和回滚路径对调用进行分类。
• 定义面向应用的模型配置文件，而不是硬编码提供商模型 ID。
• 为每个提供商和模型配置文件创建一个能力矩阵。
• 拒绝不受支持的参数，除非配置文件明确允许传递。
• 测试流、工具、结构化输出、嵌入、错误、重试和使用字段。
• 使用每个应用和每个环境的 API 密钥进行归因和控制。
• 在用户可见的生产流量之前运行影子测试。
• 一次推出一个应用程序或要素类。
• 保持经过测试的回滚配置文件可用，无需重新部署代码。

可行的结论

兼容 OpenAI 的 API 网关在成为受控迁移层（而不仅仅是不同的 URL）时才最有价值。基本 URL 开关减少了机械代码更改。兼容性合同降低了运营风险。

在翻转生产流量之前，写下应用程序实际需要的内容：流行为、工具语义、模式保证、嵌入维度、重试规则、使用字段和错误含义。将这些需求转换为模型配置文件、适配器规则和一致性测试。然后推出每个应用程序的密钥、分析和回滚配置文件。

如果简单的聊天路径有效，请将其视为一个好的开始。将迁移的其余部分视为工程工作，应与数据库、队列或支付提供商更改相同的规则。

相关阅读

• 跨多个模型提供商的结构化输出验证
• 模型替换和回滚操作手册
• 使用情况分析和令牌网关中的协调