OpenAI Node.js SDK 迁移指南：协议、重试与响应检查

修改 base URL 只是迁移的一步。SDK 方法、模型、请求字段和响应解析必须与目标路由一致。本篇提供迁移检查表和 Node.js 最小示例，不把 OpenAI SDK 的全部功能等同于每个模型都支持的能力。

先记录应用实际使用的契约

从真正发请求的代码填写下表，而不是只看客户端初始化配置。

检查项	迁移前记录	目标路由要核对什么
SDK 版本	锁文件中的 openai 精确版本	固定并测试该版本
调用方法	chat.completions.create 或 responses.create	是否支持对应端点
输入	消息或输入项、系统指令、附件	角色、媒体和可选字段是否合法
输出	文本、工具调用、结构化数据、结束状态	解析器能否处理原生响应
恢复	SDK 重试、应用重试、超时	合计尝试次数是否可控

通过模型发现接口取得公开模型 ID，再阅读对应模型指南。/v1/models 提供协议和已声明能力，不提供完整端点列表。协议标为 openai 不等于支持 Responses；端点区别见协议选择。

先发一次最小 Chat Completions 请求

在服务端项目安装 openai，提交生成的锁文件。把下面代码保存为 migration-check.mjs，在服务端环境设置 API_KEY 和 MODEL_ID；模型指南必须明确支持 Chat Completions。运行脚本会提交一次计费生成请求。

import OpenAI from 'openai';

const { API_KEY, MODEL_ID } = process.env;
if (!API_KEY || !MODEL_ID) throw new Error('Set API_KEY and MODEL_ID');
const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: 'https://newrouters.com/v1',
  maxRetries: 0,
  timeout: 60_000,
});
const response = await client.chat.completions.create({
  model: MODEL_ID,
  messages: [{ role: 'user', content: 'Explain HTTP in three short steps.' }],
  stream: false,
});
const choice = response.choices?.[0];
if (!choice) throw new Error('No completion choice returned');
console.log({
  text: choice.message.content,
  finishReason: choice.finish_reason,
  usage: response.usage,
});

客户端基础地址以 /v1 结尾，该 SDK 方法会追加 /chat/completions。不要把完整端点填入 baseURL，也不要重复追加 /v1。平台密钥只保存在服务端，只发给平台域名；不要为绕过配置错误而开启浏览器端 SDK 调用。

Node SDK 官方说明介绍了自动重试和超时设置，核对日期为 2026-11-03。本示例用 maxRetries: 0 关闭验证阶段的 SDK 自动重试。本地超时不能证明远端已停止或未产生用量，下一次尝试前先检查用量记录。

每次恢复一种高级功能

纯文本请求通过后，再依次恢复输出限制、流式响应、工具调用、结构化输出，以及所需的媒体输入。字段名称以选中模型为准，不假设采样和 token 限制参数可以互换。

切换到 Responses 时，应同时调整方法、请求体和解析器：Responses 的输出项不是 Chat Completions 的 choices[0]。同样，stream: true 返回事件流，不能沿用上面的完整 JSON 解析。先阅读流式响应指南。

工具调用仍需应用校验参数、确认操作权限、执行并回传结果；结构化输出也需要业务层校验。模型返回内容不代表工具已经执行，也不代表业务规则已经通过。

上生产前验证失败分支

用本地响应样例覆盖没有 choices、工具调用时文本为空、截断、拒答、格式错误和中断流。模拟网络失败，检查 SDK 与应用叠加后不会悄悄重复请求；不必为覆盖错误分支额外发起计费生成。

对获准的小样本实测，记录模型 ID、端点、SDK 版本、脱敏参数、结束状态与用量。用评估表对比业务验收结果，通过成本与用量指南核账。保留原有适配器，兼容性不通过时可以恢复应用配置。