APIrove

首页 / API 文档 / 中转站迁移

MIGRATION GUIDE · OPENAI COMPATIBLE

从现有 AI API 中转站迁移:先验证,再切流

已有 OpenAI 兼容客户端时,配置变化通常集中在 Base URL、API Key 和模型 ID;实际兼容性还取决于端点、参数、输出与账户权限。按这份清单保留可回滚的迁移路径。

适用对象:已有 APIrove 授权账户、正在评估迁移现有文本调用的开发团队。请先注册或登录核对权限。

第 1 步:固定现有调用清单

为每条关键路径记录当前模型 ID、端点、SDK 版本、参数、是否流式、期望输出字段、超时与重试方式。挑出一条可脱敏、可重复的最小请求作为基线。不要直接把现有服务的密钥复制给新服务。

需要记录为什么
Responses 或 Chat Completions两个接口的请求和响应结构不同
模型 ID 与账户权限旧平台的名字不一定等于新平台的可用 ID
流式、工具、JSON 与其他参数“兼容”不保证具体能力一致
用量与延迟基线切流后核对费用与用户体验

第 2 步:核对目标账户

登录 APIrove,查看模型目录及账户可用模型,确认目标模型支持你要用的接口。在价格说明指引下核对账户实际价格、余额和额度。若所需模型或接口无法确认,先不要修改生产环境。新建仅用于迁移验证的密钥,并保存在服务端环境变量或密钥管理器中。

第 3 步:在独立配置中设置新地址

建议通过配置开关让新旧客户端并存。APIrove 的 Base URL 是 https://apirove.com/v1;不要把完整 /responses 路径填入 SDK 的 Base URL,也不要把旧服务密钥发到新地址。下面示例仅展示 Python OpenAI SDK 的客户端配置,模型必须是该账户真实可用的 ID。

import os
from openai import OpenAI

candidate = OpenAI(
    api_key=os.environ["APIROVE_API_KEY"],
    base_url="https://apirove.com/v1",
)
model_id = os.environ["APIROVE_MODEL_ID"]  # 从账户中核对

这个示例不自动迁移旧平台余额、对话历史、模型权限或供应商专有参数。先保留原有客户端与回滚开关。

第 4 步:用一条小请求验证端点

如果账户中的目标模型支持 Responses,可发送:

export APIROVE_API_KEY='YOUR_API_KEY'
export APIROVE_MODEL_ID='YOUR_ENABLED_MODEL_ID'

curl https://apirove.com/v1/responses \
  -H "Authorization: Bearer $APIROVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"'"$APIROVE_MODEL_ID"'","input":"Reply with OK.","max_output_tokens":16}'

如果目标模型只支持 Chat Completions,改用对应接口与 messages 格式,见请求示例。记录 HTTP 状态、实际响应、用量与 request ID(若有),但不要把密钥或原始用户数据写入公开日志。遇到 401、404、429 时按排错顺序检查地址、密钥、模型和限额。

第 5 步:对照应用级结果

让新旧服务分别处理同一组脱敏样本,比较能否完成你的真实任务,而不只看 HTTP 200。逐项检查响应字段、流式结束、工具参数、错误处理、超时、延迟与账户用量。输出可能因模型和采样设置不同而变化,重点是业务验收条件;同时在控制台核对实际扣费。

迁移前写明通过门槛,例如“关键路径全部通过、账单可解释、延迟不高于内部门槛”。门槛由你的业务决定;本页不承诺特定成功率或性能。

第 6 步:逐步切流并保留回滚

  1. 先让内部测试或非关键请求走新配置,确认监控与用量记录正常。
  2. 按团队可观察的比例扩大流量;持续比较错误率、延迟和用量,留意 429 与 5xx。
  3. 达到预设的停止条件时,切回原配置;调查前保留脱敏请求样本和时间戳。
  4. 确认稳定后再撤销不再使用的测试密钥,不要过早删除回滚所需配置。
下一步:先核对可用模型与账户价格,再用一条低额度请求完成验证。若你的需求包括未在公开文档确认的功能,应先获得明确支持信息。