从 OpenAI 迁移到 RouteAPI

本指南帮助你将现有的 OpenAI 应用迁移到 RouteAPI。大多数场景下，你只需要修改 Base URL 和 API Key，其他代码保持不变。

为什么迁移到 RouteAPI

RouteAPI 在保持 OpenAI 兼容性的基础上提供更多能力：

统一多供应商访问 - 除了 OpenAI，还可以使用 Claude、Gemini、Azure、AWS Bedrock 等模型，无需改动代码
成本管理与预算控制 - 集中管理多个模型的用量和额度，避免超支
可观测性增强 - 统一的请求日志、用量统计和性能监控
高可用与负载均衡 - 自动故障转移和多渠道负载分配
灵活的权限与配额 - 为不同团队、项目或环境创建独立的 Token 和限额

迁移难度评估

场景	改动范围	预计耗时
使用 OpenAI SDK（Python/Node.js）	仅修改初始化配置（2 行代码）	< 5 分钟
使用 LangChain/LiteLLM 等框架	修改配置参数	< 10 分钟
使用 Cursor/Claude Code 等客户端	修改设置面板的 Base URL 和 Key	< 5 分钟
直接使用 HTTP 请求	修改请求 URL 和认证头	< 10 分钟

基础配置修改

迁移的核心步骤是修改两个配置项：

1. 修改 Base URL

将 OpenAI 的 Base URL 替换为 RouteAPI：

# OpenAI 原始地址
https://api.openai.com/v1

# RouteAPI 地址
https://api.routeapi.ai/v1

2. 替换 API Key

使用 RouteAPI Token 替换 OpenAI API Key：

登录 RouteAPI 控制台
在 API Keys 页面创建新令牌
复制并保存令牌（格式类似 sk-...）

3. 环境变量管理

推荐使用环境变量管理密钥：

# .env 文件
ROUTEAPI_KEY=sk-your-routeapi-token

安全提示：不要把 Token 提交到版本库，使用 .gitignore 排除 .env 文件。

Python SDK 迁移

OpenAI SDK

只需修改 base_url 和 api_key 参数：

# 迁移前 - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # OpenAI Key
)

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

# 迁移后 - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # 使用 RouteAPI Token
    base_url="https://api.routeapi.ai/v1",  # 指向 RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # 或使用其他模型如 claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

变化点：

添加 base_url 参数
替换 api_key，推荐从环境变量读取
可选：更换 model 为 RouteAPI 支持的其他模型

LangChain 配置

# 迁移前
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# 迁移后
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

LiteLLM 配置

# 迁移前
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# 迁移后
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Node.js SDK 迁移

OpenAI SDK

只需修改初始化配置：

// 迁移前 - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // OpenAI Key
});

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

// 迁移后 - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // 使用 RouteAPI Token
  baseURL: 'https://api.routeapi.ai/v1',  // 指向 RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // 或使用其他模型如 claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

变化点：

添加 baseURL 参数
替换 apiKey，推荐从环境变量读取
可选：更换 model 为 RouteAPI 支持的其他模型

客户端工具迁移

如果你使用 IDE 客户端或编码代理，只需在设置面板修改配置：

客户端	配置文档
Cursor	Cursor 接入配置
Claude Code	Claude Code 接入配置
OpenCode	OpenCode 接入配置
Codex (oh-my-codex)	Codex 接入配置

通常只需修改两项：

Base URL / API Endpoint → https://api.routeapi.ai/v1
API Key → 你的 RouteAPI Token

参数兼容性检查

保持不变的参数

以下参数在 RouteAPI 中与 OpenAI 行为一致：

model - 模型 ID
messages - 对话消息数组
temperature - 随机性控制（0-2）
max_tokens - 最大生成 Token 数
top_p - 核采样参数
frequency_penalty - 频率惩罚
presence_penalty - 存在惩罚
stop - 停止序列
stream - 是否启用流式响应
user - 终端用户标识符
n - 返回结果数量

需要注意的参数

某些参数的支持取决于所选模型的能力：

参数	说明	依赖
`tools` / `tool_choice`	工具调用（Function Calling）	需要模型支持工具调用
`response_format`	结构化输出（JSON mode）	需要模型支持 JSON 输出
`seed`	确定性采样种子	部分模型支持
`logprobs` / `top_logprobs`	返回 token 概率	部分模型支持

建议：对高级参数，先在测试环境验证目标模型是否支持。

显式零值处理

RouteAPI 遵循 Rule 5 约定：

如果客户端显式传入 temperature=0、top_p=0 或 max_tokens=0，这些值会被原样转发到上游模型
不会被当作”未设置”而忽略

这意味着你可以放心使用 temperature=0 来获得确定性输出。

模型名称

查询可用模型

迁移后，你可以访问 OpenAI 之外的更多模型。使用 /v1/models 接口查询：

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

响应示例：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...更多模型
  ]
}

使用模型 ID

重要：请求时使用模型的 id 字段（如 claude-3-5-sonnet-20241022），而不是展示名称（如 “Claude 3.5 Sonnet”）。

# ✅ 正确 - 使用模型 ID
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ 错误 - 使用展示名称
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # 会报错
    messages=[...],
)

跨供应商模型替换

迁移到 RouteAPI 后，你可以轻松尝试不同供应商的模型：

# OpenAI 模型
model="gpt-4"
model="gpt-4o"

# Anthropic Claude 模型
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Google Gemini 模型
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# AWS Bedrock 模型（通过 RouteAPI）
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

只需修改 model 参数，其他代码无需改动。

测试和验证

测试清单

迁移完成后，建议按以下清单验证：

认证测试 - 确认 Token 有效，能成功调用 /v1/models
基础调用 - 测试 chat.completions.create 是否正常返回
流式响应 - 如果使用 stream=True，验证流式输出是否正常
工具调用 - 如果使用 Function Calling，验证工具调用流程
错误处理 - 测试余额不足、限流、无效参数等错误场景
用量统计 - 在 RouteAPI 控制台查看用量日志是否正确记录

常见问题排查

错误码	常见原因	解决方法
401 Unauthorized	Token 无效或缺失	检查 `Authorization` 头格式：`Bearer sk-...`
402 Payment Required	余额不足或额度耗尽	登录控制台充值或提高 Token 额度
404 Not Found	Base URL 错误或路径拼写错误	确认 Base URL 为 `https://api.routeapi.ai/v1`
429 Too Many Requests	触发限流	降低请求频率，或联系管理员提高限额
500 Internal Server Error	上游模型服务异常	重试请求，或切换到备用模型

调试技巧：

使用 cURL 直接测试接口，排除 SDK 配置问题
检查 RouteAPI 控制台的用量日志，查看具体错误信息
对比原 OpenAI 请求和 RouteAPI 请求的参数差异

示例：使用 cURL 测试

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果 cURL 请求成功，说明 Token 和 Base URL 配置正确，问题可能出在 SDK 层。

分步迁移建议

对于生产环境，建议采用渐进式迁移策略：

1. 先在测试环境验证

在开发或测试环境完整测试迁移后的代码
验证核心功能、边界情况和错误处理
对比 OpenAI 和 RouteAPI 的响应内容和性能

2. 灰度发布

使用功能开关（Feature Flag）控制 Base URL 切换
先对小部分流量启用 RouteAPI
观察错误率、延迟和用户反馈

示例：使用环境变量控制

import os

# 通过环境变量控制是否使用 RouteAPI
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. 监控用量日志和错误率

迁移后密切关注：

请求成功率 - 是否有异常的 4xx/5xx 错误
响应延迟 - P50、P95、P99 延迟分布
Token 用量 - 计费是否符合预期
模型可用性 - 不同模型的成功率和延迟

在 RouteAPI 控制台的”用量日志”页面可以查看详细记录。

4. 回滚方案

准备快速回滚到 OpenAI 的方案：

保留原 OpenAI API Key，不要立即删除
使用配置中心或环境变量管理 Base URL，便于快速切换
在监控中设置告警阈值，自动触发回滚

# 回滚示例：修改环境变量即可切换
# USE_ROUTEAPI=false -> 使用 OpenAI
# USE_ROUTEAPI=true -> 使用 RouteAPI

迁移后的优化建议

1. 利用多模型能力

RouteAPI 支持多个供应商的模型。根据场景选择最合适的模型：

延迟敏感场景 - 使用 gemini-2.0-flash-exp 或 gpt-4o-mini
复杂推理任务 - 使用 claude-3-5-sonnet-20241022 或 gpt-4
成本优化 - 对比不同模型的性价比，选择最优方案

2. 设置独立 Token

为不同项目、环境或团队创建独立的 Token：

开发环境 - 低额度 Token，避免测试时产生大量费用
生产环境 - 高额度 Token，并设置告警
不同团队 - 独立 Token 便于成本归属和审计

3. 启用请求日志

在 RouteAPI 控制台查看详细的请求日志：

每次请求的模型、Token 用量、延迟
错误请求的原因和堆栈
用量趋势和成本分析

这些日志有助于优化成本和排查问题。

获取帮助

如果迁移过程中遇到问题：

查看 API 参考文档
访问 RouteAPI 控制台查看用量日志
联系技术支持获取帮助

相关文档：