从六个厂商各自直连改成一把聚合站 base URL：迁移清单怎么列

先想清楚：迁移的到底是什么

从多厂商直连换到聚合站，核心变化只有两件事：base URL（请求地址） 和 API key（鉴权凭证）；模型名、消息结构、流式响应格式这些都没有变。真正的工作量在于：梳理哪个 SDK 在用哪个地址，以及切换后如何验证行为等价。

先明确三个不变项，能减少很多顾虑：

• 模型标识不变：请求体里写的模型名仍由聚合站按厂商路由，不需要换写法。
• 请求语义不变：messages 结构、system 角色、temperature、max_tokens、tool 定义等参数语义沿用对应厂商协议。
• 流式协议不变：SSE 分片格式与结束标记仍按协议返回，前端解析逻辑一般不用改。

变的是鉴权头和地址拼接方式。列清单就从这里开始。

第一步：盘点调用点，按厂商分类

别急着改代码，先做一张表。对每个会发 LLM 请求的服务，记录以下字段：

• 服务名、语言、部署位置
• 使用的 SDK 或 HTTP 客户端（官方 SDK / OpenAI 兼容客户端 / 自封装）
• 当前 base URL 与 key 的环境变量名
• 当前调用的模型名列表
• 是否流式、是否用 tool calling、是否多模态
• 是否有重试、超时、并发限制等本地策略

分类的关键是协议族而非厂商名。Claude 走 Anthropic Messages 协议；GPT、DeepSeek、Qwen、GLM、Kimi 多数提供 OpenAI 兼容接口。这些调用在聚合站里可以共用同一个 base URL 和同一把 key；Anthropic 协议调用则走同一个 base URL、但路径和鉴权头按 Anthropic 规范来。具体路径和 header 名请以文档站当前的接入说明为准。

盘点完，你会得到两类调用点：

1. 可收敛的：原本 base URL 只差一个域名、key 只是不同的环境变量，改配置即可。
2. 需要适配的：自己拼 URL、自己加厂商专属 header、或是用了非标准参数。这类要逐个确认聚合站是否透传。

第二步：按厂商拆迁移步骤

Anthropic（Claude）

• 保留 Anthropic 官方 SDK，只把 base URL 指向聚合站，key 换成聚合站的 key。
• 检查是否有代码手动设置 anthropic-version 等 header；官方 SDK 会自动带，自封装客户端要确认。
• 如果项目同时用了 OpenAI 兼容客户端调 Claude，就把那条路径合并到 Anthropic 协议路径，避免同一模型两套代码。

OpenAI（GPT）

• 官方 SDK 支持自定义 base URL，改环境变量即可，key 换成聚合站的 key。
• 注意区分 base URL 是否需要带版本段；OpenAI SDK 通常会在末尾拼接路径，配置时不要重复。
• 用了 Azure 风格 endpoint 的代码要单独处理，那条路径的参数结构不同。

DeepSeek、Qwen、GLM、Kimi

这四家多数以 OpenAI 兼容接口接入，收敛成本最低：

• 把四套 base URL 与 key 环境变量合并成一套，模型名照旧写。
• 逐个确认各家专有参数（如思考模式开关、特定采样参数）是否仍然透传；不确定时先在小流量上试。
• 如果代码里有按厂商名分支的逻辑（比如 if provider == "qwen"），迁移后这类分支应退化为纯模型名判断。

第三步：配置收敛的落地方式

推荐把配置抽成两层：

• 全局层：一个聚合站 base URL、一把 key，由部署环境注入，不进代码库。
• 模型层：模型名与用途的映射表（比如“摘要用哪个、代码用哪个”），便于后续只换模型不换代码。

要点：

• key 走密钥管理或环境变量，禁止写进仓库与日志。
• 保留旧配置一段时间，用开关控制走新地址还是旧地址，便于回滚。
• 记录每个服务的切换时间点，后面验证要对得上。

第四步：逐个模型验证行为等价

一个模型一个模型切，切完就跑验证，不要一次性全量。每个模型至少验证四类：

1. 非流式基本调用：同一提示词、同一参数，对比输出结构（字段齐全、finish reason 合理），不要求逐字相同。
2. 流式输出：分片能正常到达、结束标记正确、前端渲染不中断。
3. tool calling / 结构化输出：函数名、参数 JSON 可解析，多轮工具往返能走通。
4. 异常路径：无效 key、超长输入、未知模型名的报错信息能否被现有错误处理识别。

验证方式建议用固定的评测集：准备一组代表性提示词，记录旧地址下的基线输出，切新地址后跑同一组，人工或脚本比对关键差异。重点关注：截断、拒答模式、JSON 解析失败率。

第五步：切换顺序与观察期

建议按风险从低到高排：

• 先切非关键路径（内部工具、离线批处理）。
• 再切读多写少的路径（摘要、分类、检索增强的改写）。
• 最后切用户直接面对的核心路径（对话、代码生成）。

每个阶段留观察期，盯这几个指标：错误率、超时率、平均延迟、token 用量变化、结构化输出解析失败率。用量变化要能解释：计费口径变了，账单数字和直连时不可直接对比，看的是用量趋势而非面额。

第六步：长期回归项

迁移不是一次性动作，把下面几项加入常规检查：

• 模型名弃用：厂商下线旧模型时，映射表要跟着改。
• 参数兼容：厂商新增参数后，确认聚合路径是否透传。
• key 与额度：聚合站余额、限流策略与直连不同，监控告警要重新设。
• 回滚预案：保留旧直连配置与 key 一段时间，出问题能单服务切回。

清单模板（可直接复制）

• [ ] 盘点所有调用点，填完字段表
• [ ] 按协议族把调用点分成“可收敛 / 需适配”两类
• [ ] 生成聚合站 key，写入密钥管理
• [ ] 建立模型名映射表
• [ ] 改造配置层，加新旧地址开关
• [ ] 按厂商逐条改 base URL 与 key
• [ ] 每个模型跑四项验证
• [ ] 按风险顺序分批切换并留观察期
• [ ] 更新监控与告警阈值
• [ ] 文档记录切换时间与回滚步骤

把这张清单当作迁移的骨架，逐项打勾，比“一次性全量替换再debug”稳得多。