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

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

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

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

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

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

## 先发一次最小 Chat Completions 请求

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

```javascript
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 官方说明](https://github.com/openai/openai-node#retries)介绍了自动重试和超时设置，核对日期为 2026-11-03。本示例用 `maxRetries: 0` 关闭验证阶段的 SDK 自动重试。本地超时不能证明远端已停止或未产生用量，下一次尝试前先检查用量记录。

## 每次恢复一种高级功能

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

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

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

## 上生产前验证失败分支

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

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