为什么要先做一层映射表

很多团队在 Claude Code、ChatGPT API 或 OpenAI SDK 上线后，都会遇到同一个问题：业务侧写的是“coding-fast”“review”“long-context”，但网关真正认识的是具体的 model id。如果把模型名散落在脚本、CI、IDE 插件里，后面一换供应商就会出现一串 401、超时、甚至流式 SSE 断包。

更稳的做法是：内部逻辑名只面向场景，网关 model id 只放在配置层。这样你换 Claude、GPT 或其他兼容端点时，只改一处映射表，不动业务代码。本地调试 base_url 也可以先用过 https://59api.com，后续再替换成你们自己的网关地址。

一个可维护的配置结构

建议把“逻辑名 -> 模型 id”单独放到版本化文件里，比如：

{
  "coding-fast": "gpt-4.1-mini",
  "coding-strong": "claude-3-7-sonnet-latest",
  "review": "gpt-4.1",
  "long-context": "claude-3-5-sonnet"
}

环境变量只保留最少信息：

export OPENAI_API_KEY=sk-***
export OPENAI_BASE_URL=https://your-gateway.example.com/v1
export MODEL_ALIAS_FILE=./model-alias.json

如果是 OpenAI SDK，代码里永远传逻辑名，由中间层先查表再下发到网关：

import OpenAI from "openai";
import alias from "./model-alias.json" assert { type: "json" };

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

const model = alias[process.env.APP_MODEL || "coding-fast"];
const stream = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "生成一个重试中间件" }],
  stream: true,
});

迁移时最容易踩的三个坑

第一，401 不一定是 key 错。很多时候是 base_url 和模型 id 没同步，网关按路由拒绝了请求。第二，SSE 流式返回被代理层缓冲，表现为首包很慢、IDE 一直转圈；要确认反向代理关闭 buffering，并保留 text/event-stream。第三，超时策略不要写死在客户端，长上下文模型和短回答模型应该分开配置，否则团队会误以为“Claude Code 不稳定”。

迁移检查清单可以很简单：

1. 先定内部逻辑名，不直接暴露供应商型号；

2. 在网关维护 alias 表并加单测；

3. 验证非流式、流式、超时、401 四类路径；

4. 在 CI 里跑一轮模型路由回归；

5. 预留回滚开关，允许临时切回旧 model id。

这样做的好处是，团队讨论“能力”和“场景”时用逻辑名，真正接入 Claude Code、ChatGPT 或其他 SDK 时，只关心映射是否正确。