API Migration 指南:安全切换 LLM 提供商
本 API 迁移指南介绍如何将已连接 OpenAI 兼容聊天接口的应用迁移至其他提供商。大部分工作并非那两行代码的修改,而是找出哪些内容因意外而依赖于旧提供商。
最后更新

总结
- 对于兼容 OpenAI 的目标,需更改 Base URL、API 密钥和模型 ID,然后验证行为。
- 首先列出功能清单:嵌入向量、图像和微调不会迁移至仅支持文本的 API。
- 通过标志按比例上线,以便回滚只需更改一次配置。
- 在切换前,根据你的 token 用量估算新账单。
六步计划
- 列出应用调用的每个 API 功能。
- 将提供商设置移至配置中。
- 映射参数和模型名称。
- 添加匹配新限制的错误和速率限制处理。
- 将少量流量路由至新提供商并进行比较。
- 检查费用,完成切换,并保留旧路由一段时间。
示例中的目标是 https://api.apimigration.com/v1,模型 ID 为 uncensored。这些步骤适用于任何兼容 OpenAI 的提供商,因此请将其视为检查清单而非特定供应商的操作指南。如果途中出现问题,请参阅 常见 LLM 集成错误故障排除文章 了解常见原因。
步骤 1:清点应用使用的功能
在代码中搜索对旧提供商的所有调用,并列出功能以及端点。单个聊天请求通常隐藏多个依赖项:依赖特定风格的系统提示词、工具模式、JSON 响应格式、大上下文。
| 应用中的功能 | 此 API 支持情况 |
|---|---|
聊天补全,/v1/responses | 支持 |
| SSE 流式输出 | 支持,用法在末尾发送 |
| 函数调用 | 支持,包括流式输出 tool_calls |
| JSON 模式 | 通过 response_format 支持 |
| 上下文 | 100,000 个 token,提示词加补全 |
| 嵌入向量、图像、音频、微调 | 不提供,请保留在其他提供商处 |
如果旧提供商也处理嵌入向量或图像生成,请拆分迁移:仅迁移文本调用,其余保留原处。
步骤 2:将提供商设置放入配置
硬编码的 Base URL 会导致迁移变成代码变更。从环境变量中读取 Base URL、API 密钥和模型 ID,以便在不部署的情况下切换。
export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["LLM_BASE_URL"],
api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")
认证使用标准的 Authorization: Bearer 头,SDK 会为你设置。要确认 API 密钥并查看服务器提供的内容,请调用 GET /v1/models。
curl https://api.apimigration.com/v1/models \
-H "Authorization: Bearer $LLM_API_KEY"步骤 3:映射参数和提示词
此 API 透传的参数包括:temperature、top_p、stop、seed 以及频率和存在惩罚。max_tokens 是可选的。如果你的旧代码设置它以防止成本失控,请保留它。
有三件事值得仔细检查。
- 供应商特定字段。 任何不在 OpenAI 请求格式内的内容都可能会被忽略或拒绝。发送包含你实际生产负载的请求并读取响应。
- 模型行为。 不同模型对相同提示词的理解不同。针对旧模型优化的系统提示词通常需要进行小幅度编辑。请测试它们,不要假设。
- 拒绝。 如果你的旧提示词包含避免拒绝的变通方法,通常可以在此处删除它们,从而缩短提示词。
模型在回答内容上也有差异。此模型针对合法成人用途进行了调整,不会拒绝内容,且会屏蔽涉及未成年人的性内容。
步骤 4:匹配错误处理以适应新限制
完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个和 60 个。超出限制时,你会收到 HTTP 429,错误代码为 rate_limited 或 concurrency。在临时过载时,你也会收到 429,并带有 Retry-After: 5。
import time
from openai import RateLimitError
def chat(messages, retries=4):
for attempt in range(retries):
try:
return client.chat.completions.create(model=MODEL, messages=messages)
except RateLimitError:
time.sleep(5 * (attempt + 1))
raise RuntimeError("still rate limited after retries")
流式请求在流结束前会保留其并发槽位,因此卡住的客户端会导致其他请求饥饿。在 finally 块中关闭流。如果你的旧提供商允许更多并行请求,请添加一个大小适应新限制的信号量。失败的请求不会收费,这使得重试对预算安全。
步骤 5:按比例上线
不要一次性全部切换。将一小部分稳定的用户比例发送到新提供商,并将旧提供商作为后备。对用户 ID 进行哈希处理可确保每个用户固定在一侧,从而避免对话中途改变风格。
import hashlib
def use_new(user_id: str, percent: int) -> bool:
bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
return bucket < percent
# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])
def pick(user_id):
return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client
仅在上一阶段运行干净一天左右后才提高百分比。回滚只需将环境变量设置回 0 即可。
切换后通常令团队惊讶的情况
Base URL 的更改首次尝试即可生效。意外情况稍后出现。
- 语气和格式漂移。 相同的提示词会给出措辞不同的回答。解析自由文本的功能(例如对 "Answer:" 前缀的正则表达式)会最先失效。对于程序读取的内容,优先使用 JSON 模式或函数调用。
- Token 数量不同。 每个模型对文本的分词方式不同。旧提供商的 token 数量估算会有偏差,因此请通过
usage字段重新测量。 - 输出长度。 如果不设置
max_tokens,补全可能会占用 100,000-token 上下文窗口的剩余部分。如果你的旧设置中有默认上限,请有意识地设置一个。 - 超时。 你的客户端超时时间是根据旧提供商调整的。新提供商的长回答可能会超出该限制。尽可能使用流式输出,并提高非流式调用的超时时间。
- 静默拒绝的变化。 如果你的产品曾经捕获拒绝消息并显示备用内容,相关代码可能不再触发。请决定是否仍需要它。
切换前的简短检查清单
- 你功能清单中的每个功能都有经过测试的等效功能或已记录的差距。
- Base URL、密钥和模型来自调用 API 的每个服务的配置。
- 代码中的速率限制和并发限制与新的限制匹配。
- 客户端断开连接时关闭流。
- 日志包含
X-Request-Id标头,以便你在请求帮助时引用请求。 - 余额通过
X-Balance-USD或GET /v1/balance进行监控,余额不足时会发出警报。 - 旧提供商仍有资金且已配置回滚。
- 指定人员拥有回滚决策权。
最后一项在故障发生前听起来似乎荒谬。凌晨 2 点出故障时,必须允许有人来切换标志。
第 6 步:检查成本,然后切换
根据你的实际流量计算新账单。价格为每 1M 输入 token $0.15,每 1M 输出 token $0.50。
示例:每天 10,000 次请求,每次包含 1,500 个输入 token 和 400 个输出 token。
- 输入:15,000,000 token x $0.15 / 1,000,000 = $2.25。
- 输出:4,000,000 token x $0.50 / 1,000,000 = $2.00。
- 总计:每天 $4.25。
将其与旧发票进行比较,使用旧提供商的当前定价页面。此处的计费为预付额度,无订阅,且额度永不失效。充值金额为 $20 至 $500 的整数,从 $50 起赠送 5%,从 $100 起赠送 10%,从 $200 起赠送 15%,通过加密货币(TRC20 上的 USDT 或 Base 上的 USDC)支付。余额显示在 X-Balance-USD 响应标头中,以便你对此设置警报。
新账户可领取 $0.50 的试用额度用于首次测试。查看 定价,然后 获取 API 密钥,并在映射参数时保持 文档 打开。
更多指南
常见问题
仅更改 Base URL 是否可以迁移?
对于 OpenAI 兼容 API,Base URL、密钥和模型 ID 是必须更改的内容。你仍应测试提示词,因为不同的模型回答方式不同。
我的函数调用和 JSON 模式还能用吗?
支持工具调用和 JSON 模式(response_format json_object)。在切换前使用真实提示词验证你的 Schema。
如果我的应用使用嵌入怎么办?
此 API 仅支持文本,不提供嵌入、图像生成或微调。请将这些调用保留在当前的提供商上。
如何快速回滚?
通过环境标志(如 rollout 百分比)进行路由,并保留旧客户端配置,直到新路由干净运行几天。
获取 API 密钥
注册,复制密钥,更新基础 URL。设置完成。