多模型 SDK 迁移：为 Claude、Gemini 和 DeepSeek 保留 OpenAI 客户端

多模型 SDK 迁移不应从替换应用中的每个客户端库开始。如果您的生产代码已经在使用 OpenAI Python 或 Node SDK 进行聊天补全，那么更安全的第一步是保持该客户端接口稳定，将提供商选择移至配置中，并在扩大流量之前，通过兼容的路由证明 Claude、Gemini 和 DeepSeek 的行为。

Flatkey 专为希望在一个地方获得一个密钥、一个 OpenAI 兼容的路由层、跨提供商的模型访问以及使用和计费审查的团队而构建。这使其对多模型 SDK 迁移很有用，但并不能免除测试端点族、模型别名、流式传输、工具调用和使用记录的需要。在您使用自己的 Flatkey 密钥和当前模型目录验证之前，请将此处的每个代码示例都视为模板。

实际目标很简单：保留您的应用已经熟悉请求对象，隔离少数必须更改的值，并在切换前构建一个验证包。

多模型 SDK 迁移决策矩阵

在更改代码之前，请使用此矩阵。它将可以保持稳定的部分与必须变得可配置的部分分开。

这是多模型 SDK 迁移的核心准则：不要将库替换、提示迁移、提供商评估、计费验证和生产部署混合在一次部署中。

官方文档关于兼容性的说明

OpenAI 的 SDK 已经支持您需要的模式。当前的 OpenAI Python README 文档记录了 OpenAI 客户端和 base_url 选项，而 Node README 文档记录了标准的 OpenAI 客户端和聊天补全。OpenAI 的 API 参考 指出，聊天补全（Chat Completions）会为对话创建模型响应，支持流式传输，并返回一个聊天补全对象或流式块。

如果您按运行时拆分部署，请将此清单与 OpenAI Python SDK 自定义基础 URL 指南和 OpenAI Node SDK 基础 URL 指南结合使用。如果第一个决策是提供商路由而不是客户端设置，请在选择测试工作负载之前使用 Claude vs GPT API 路由指南。

提供商的兼容性各不相同：

重要的一点是，“OpenAI 兼容”通常意味着客户端可以发送 OpenAI 格式的请求。但这并不意味着每个参数、工具模式、推理控制、媒体输入或使用字段在不同提供商之间的行为都完全相同。

第 1 步：冻结客户端边界

通过将 OpenAI 客户端置于一个本地工厂之后来开始多模型 SDK 迁移。该工厂应该是唯一知道密钥、基础 URL、超时和模型别名的地方。

import os
from openai import OpenAI


def make_llm_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
        timeout=float(os.getenv("LLM_TIMEOUT_SECONDS", "60")),
        max_retries=int(os.getenv("LLM_MAX_RETRIES", "2")),
    )


client = make_llm_client()

completion = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[
        {"role": "system", "content": "你用简短的实现说明来回答。"},
        {"role": "user", "content": "请确切回复：migration probe ok"},
    ],
)

print(completion.choices[0].message.content)

对于 Node：

import OpenAI from "openai";

export function makeLlmClient() {
  return new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
    timeout: Number(process.env.LLM_TIMEOUT_MS ?? 60000),
    maxRetries: Number(process.env.LLM_MAX_RETRIES ?? 2),
  });
}

const client = makeLlmClient();

const completion = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL,
  messages: [
    { role: "system", content: "你用简短的实现说明来回答。" },
    { role: "user", content: "请确切回复：migration probe ok" },
  ],
});

console.log(completion.choices[0].message.content);

应用程序应调用 make_llm_client() 或 makeLlmClient()，而不是在控制器、工作程序和脚本中构造客户端。这个单一的边界使得多模型 SDK 迁移能够保持可逆性。

第 2 步：构建模型和端点映射

不要将每个工作负载都指向一个新模型名称。首先创建一个映射，命名工作负载、端点系列、当前提供商、目标提供商和回滚值。

Flatkey 的模型页面在这里很有用，因为它公开了端点类型。如果一个模型被列在原生端点系列下，不要假设它可以通过 OpenAI 聊天路径使用，直到您的账户目录和冒烟测试证明了这一点。

第 3 步：运行四提供商冒烟测试

最有用的多模型 SDK 迁移冒烟测试至少包含四个提供商行和相同的提示。保持提示的平淡无奇，这样响应风格就不会掩盖传输失败。

保存原始请求体、经过编辑的标头、响应体、HTTP 状态、模型别名、返回的请求 ID（如果有）以及仪表板使用条目。如果任何提供商需要不同的参数，请将该参数移至提供商配置文件中，而不是在您的应用程序中分散 if provider == 分支。

第 4 步：分别测试流式传输和工具调用

一个普通的补全只能证明风险最低的路径。流式传输和工具调用是独立的契约。

对于流式传输，请保存：

对于工具，请先测试一个微小的模式：

{
  "type": "function",
  "function": {
    "name": "lookup_order_status",
    "description": "Return a test order status.",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" }
      },
      "required": ["order_id"]
    }
  }
}

不要使用您最大的生产工具模式作为第一个证明。例如，Anthropic 的兼容性文档指出了 OpenAI 兼容性的局限性，并建议使用原生的 Claude API 以获得完整的 Claude 功能集。这正是一个多模型 SDK 迁移清单在推广前应该捕捉到的细节。

第 5 步：保持提供商配置文件精简

提供商配置文件应描述差异，而不是拥有业务逻辑。

{
  "support_chat": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_SUPPORT_CHAT_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": true,
    "tools": "basic",
    "fallback_alias": "support_chat_previous"
  },
  "analysis_fast": {
    "base_url_env": "FLATKEY_BASE_URL",
    "model_env": "FLATKEY_ANALYSIS_FAST_MODEL",
    "endpoint_family": "openai_chat_completions",
    "stream": false,
    "tools": "none",
    "fallback_alias": "analysis_fast_previous"
  }
}

除非您对每个目标提供商都有测试，否则不要将原生提供商功能置于共享的 OpenAI 客户端路径中。如果需要 Claude 引用、Gemini 特定的媒体行为、DeepSeek 思维控制或提供商原生的批处理端点，请创建一个命名的原生适配器，并为真正适合的工作负载保留 OpenAI 兼容路径。

第 6 步：验证计费和回滚

一次迁移如果返回了文本但丢失了计费证据，那就不算完成。在增加流量之前，请保存：

这就是 Flatkey 统一计费和使用情况审查的重要性所在。目标不仅仅是访问更多模型。多模型 SDK 迁移的目标是让产品、运营和财务部门在流量转移后能够进行检查。

多模型 SDK 迁移的切换工作流

对于第一个生产切片，请按此顺序操作：

1. 选择一个风险较低且已有 OpenAI SDK 客户端的工作负载。
2. 添加客户端工厂和环境变量，但不更改当前提供商。
3. 通过新工厂验证当前模型。
4. 通过一个简单的补全来验证一个 Claude、Gemini 或 DeepSeek 目标。
5. 仅当该工作负载使用流式传输和工具时，才验证它们。
6. 验证使用情况、计费、错误处理和回滚。
7. 将一小部分流量路由到新的模型别名。
8. 在添加下一个工作负载之前，按提供商和端点系列审查失败情况。

如果第一个工作负载需要原生提供商功能，请为首次多模型 SDK 迁移选择一个不同的工作负载。第一个切片应该证明迁移模式，而不是每个模型的功能。

常见问题解答

我可以使用一个 OpenAI SDK 客户端来处理 Claude、Gemini 和 DeepSeek 吗？

您通常可以为 OpenAI 兼容的路由保留一个 OpenAI SDK 客户端，但您仍然需要进行特定于提供商的测试。Google 和 DeepSeek 记录了 OpenAI 兼容的访问方式。Anthropic 记录了一个 OpenAI SDK 兼容层，但表示它主要用于测试和比较，而不是大多数用例的长期生产选择。

我应该以同样的方式迁移 Responses API 流量吗？

仅当目标网关和目标模型明确支持您正在使用的端点系列时才可以。聊天补全 (Chat Completions) 和响应 (Responses) 不是同一个契约。从您的应用程序已在使用的端点系列开始，然后为响应 (Responses) 创建一个单独的测试计划。

多模型 SDK 迁移中最常见的错误是什么？

最常见的错误是将更改基础 URL 视为整个迁移。一次真正的多模型 SDK 迁移还会验证模型名称、端点系列、流式传输、工具、使用情况、配额、错误处理和回滚。

我应该在什么时候保留原生提供商 SDK？

当您的工作负载依赖于兼容层未涵盖的特定于提供商的功能时，请保留原生提供商 SDK。原生的 Claude 功能、Gemini 特定的媒体路径或 DeepSeek 特定的推理控制可能需要一个单独的适配器。

最终清单

在宣布迁移完成之前，请确认您已：

多模型 SDK 迁移在平淡无奇时效果最佳：一个小型工作负载、一个客户端边界、一个模型映射，以及为您添加的每个提供商提供证据。当您准备好通过统一路由运行这些测试时，获取一个 Flatkey 密钥，并从一个低风险的 OpenAI 兼容聊天路径开始。