只改 base_url 不够：迁到聚合站时环境变量、模型别名与客户端默认值要一起动

为什么只改 base_url 会「看起来能跑，实际出问题」

很多聚合站的接口形态与 OpenAI 兼容，所以把 base_url 指向新网关后，第一次 curl 常常是成功的。于是迁移被判定为完成。

但真实项目里，请求能不能发出去只是第一层。后续出问题的地方多集中在三处：读不到 key、模型名对不上、以及旧客户端带着一套为别家服务调优过的超时与重试策略。它们的共同特点是失败不总是报错，有时表现为延迟、偶发 5xx、或悄悄降级到某个兜底模型。

第一类：API key 的环境变量名与加载路径

变量名往往被硬编码在默认约定里

多数 SDK 默认读取特定名称的环境变量（OpenAI 系常见 OPENAIAPIKEY）。如果你只是把 base_url 换掉、key 换成聚合站签发的，但变量名没改，代码在本地可能靠 .env 里的旧值跑通，一上 CI 或容器就变成空 key。

建议做法：

• 为聚合站单独定义一个变量名，例如 AGGREGATORAPIKEY，而不是复用原厂商的名字。这样两套配置可以并存，回滚成本低。
• 在初始化客户端时显式传入 key，而不是依赖 SDK 的隐式读取。显式传参让「key 从哪来」在代码里可追溯。
• 检查 .env、.env.example、容器编排文件、CI secrets、以及本地 shell profile 四个位置，旧变量名容易残留在其中之一。

注意加载顺序与覆盖关系

不少框架的配置是「环境变量 > 配置文件 > 代码默认值」。迁移时如果把新 key 写进配置文件，而环境里还留着旧变量，实际生效的可能不是你预期的那一个。排查空 key 或 401 时，先打印一次实际使用的 base_url 与 key 前缀（不要打印全量 key），比读代码更快。

一个 key 调多模型，权限校验逻辑要重审

聚合站的特点是一个 key 可访问多个厂商的模型。如果代码里存在「按 key 前缀判断可调用哪些模型」之类的逻辑，这部分假设已经不成立，需要改成基于模型标识的白名单或配置驱动。

第二类：模型 slug 的映射与别名

同一模型在不同渠道的标识不一致

各家厂商的模型标识写法不同，聚合站通常会定义自己的一套模型标识。迁移时要做的不是「把 A 换成 B」这一件事，而是建立一张映射表：

• 业务代码里使用的逻辑名（如 chat-default、chat-cheap、reasoning）。
• 聚合站实际接受的模型标识。
• 该逻辑名对应的用途、上下文需求和降级备选。

把逻辑名和物理模型标识解耦，好处是以后换模型只改映射表一处，不用全仓库搜索替换。

别名不要写死在多处

常见反模式是模型名散落在提示词模板、测试用例、前端下拉框、以及定时任务脚本里。建议收敛为一个常量文件或配置项，并在启动时做一次校验：向聚合站发一个最小的探测请求，确认所有配置的模型标识都存在。这样模型下线或改名会在部署阶段暴露，而不是在用户请求时。

别让兜底逻辑掩盖映射错误

有些客户端在模型不存在时会自动回退到默认模型。这在迁移期很危险：你以为在测新模型，实际跑的是兜底模型，评测数据全废。迁移期间建议临时关闭自动兜底，让错误直接抛出，确认映射正确后再打开。

第三类：旧客户端遗留的重试、超时与并发默认值

超时是按旧服务的响应特征调的

如果旧配置把读超时设得很短，是因为原服务首 token 快；换到新网关后，不同厂商、不同模型的响应特征差异更大，短超时会集中出现超时错误。反过来，超时设得过长会让故障请求长期占用连接。建议按用途分层设置，而不是全局一个值。

重试策略要区分可重试与不可重试

旧客户端常见的默认是「5xx 和超时都重试固定次数」。迁移后需要确认：

• 对 4xx（鉴权失败、模型不存在、参数错误）不应重试，重试只会放大无效流量。
• 对限流类错误应采用退避而非固定间隔。
• 流式请求中途断开是否重试，要有明确决定，不能沿用非流式的默认。
• 重试次数与总超时要联动，否则外层超时先触发，重试形同虚设。

并发与连接池

旧客户端可能配了较大的连接池或较高的并发上限，是配合单一上游的容量。换到聚合站后，实际并发会分散到多个上游模型，本地连接池设置过小反而成为瓶颈，过大则在限流时制造排队。建议先观察一段时间的实际并发与错误分布，再调参，不要一次性按旧值照搬。

一次可回归的迁移检查清单

把上面三类合并成可执行的步骤：

1. 定义新的 key 环境变量名，更新所有部署位置，并显式传入客户端。
2. 建立逻辑名到聚合站模型标识的映射表，收敛到单一配置源。
3. 启动时做模型存在性探测，迁移期关闭自动兜底。
4. 按用途分层设置超时；区分可重试与不可重试错误；重试与总超时联动。
5. 观察实际并发后再调整连接池与并发上限。
6. 用一组固定的回归请求（含流式与非流式、含一个预期失败的鉴权请求）验证配置确实生效。

第 6 步最容易被跳过，但它能把「看起来能跑」和「确实配好了」区分开。

计费侧的一个提醒

迁移后成本口径也会变。在该聚合站上，用户按官方价 ×1.3 扣费；贡献 key 的一方按官方价 ×1.1（优质 key ×1.2）返 USDC。这意味着即使模型标识和调用方式都正确，同一份请求的账面成本与直连官方并不相同。做容量规划和预算告警时，阈值要按新的计费口径重设，不要沿用旧的单价假设。