2026 年 Node.js 大模型API接入 教程：请求封装与重试思路

2026 年 Node.js 大模型API接入 教程：请求封装与重试思路

Node.js 接大模型 API，第一版代码二十行就能跑通；难的是上线之后——超时、限流、偶发 5xx、连接被重置，都会让一个本来正常的接口变得不稳定。

这篇教程按“先跑通、再跑稳”的顺序讲三件事：配置怎么准备、请求怎么封装、重试怎么写才安全。示例基于 OpenAI 兼容的 Chat Completions 结构，字段名称请以你所使用平台的控制台说明为准。

代码使用 Node.js 18 以上内置的 fetch 与 AbortSignal，不引入额外依赖，方便直接复制后改成项目里的风格。

接入前要准备的配置项

API Key、Base URL 与模型名称

三者缺一不可，而且都要从控制台复制，不要靠记忆或从旧的配置文件里翻。Base URL 决定请求发到哪里，模型名称决定实际调用哪个模型，API Key 决定身份与额度归属。任何一项写错，返回的错误信息往往都不够直观。

请求封装：把重复逻辑收进一个模块

不要在业务代码里到处写 fetch。抽一个客户端模块，把地址拼接、鉴权头、超时与错误抛出统一处理，后面加日志、加埋点、换模型都只改一个地方。

一个最小可用的客户端

const createClient = (config) => async (messages) => {
  const res = await fetch(`${config.baseUrl}/chat/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${config.apiKey}`,
    },
    body: JSON.stringify({
      model: config.model,
      messages,
      temperature: config.temperature ?? 0.7,
    }),
    signal: AbortSignal.timeout(config.timeoutMs ?? 30000),
  });

  if (!res.ok) {
    const detail = await res.text();
    const err = new Error(`HTTP ${res.status}: ${detail.slice(0, 200)}`);
    err.status = res.status;
    throw err;
  }
  return res.json();
};

这段代码有两个关键点：一是用 AbortSignal.timeout 主动结束挂起请求，二是把 HTTP 状态码挂在错误对象上，方便后续判断是否值得重试。至于路径到底是 /v1/chat/completions 还是别的写法，一定以控制台给出的 Base URL 与接口文档为准。

把模型与超时放进配置对象

模型名称、温度、超时这些值建议集中在配置文件里，不要散落在业务逻辑中。这样切模型时只改一行，也方便针对不同场景设置不同超时：短问答 20 秒通常够用，长文生成可能需要 60 秒以上。同时建议在客户端里预留一个 requestId，方便把日志串起来排查。

重试逻辑：哪些错误该重试

先分类，再决定重试

重试不是万能药。对请求格式错误、鉴权失败、模型名不存在这类问题重试一百次也不会成功，反而放大日志噪音和额度消耗。

• 可以重试：408、409、425、429、500、502、503、504，以及连接超时、读取超时等网络类错误。
• 不要重试：400、401、403、404、422，这类通常是参数、鉴权或模型名写错导致的。
• 谨慎处理：429 通常需要配合更长的等待时间，或者先降低并发，而不是立刻重发。

指数退避加随机抖动

const RETRYABLE = new Set([408, 409, 425, 429, 500, 502, 503, 504]);

async function withRetry(task, { retries = 3, baseDelay = 500 } = {}) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await task();
    } catch (err) {
      const canRetry = err.name === 'TimeoutError' || RETRYABLE.has(err.status);
      if (!canRetry || attempt >= retries) throw err;
      const backoff = baseDelay * 2 ** attempt;
      const jitter = Math.random() * baseDelay;
      await new Promise((r) => setTimeout(r, backoff + jitter));
    }
  }
}

退避让每次等待时间翻倍，抖动则避免多个实例在同一时刻集中重发。需要特别注意：流式输出场景下，如果已经向客户端推送了部分内容，直接重试会造成重复文本，应结合业务决定是否允许重试，或者只在连接建立阶段重试。

重试的目标是掩盖偶发故障，而不是掩盖配置错误。如果一个请求连续三次都失败，优先去看错误内容，而不是把重试次数继续调大。

上线前建议完成的几项检查

• 把 API Key 放进环境变量，确认不会被打进构建产物或提交到仓库。
• 在日志里记录耗时、状态码与模型名称，但不要记录完整的 API Key 和用户原文。
• 为并发设置上限，避免批量任务同时打满从而触发限流。
• 用一条真实业务请求做端到端测试，而不是只发一句 “hello” 就算测通。

多模型切换：用通联AI中转站统一入口

当项目里需要按任务选择不同模型时，最大的成本其实是配置管理：多套地址、多个 Key、多份额度。通联AI中转站 这类 AI 聚合平台提供 OpenAI 兼容的接入方向，用统一的 Base URL 与 API Key 管理多个模型的调用，迁移时通常只需要替换地址、Key 和模型名称三个变量，前面封装好的客户端几乎不用动。

建议的顺序是：先在 通联官网 注册账号并获取 API Key，从控制台复制 Base URL 与模型名称，用上面的客户端跑一次非流式请求，确认返回格式符合预期后，再补上流式处理与重试逻辑。具体的接口地址、可选模型与计费方式，以控制台实时展示的信息为准。

如果你准备把上面这套封装落到真实项目里，可以先去通联注册账号，在控制台拿到 API Key 与 Base URL，选一个模型完成第一次请求测试，再逐步加上超时、退避与日志。

注册通联AI中转站并获取 API Key