从 OpenAI SDK 迁移到 TheRouter

从 OpenAI API 迁移到 TheRouter 只需要改两处：base URL 和 API key。你现有的 OpenAI SDK 代码——Python、TypeScript、cURL——无需修改其余部分，因为 TheRouter 提供 OpenAI-compatible 的 /v1/chat/completions endpoint。本文会逐步讲解具体 diff、model ID 映射、fallback 配置、streaming 行为、回滚路径和成本考量。

我们把 OpenAI 兼容请求路由到已配置的供应商，并在已实现的产品路径中支持供应商 / 模型路由与故障转移。我们在已实现的范围内提供统一计费和账务。我们不承诺零停机、支持所有模型，也不承诺一定最便宜。

Before/after 代码 diff

迁移只是 base URL 和 API key 的替换，其他——消息格式、streaming、function calling——保持不变。

Python (OpenAI SDK)

# Before：直连 OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    # base_url 默认是 https://api.openai.com/v1
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

# After：通过 TheRouter
from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai/v1",
    api_key="<THEROUTER_API_KEY>",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",  # provider/model 格式
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (OpenAI SDK)

// Before：直连 OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-openai-key',
});

// After：通过 TheRouter
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.therouter.ai/v1',
  apiKey: '<THEROUTER_API_KEY>',
});

环境变量

如果你的应用通过环境变量读取 OPENAI_BASE_URL 和 OPENAI_API_KEY，迁移可以做到零代码改动：

# Before
export OPENAI_API_KEY="sk-your-openai-key"
# OPENAI_BASE_URL 默认是 https://api.openai.com/v1

# After
export OPENAI_BASE_URL="https://api.therouter.ai/v1"
export OPENAI_API_KEY="<THEROUTER_API_KEY>"

OpenAI Python SDK 会在没有传入 base_url 时自动读取 OPENAI_BASE_URL。来源：OpenAI Python SDK、OpenAI API reference，检索于 2026-06-09。

cURL

# Before
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

# After
curl https://api.therouter.ai/v1/chat/completions \
  -H "Authorization: Bearer <THEROUTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Model ID 映射

TheRouter 使用 provider/model-name 格式。从 OpenAI 迁移时，给 model ID 加上 openai/ 前缀。如果想路由到其他供应商的模型，换成对应供应商的前缀。

在 Models 页面 浏览所有可用模型。各供应商的详细配置可以看我们的 SiliconFlow 指南、DeepSeek 指南 和 阿里云百炼。

关键点：迁移后你不再局限于 OpenAI 模型。同一个 base_url 和 api_key 可以访问多个供应商的模型。

加故障转移，但不承诺零停机

TheRouter 支持模型故障转移链。传一个 models 数组代替单个 model，定义故障切换顺序。TheRouter 先尝试第一个模型，当路由因宕机、限流或审核拒绝而失败时，自动重试下一个。来源：TheRouter Model Fallbacks，检索于 2026-06-09。

import requests

response = requests.post(
    "https://api.therouter.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer <THEROUTER_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "models": [
            "openai/gpt-4o",
            "anthropic/claude-sonnet-4.5",
            "deepseek/deepseek-v4-flash",
        ],
        "messages": [{"role": "user", "content": "总结这篇文档。"}],
    },
)

使用 OpenAI SDK 时，保留 model 字段，通过 extra_body 传 fallback：

const completion = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  extra_body: {
    models: ['anthropic/claude-sonnet-4.5', 'deepseek/deepseek-v4-flash'],
  },
  messages: [{ role: 'user', content: '总结这篇文档。' }],
});

Fallback 不保证零停机。如果链中所有模型都不可用，请求会失败——你的错误处理逻辑需要覆盖这种情况。关于 fallback 模式、重试策略和成本护栏的完整讨论，见 LLM API Fallback Routing 指南。

Streaming 与 response field 行为

Streaming 用法完全一样。加 stream=True（Python）或 stream: true（TypeScript），TheRouter 会从上游供应商转发 Server-Sent Events。

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "给我讲个故事"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="")

Response field 注意事项：

• 响应中的 model 字段显示的是实际服务请求的模型。如果触发了 fallback，它会和你请求的模型不同。
• 供应商特有的 response field（如 OpenAI 的 system_fingerprint）只在上游供应商返回时才会保留。不要假设这些字段在所有路由模型中都存在。
• Token 用量字段（usage.prompt_tokens、usage.completion_tokens）直接透传自上游供应商。不同供应商对相同输入的 token 计数可能不同。

回滚路径

回滚到直连 OpenAI 就是迁移的逆操作：恢复原来的 base_url（或移除它以使用默认值）并恢复 OpenAI API key。

回滚清单

1. 还原环境变量：

   export OPENAI_BASE_URL="https://api.openai.com/v1"  # 或直接 unset
   export OPENAI_API_KEY="sk-your-openai-key"
   

2. 还原 model ID： 把 openai/gpt-4o 改回 gpt-4o，去掉 provider 前缀。

3. 移除 fallback 数组： 把 models: [...] 替换为单个 model 字段，删除 extra_body.models。

4. 检查 TheRouter 专有字段： 如果你加了 provider.order、provider.allow_fallbacks 等 TheRouter 专属字段，移除它们——OpenAI 会拒绝未知字段。

5. 确认 OpenAI API key 仍然有效。 如果迁移期间轮换或撤销了密钥，在 platform.openai.com/api-keys 重新生成。

6. 跑测试。 确认响应格式和延迟符合预期。

回滚是安全的，因为迁移只改了传输层。你的 prompt、消息历史和业务逻辑没有变动。

成本考量

TheRouter 在上游供应商成本之上有自己的定价。每次请求的总成本取决于最终服务请求的供应商和模型。

会变化的：

• 你支付的是 TheRouter 的费率而非直连供应商的费率。当前费率见 TheRouter 定价。
• Fallback 链可能路由到更贵的模型。从低价模型 fallback 到高价模型的请求，比直连低价模型的成本更高。
• 统一计费意味着一张账单代替多个供应商账户。

不会变化的：

• Token 计数由上游模型决定，不受路由层影响。
• Prompt 和 completion 长度不变。

我们不承诺一定最便宜。在把生产流量迁过来之前，拿 TheRouter 的费率和你当前直连供应商的成本做对比。如果成本敏感度高，建议先并行跑两条路径做试运行。

迁移清单

用这个清单追踪你的迁移进度：

• 在 therouter.ai 获取 TheRouter API key
• 把 base_url 改为 https://api.therouter.ai/v1
• 把 api_key 改为你的 TheRouter key
• 给 model ID 加 provider/ 前缀（如 openai/gpt-4o）
• 手动测试一个请求（cURL 或 SDK）
• 如果应用用了 streaming，测试 streaming
• 如需多供应商容灾，添加 fallback 模型
• 验证应用依赖的 response field
• 用 TheRouter 跑一遍已有的测试套件
• 监控头 24 小时的错误率和延迟
• 保留直连 OpenAI 的 API key 用于回滚

FAQ

需要改 OpenAI SDK 版本吗？

不需要。TheRouter 兼容标准 OpenAI SDK，只改 base_url 和 api_key。来源：TheRouter Quickstart，检索于 2026-06-09。

支持自定义 base URL 的工具也能用吗？

可以。Cursor、Claude Code、OpenCode 等支持自定义 OpenAI-compatible base URL 的编程工具都可以指向 TheRouter。具体配置见 Coding Tools Setup。

TheRouter 挂了怎么办？

请求会失败。TheRouter 不承诺零停机。保留你的直连供应商凭据以备回滚。建议在路由生产流量之前，先对 TheRouter endpoint 做健康检查。

能渐进式迁移吗？

可以。把一部分流量路由到 TheRouter，其余保留在直连 OpenAI。对比错误率、延迟和成本，确认路由层表现稳定后再加量。

TheRouter 支持所有 OpenAI 模型吗？

TheRouter 支持的模型列在 Models 页面。并非所有 OpenAI 模型都一定可用。迁移依赖特定模型的工作负载前，先确认模型可用性。

在哪里了解更多可用供应商？

见我们的供应商指南：OpenAI-compatible API providers、中国 OpenAI-compatible APIs、SiliconFlow 指南、DeepSeek 指南 和 阿里云百炼指南。