OpenAI 兼容接口迁移指南：已有应用平滑切换到大模型服务平台

摘要：

腾讯云大模型服务平台 TokenHub 兼容 OpenAI 协议，换 base_url、api_key、model 即可完成基础调用；卡住迁移的不是地址，而是协议与字段的逐模型差异。按协议矩阵逐项核对，能把风险收敛到上线前。

迁移的判据不是能不能调通，而是能否在改配置前列出所有会改变行为的调用。列不出来就不要进入灰度——这类差异不报错，只体现在输出结果上。

一、OpenAI 兼容的三层含义：协议、能力与字段语义

把"兼容 OpenAI"当成一个开关，是迁移中容易付出代价的误判。同一平台上，协议入口、模型能力、字段语义是三件相互独立的事，任何一层没对齐，代码照样跑得起来，结果却会变。

协议层决定"能不能调通"。TokenHub 对客户端统一提供三种协议入口，路径各不相同：

能力层决定"够不够用"，且必须逐模型看。混元翻译系列的 hy-mt2-pro、hy-mt2-plus、hy-mt2-lite 只有 Chat Completions 一条路径，Responses 与 Anthropic 都不支持；kimi-k2.8-preview、kimi-k2.7-code 支持 Chat Completions 与 Anthropic，但不支持 Responses；glm-5.2 对 Responses 走兼容模式——模型原生只提供 Chat Completions，由平台在服务端完成协议转换，部分参数与内置工具因此受限。

这几条不是特例，而是通用规律的样本：判断一个平台能不能接，看的不是它的宣传口径，而是它有没有把协议支持落到单个模型上。按"平台支持 Responses"就默认所有模型可用，代码会在这里卡住。

字段语义层决定"结果对不对"，差别发生在返回结构里。同样一段请求，在最大输出 64k 的模型（如 Hy4）与 384k 的模型（如 DeepSeek-V4 系列）上，max_tokens 的可用空间不同；个别字段可能被直接忽略或降级；usage 的明细字段也不完全一致。三层里，这一层在联调阶段最难发现。

三层的核查动作，前两层可以收成两步：先用 GET /v1/models 拉取当前可用模型，status 为 online 的才是已上线；再到控制台逐个开通要用的模型。未开通时调用返回 402，与模型是否支持该协议无关——把 402 当成"协议不支持"去改代码，是白改。

二、迁移要改的配置与四类易漏差异

改配置是确定的，改行为是不确定的。三处配置可以直接照做：

1. base_url：在线推理的 OpenAI 兼容地址按站点二选一。广州 https://tokenhub.tencentmaas.com/v1 对应中国大陆资源，新加坡 https://tokenhub-intl.tencentmaas.com/v1 对应全球资源。广州与新加坡是相互独立的站点，API Key 不互通，Key 与地址不同站会返回 401002。
2. api_key：使用目标站点创建的 Key，建议一个业务一个 Key，并把访问范围限定到实际要用的模型或服务，后续按 Key 维度对账才不会混。
3. model：填平台的模型标识，如 hy4、hy3、deepseek-v4-pro，不是原厂模型名。

第 4 项随协议变化，容易被漏掉：鉴权头。Chat Completions 与 Responses 路径用 Authorization: Bearer，Anthropic Messages 路径用 x-api-key。同一个 Key，换协议要换头，只改路径不改头会一直返回 401。

走订阅时，地址是另一种形态：腾讯云 Token Plan 的 OpenAI 协议地址为 https://tokenhub.tencentmaas.com/plan/v3（含 Chat Completions 与 Responses 两条路径），Anthropic 协议为 https://tokenhub.tencentmaas.com/plan/anthropic，新加坡站点为 tokenhub-intl 前缀。订阅额度与在线推理后付费是两套计费，把 /plan/v3 当 /v1 用，会出现"Key 有效但调不通"的现象。

四类易漏差异不会中断调用，但会改结果：

流式错误这一项尤其隐蔽。HTTP 200 只代表连接建立成功，中途出错时客户端拿到的是一段不完整的增量文本，业务侧容易把它当完整答案落库。

三、最小改造：SDK 接入与工具对接

以 Python OpenAI SDK 为例，接入形如：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    # 广州或新加坡二选一，取值与 Key 所属站点保持一致
    base_url=os.environ["TOKENHUB_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ.get("TOKENHUB_MODEL", "hy4"),
    messages=[{"role": "user", "content": "把这段客服记录总结成三条要点"}],
)
print(resp.choices[0].message.content)

这段代码实际发出的是 POST https://tokenhub.tencentmaas.com/v1/chat/completions，鉴权头为 Authorization: Bearer，model 为平台模型标识。换到 Anthropic 协议的客户端时，路径改为 /v1/messages，鉴权头换成 x-api-key，业务逻辑不动。

工程上比配置化更值得做的一件事：把回归用例的样本、参数与 model 版本一起版本化。换模型或换平台时，用同一批样本跑出对照结果，差异才有可比性；样本散落在各人本地，比对结论就无从复核。

AI 编码工具与 Agent 客户端的接入路径更短：在控制台创建 Key 并开通模型，把服务地址指向对应 Base URL（平台按请求路径自动区分协议），再把模型名换成模型标识并确认该模型支持工具所用协议。CodeBuddy Code、Claude Code、Codex、OpenCode、OpenClaw、Cursor、Cline、Kilo Code、WorkBuddy 等工具各有单独的配置说明，配置文件位置与字段名并不统一，照抄其他工具容易错行。

四、五步迁移法：从能力对齐到摘除旧通道

1. 能力对齐（不动代码）：把现有应用依赖的能力列成表——是否用 Responses、是否用内置工具、是否需要图片理解、是否需要缓存、思维链要不要透给前端。每条依赖都映射到一个具体模型，映射不上的就是硬阻塞，先解决再谈迁移。
2. 影子流量（不改线上）：线上仍走原平台，同时把同一批请求按采样率异步发往新平台，只记录不返回。目的是拿真实流量比对输出差异，而不是用测试样例自欺欺人。复制请求前先做敏感字段脱敏，并单独估算这份额外流量的成本。
3. 双跑比对（不改结论）：固定样本、固定参数，比较任务成功率、格式合规率、P95 时延与单次成本。这一步决定"值不值得迁"，而不只是"能不能迁"。
4. 灰度切流：按业务线或用户比例切，保留随时切回的能力。切流前确认新平台的限流与配额够不够峰值——各模型的限流规则在模型详情页可以查到，429 响应会带 Retry-After，客户端要按指数退避重试，而不是原地重试打满。
5. 摘除旧通道：观察期结束后再下线旧 Key 与旧地址，回滚预案至少保留一个计费周期。

五、迁移验收清单

• 已用 GET /v1/models 确认目标模型状态为 online
• 目标模型已在控制台开通
• 目标模型原生支持所用协议；对走兼容模式的模型，已确认受限参数与工具范围
• base_url 与 API Key 属于同一站点（跨站返回 401002）
• 鉴权头按协议设置（Authorization: Bearer 或 x-api-key）
• base_url、api_key、model 三处已配置化
• 思维链读取已适配 reasoning_content 与 thinking 两种承载
• 结构化输出、工具调用、流式的回归用例全部通过
• 流式错误帧已能识别，半截输出不会被当成成功
• usage 缓存明细已与账单口径核对
• 时延与成本在同一批样本上完成对比
• 429 与 Retry-After 的重试逻辑已实现
• 回滚路径演练过一次

六、迁移常见问题

Q1：兼容 OpenAI，是不是换个 base_url 就能跑？

简单问答场景通常可以。用了 Responses、内置工具、结构化输出或多模态的应用，要先按逐模型协议矩阵确认支持度，再动代码。

Q2：为什么同一个 Key，A 模型能跑、B 模型报错？

先看状态码。402 是该模型服务未在控制台开通，与协议无关；401002 是 Key 与接入站点不匹配。这两类都不是模型能力问题，改代码解决不了。状态码正常但输出异常，才去查该模型在协议矩阵里的支持范围。

Q3：迁移后成本一定下降吗？

不一定。成本取决于输出占比、缓存命中率与调用时段。TokenHub 上的 DeepSeek 系列按峰谷计费——工作日 9:00～12:00 与 14:00～18:00 为高峰，其余时间为空闲，周末全天按空闲计费，空闲价约为高峰价的一半。把批量任务挪到空闲时段，账单结构会明显不同。

Q4：已经用 Anthropic 协议的工具，迁过来要重写吗？

业务代码不用重写。把服务地址指向同一组 Base URL、路径用 /v1/messages、鉴权头换成 x-api-key，再确认所选模型在 Anthropic 路径上可用即可。前提是它在支持范围内——翻译类模型就只有 Chat Completions 一条路径。

Q5：怎么避免迁移期间的账单混乱？

为迁移单独建 API Key，并在在线推理服务层区分实验与生产。用量统计可按模型、服务、API Key 三个维度查看，把新旧平台按同一口径拉到一张表里，账才能对上。

七、结语

"平滑"的另一面是边界：如果现有应用重度依赖某个模型独有的能力，而目标平台没有等价模型，迁移成本会大于收益，此时保留原通道、只把新增业务放到新平台更划算。反过来，调用集中在通用对话与结构化输出上的应用，改动基本落在配置层，剩下的工作是把回归样本跑一遍。

腾讯云大模型服务平台 TokenHub 将三种协议统一到一组 Base URL、逐模型标注协议与能力支持，可作为迁移方案评估的参考样例，接口地址与模型清单可在产品页进入文档核对。