换一家大模型 API，除了 base_url 还要改什么？迁移自查清单
事实依据为 2026-08-24 抓取的各厂商官方文档。文中不写具体单价与限速阈值，请以官方页面为准。
几家厂商的官方文档都写着类似的话：兼容 OpenAI 接口规范，只需要调整 API Key、base_url 和模型名称，就能把现有代码迁过来。这句话是真的——但它描述的是「调通」，不是「迁完」。
调通只需要十分钟。真正花时间的是后面那些兼容层不管的东西：你的专有参数挂在哪一层、用量字段叫什么名字、限流换成了哪把尺子、缓存要不要你手动开、429 到底是谁的问题、以及成本模型是不是整个变了。
兼容层到底覆盖了什么
先把好消息说清楚，这样才知道剩下的坏消息有多大。
几家的官方表述是一致的：Kimi 的 API 概述页写明在请求和响应格式上兼容 OpenAI 的 Chat Completions API，可以直接用 OpenAI 官方 SDK，也支持大多数兼容 OpenAI 的第三方工具和框架，只需把 base_url 指过来；阿里云百炼的说明是兼容 OpenAI 接口规范，调整 Key、base_url 和模型名即可迁移；智谱的文档里分别有 OpenAI 兼容和 Claude 兼容两份接入说明；DeepSeek 更进一步，直接给了两个服务地址，一个是 OpenAI 格式，一个是 Anthropic 格式。
**所以「调用能不能通」几乎不再是迁移的风险点。**兼容层稳定覆盖的是最常用的对话补全接口、消息结构、流式输出这几样。兼容边界本身的讨论，见OpenAI 兼容端点是什么。
下面六项是兼容层不覆盖的，也就是迁移真正的工作量。
一、专有参数的挂载位置会变
各家的独有能力没法塞进 OpenAI 的标准字段里，于是都被放到了非标准的位置——而且各家放的位置还不一样。
官方文档里能直接查到的几个例子：Kimi 的 thinking 参数需要通过 SDK 的 extra_body 传递，而 partial 不是顶层请求参数，它是写在 messages 里那条 assistant 消息上的字段；DeepSeek 的 user_id 参数在用 OpenAI SDK 时要放进 extra_body，而在用 Anthropic SDK 时则要放进 metadata——同一个参数，换个 SDK 就换个位置。
迁移动作：把你现在用到的每一个非标准参数列出来，逐个到新厂商文档里确认三件事——有没有对应能力、参数叫什么名字、挂在请求的哪一层。没有对应能力的那些，是要改业务逻辑的，不是改配置。
二、用量字段名会变，对账会断
这条最容易被漏掉，因为它不报错——它只是让你的成本统计悄悄归零。
以缓存相关的字段为例，各家官方文档里的写法就有三套：DeepSeek 在 usage 里给的是 prompt_cache_hit_tokens 和 prompt_cache_miss_tokens；智谱两个文档站给的都是 usage.prompt_tokens_details.cached_tokens；阿里云百炼在 OpenAI 兼容协议下是 prompt_tokens_details.cached_tokens，但在 Anthropic 兼容协议下变成了 cache_read_input_tokens；聚合层这边，OpenRouter 在 prompt_tokens_details 里同时给 cached_tokens 和 cache_write_tokens，另外还有一个直接告诉你省了多少的折扣字段。
迁移动作：**在封装层里显式做字段映射，并且给每个字段加一条「读不到就告警」的兜底。**否则迁移之后你的缓存命中率图表会变成一条零线，而你要过很久才会发现那不是缓存失效，是字段名换了。各家缓存口径的完整对比见大模型 API 的缓存计费差在哪。
三、限流换了一把尺子
这是迁移后最常见的线上事故来源：老厂商只卡并发，新厂商同时卡并发、每分钟请求数、每分钟 token 数和每天 token 数；或者老厂商按账号算，新厂商按主账号把所有子账号和 Key 合并算。
还有一个隐性变化是提额路径不同：有的按累计充值分层、有的按积分等级、有的按月消费自动调整、有的要提工单等审核。如果新厂商的提额需要审核周期，这段时间必须算进迁移排期，不能等切流量那天才发现额度不够还得等几个工作日。
迁移动作：把新厂商限速页上列出的每一个口径抄下来，逐个对照你现在的流量特征估算；把并发池、队列、退避策略按新口径重配，而不是照搬旧配置。各家口径差异见各家大模型 API 的限流口径为什么不一样。
四、缓存可能从自动变成手动，或者反过来
如果老厂商的缓存是全自动的，你的代码里一行相关逻辑都没有；换到一个以显式缓存为主的厂商，你不加标记就等于完全没有缓存——功能全对，账单翻倍。
反过来也一样：从显式缓存迁到自动缓存的平台，你原来精心放置的标记可能被忽略，也可能触发另一套规则。还有一层是命中判定规则本身不同，有的要求完整匹配一整个前缀单元，有的从标记位往前回溯有限个内容块，有的按断点哈希。同一份 prompt 结构，在 A 家命中率很高，搬到 B 家可能一次都不命中。
迁移动作：迁移后的第一周，把缓存命中率当成核心指标盯着，而不是等月底看账单。
五、错误码的语义变了
HTTP 状态码是一样的，语义不一样。
智谱的文档把 429 之下的情况细分成了两类：一类是账户触发了自身的速率限制，处理方式是降并发、加队列、提等级；另一类是平台服务过载，官方明确说明这与单一账户的调用行为无直接关系，只能退避重试或降级。这两类的处理方式相反，用同一套重试逻辑对付会出问题。
Kimi 那边则有一条特别的规则：当系统检测到账户存在异常行为时会触发风控限速策略，一旦触发即无法解除。走聚合层的话还要再分一层，OpenRouter 的文档说明 429 可能来自平台自身的限制，也可能来自上游供应商，同时它把余额不足和「没有符合路由要求的可用供应商」分别给了不同的状态码。
迁移动作：把新厂商的错误码表通读一遍，重写重试与降级的判断分支。照搬旧的重试逻辑是迁移事故里最典型的一种。
六、成本模型可能整个换了形态
这条决定了迁移到底值不值。
计价形态本身就有好几种：有的按单次请求的输入长度分阶梯，而且跨档时整次请求全部按更贵的档位重算；有的在标称窗口内全程一个价；有的按调用时段分高峰和空闲两档；有的把缓存存储单列成独立的价格位。
**这意味着「新厂商单价更低」完全可能得出错误结论。**如果你的请求长度经常越过新厂商的档位临界点，或者你的负载集中在它的高峰时段，实际账单可能不降反升。
迁移动作：**别比单价，比同一个任务的总账。**拿你自己的真实请求样本（输入长度分布、调用时间分布、前缀复用率）分别代入两家的计价规则算一遍。各家的价格档位对照见国产大模型 API 价格对比。
还有几件小事，但都会咬人
- 模型 ID 和版本节奏不同。 有的厂商给带日期的快照 ID 和一个指向最新版的别名，有的会发布迁移指引文档，有的会预告老系列的下线时间点。迁移时优先选带明确版本标识的 ID，别用会自己变的别名，否则某天模型行为变了你都不知道是什么时候变的。
- 自研 HTTP 解析要重新验。 DeepSeek 的文档专门说明了请求保活机制——非流式请求会持续返回空行，流式请求会持续返回 SSE 的 keep-alive 注释，并提醒自己解析响应的用户要处理这些内容；同时超过一段时间未开始推理时服务端会关闭连接。用官方 SDK 一般感知不到，自己拼 HTTP 的就要单独测。
- Key 和地域体系是分开的。 如果新厂商分地域，各地域的接入点和 Key 都不通用，这不是一个环境变量能覆盖的事。
- token 换算比例不同。 同一段中文在不同厂商的分词结果不一样，官方文档通常只给一个大致区间，有的平台提供了专门的 token 计算接口。迁移前后的 token 数不可比，成本对比要用同一批样本分别实算。
一张可以照着打勾的迁移清单
| 检查项 | 判断标准 |
|---|---|
| 专有参数 | 每一个非标准参数都确认了新厂商的名称与挂载层级 |
| 用量字段 | 做了显式映射，读不到时会告警 |
| 限流口径 | 抄下了新厂商的全部口径，并按其重配并发与退避 |
| 提额周期 | 确认了提额路径，并把审核周期算进了排期 |
| 缓存模式 | 确认了是自动还是显式，命中率有监控 |
| 错误码 | 重写了重试与降级分支，能区分自身限流与平台过载 |
| 计价形态 | 用自己的样本分别实算了总账，不是比单价 |
| 模型版本 | 用了带明确版本标识的 ID，查过下线预告 |
| 流式解析 | 自研解析的场景单独验过保活与超时行为 |
| 回退方案 | 出问题时能切回原厂商，且切回的路径演练过 |
迁移的节奏
比清单更重要的是顺序。比较稳的做法是四步：
**第一步，影子流量。**把线上请求复制一份发给新厂商，不使用其返回结果，只用来采集 token 用量、延迟、错误率和缓存命中率。这一步能在零风险的前提下拿到真实数据。
**第二步，小比例切流。**从很小的比例开始，重点观察限流表现——因为新账户往往处在最低等级档，而额度提升需要时间累积。
**第三步，双跑对账。**两边的账单各自核对一个完整周期，验证你的成本模型算对了。
**第四步，保留回退路径。**在完全切换后的一段时间内，保持随时能切回去的能力。这就要求你的封装层里模型和厂商是配置项而不是硬编码——这也是为什么建议从一开始就做这层抽象。
最后提醒一句：**迁移成本本身也是选型的一部分。**在决定接入某一家之前，先想一遍「以后要走的话得改多少东西」，会让你更愿意把差异显式建模，而不是图省事把厂商特性写进业务代码里。
核实边界
- 本文依据 2026-08-24 的抓取，逐字核到正文的官方页面包括：Kimi 开放平台的 API 概述页与充值限速页、DeepSeek 的限速与隔离文档和模型价格页、智谱开放平台的速率限制文档与 OpenAI/Claude 兼容说明、阿里云百炼的产品说明页与计费文档、OpenRouter 的提示缓存文档与 Limits 文档。
- 未核到的厂商：火山方舟（豆包）官方文档站为前端渲染，正文未逐字核到，未纳入本文；OpenAI 官方文档站本次网络不可达，文中不含 OpenAI 官方口径的表述。
- 本文没有写任何具体单价、限速阈值、缓存折扣比例和档位边界。这些参数变动频繁，正文一律改写为机制描述。
- 文中的迁移清单与四步节奏属于工程实践建议，不是厂商官方推荐；笔者没有上述厂商的付费账号，也没有实际执行过这几家之间的迁移，相关判断来自官方文档中列明的差异点。