同时接 OpenAI、Claude、Gemini、DeepSeek、通义、Grok、MiniMax、Kimi 这些 API 之后，我踩了不少坑。这篇把最费时间的几个问题和对应的兼容方案整理出来，希望能帮你少绕路。

坑一：协议不统一，用户经常填错

大模型 API 目前主要是两套协议：

• OpenAI 兼容：POST /v1/chat/completions，鉴权 Authorization: Bearer sk-xxx
• Anthropic 原生：POST /v1/messages，鉴权 x-api-key: xxx，还得带 anthropic-version: 2023-06-01

问题是，很多人（尤其用中转地址时）根本分不清自己手里的接口是哪套协议，强制让用户选就很劝退。

我的做法是自动探测：按优先级先试一种协议，失败再试另一种，谁先返回合法结构就用谁。

async function detectProtocol(baseUrl: string, apiKey: string, model: string) {
  const order = ["anthropic", "openai"] as const;
  let last = null;
  for (const proto of order) {
    const probe = await chat(baseUrl, apiKey, proto, {
      model, userText: "ping", maxTokens: 8, temperature: 0,
    });
    // 返回体里有内容或 model 字段，才算这条协议探测成功
    if (probe.ok && (probe.contentText || probe.modelField)) {
      return { protocol: proto, probe };
    }
    last = probe;
  }
  return { protocol: "anthropic", probe: last }; // 都失败，返回最后一次用于报错
}

体验立刻好很多——用户只管填地址和 Key，协议我们自己判。

坑二：baseUrl 用户填法五花八门

用户填的 baseUrl 可能是 https://x.com、https://x.com/v1、https://x.com/v1/chat/completions……直接拼接必然出错。得做容错归一化：

function buildEndpoint(baseUrl: string, protocol: "anthropic" | "openai") {
  const b = baseUrl.trim().replace(/\/+$/, ""); // 去尾部斜杠
  if (protocol === "anthropic") {
    if (/\/messages$/.test(b)) return b;
    if (/\/v1$/.test(b)) return b + "/messages";
    return b + "/v1/messages";
  }
  if (/\/chat\/completions$/.test(b)) return b;
  if (/\/v1$/.test(b)) return b + "/chat/completions";
  return b + "/v1/chat/completions";
}

核心思路：先判断用户已经填到哪一层，再补齐剩下的路径，而不是无脑拼接。

坑三：temperature 参数会把正常端点误判为失败

这个坑很隐蔽。OpenAI 的 o1/o3 推理系列、以及部分新模型/中转，不接受 temperature 参数，你传了反而报错。

如果你把这种报错当成「Key 无效」或「接口不通」，就冤枉了一条本来正常的端点。正确做法是识别到 temperature 相关报错，去掉该参数重试一次：

async function chat(baseUrl, apiKey, protocol, params) {
  const res = await attemptChat(baseUrl, apiKey, protocol, params);
  if (!res.ok &&
      params.temperature !== undefined &&
      /temperature/i.test(res.errorMessage || "")) {
    // 因 temperature 被拒，去掉参数重试
    return attemptChat(baseUrl, apiKey, protocol, { ...params, temperature: undefined });
  }
  return res;
}

坑四：网络层报错直接抛给用户，没人看得懂

ENOTFOUND、ECONNREFUSED、ETIMEDOUT、CERT_HAS_EXPIRED……这些底层 code 丢给用户等于没说。统一翻译成人话，排查效率天差地别：

function friendlyNetworkError(e) {
  if (e?.name === "AbortError") return "请求超时（超过 45 秒无响应）";
  const code = e?.cause?.code || "";
  const raw = (e?.cause?.message || e?.message || "").toLowerCase();
  if (code === "ENOTFOUND" || raw.includes("getaddrinfo")) return "域名无法解析（接口地址不存在或拼写错误）";
  if (code === "ECONNREFUSED") return "连接被拒绝（目标服务未开放或端口错误）";
  if (code === "ETIMEDOUT") return "连接超时（目标服务无响应）";
  if (code === "ECONNRESET") return "连接被重置（目标服务异常断开）";
  if (raw.includes("certificate") || raw.includes("self-signed")) return "SSL 证书错误（证书无效或不受信任）";
  return e?.message ? `连接失败：${e.message}` : "网络请求失败，请检查接口地址与网络";
}

坑五：响应结构要归一化，否则上层逻辑写到崩溃

OpenAI 把内容放在 choices[0].message.content，Anthropic 放在 content[] 里 type==="text" 的项；用量字段一个叫 prompt_tokens/completion_tokens，一个叫 input_tokens/output_tokens。如果上层直接读原始结构，每加一家就得改一遍。

解法是加一层归一化，把各家响应统一成同一个内部结构（contentText、modelField、usage.input/output、stopReason 等），上层只认这层，加新厂商只需写一个 parser。

小结

对接多家大模型 API，真正费时间的不是「发请求」，而是这些兼容性细节：协议探测、baseUrl 容错、参数兼容、错误翻译、响应归一化。

后来我把这套逻辑做成了一个在线小工具 TokenLens，填接口地址 + Key + 选模型，就能自动跑完上面这些检测并给出结果，省得每次手动测。如果你也在做多模型对接，可以拿它验证端点，或者直接参考上面的思路自己实现。

你在联调大模型 API 时还踩过哪些坑？欢迎评论区交流。