openai/openai-node 来源：https://github.com/openai/openai-node # OpenAI TypeScript 和 JavaScript API 库 npm 捆绑包大小 JSR 版本 (https://jsr.io/@openai/openai) 该库提供了从 TypeScript 或 JavaScript 便捷访问 OpenAI REST API 的功能。它是基于我们的 OpenAPI 规范 (https://github.com/openai/openai-openapi) 并使用 Stainless (https://stainlessapi.com/) 生成的。要了解如何使用 OpenAI API，请查阅我们的 API 参考文档 (https://platform.openai.com/docs/api-reference) 和官方文档 (https://platform.openai.com/docs)。 ## 安装 sh npm install openai ### 从 JSR 安装 sh deno add jsr:@openai/openai npx jsr add @openai/openai 这些命令将使模块可以从 @openai/openai 作用域导入。如果你使用的是 Deno JavaScript 运行时，也可以直接从 JSR (https://jsr.io/docs/using-packages#importing-with-jsr-specifiers) 导入，而无需执行安装步骤： ts import OpenAI from 'jsr:@openai/openai'; ## 使用 该库的完整 API 可以在 api.md 文件 中找到，其中包含大量代码示例 (https://github.com/openai/openai-node/tree/master/examples)。与 OpenAI 模型交互的主要 API 是 Responses API (https://platform.openai.com/docs/api-reference/responses)。你可以使用以下代码从模型生成文本。 ts import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // 这是默认设置，可以省略 }); const response = await client.responses.create({ model: 'gpt-5.2', instructions: '你是一个说话像海盗的编程助手', input: 'JavaScript 中的分号是可选的吗？', }); console.log(response.output_text); 之前用于生成文本的标准（将无限期支持）是 Chat Completions API (https://platform.openai.com/docs/api-reference/chat)。你可以使用该 API 通过以下代码从模型生成文本。 ts import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // 这是默认设置，可以省略 }); const completion = await client.chat.completions.create({ model: 'gpt-5.2', messages: [ { role: 'developer', content: '说话像海盗。' }, { role: 'user', content: 'JavaScript 中的分号是可选的吗？' }, ], }); console.log(completion.choices[0].message.content); ## 工作负载身份认证 对于像云托管 Kubernetes、Azure 和 GCP 这样安全且自动化的环境，你可以使用工作负载身份认证，利用云身份提供商提供的短期令牌，而不是长期有效的 API 密钥。workloadIdentity 参数与 apiKey 互斥。 ### Kubernetes（服务账户令牌） ts import OpenAI from 'openai'; import { k8sServiceAccountTokenProvider } from 'openai/auth'; const client = new OpenAI({ workloadIdentity: { clientId: 'your-client-id', identityProviderId: 'idp-123', serviceAccountId: 'sa-456', provider: k8sServiceAccountTokenProvider('/var/run/secrets/kubernetes.io/serviceaccount/token'), }, }); const response = await client.chat.completions.create({ model: 'gpt-4', messages: [{ role: 'user', content: '你好！' }], }); ### Azure（托管身份） ts import OpenAI from 'openai'; import { azureManagedIdentityTokenProvider } from 'openai/auth'; const client = new OpenAI({ workloadIdentity: { clientId: 'your-client-id', identityProviderId: 'idp-123', serviceAccountId: 'sa-456', provider: azureManagedIdentityTokenProvider(), }, }); ### GCP（计算引擎元数据） ts import OpenAI from 'openai'; import { gcpIDTokenProvider } from 'openai/auth'; const client = new OpenAI({ workloadIdentity: { clientId: 'your-client-id', identityProviderId: 'idp-123', serviceAccountId: 'sa-456', provider: gcpIDTokenProvider(), }, }); ### 自定义主体令牌提供程序 ts import OpenAI from 'openai'; const client = new OpenAI({ workloadIdentity: { clientId: 'your-client-id', identityProviderId: 'idp-123', serviceAccountId: 'sa-456', provider: { tokenType: 'jwt', getToken: async () => { return 'your-jwt-token'; }, }, }, }); 你还可以自定义令牌刷新缓冲期（默认值为过期前 1200 秒（20 分钟））： ts import OpenAI from 'openai'; import { k8sServiceAccountTokenProvider } from 'openai/auth'; const client = new OpenAI({ workloadIdentity: { clientId: 'your-client-id', identityProviderId: 'idp-123', serviceAccountId: 'sa-456', provider: k8sServiceAccountTokenProvider('/var/token'), refreshBufferSeconds: 120.0, }, }); ## 流式响应 我们支持使用服务器发送事件（SSE）进行流式响应。 ts import OpenAI from 'openai'; const client = new OpenAI(); const stream = await client.responses.create({ model: 'gpt-5.2', input: '快速说十遍"Sheep sleep deep"！', stream: true, }); for await (const event of stream) { console.log(event); } ## 文件上传 对应于文件上传的请求参数可以以多种形式传递： - File（或具有相同结构的对象） - fetch Response（或具有相同结构的对象） - fs.ReadStream - 我们 toFile 辅助函数的返回值 ts import fs from 'fs'; import OpenAI, { toFile } from 'openai'; const client = new OpenAI(); // 如果你有权访问 Node.js 的 `fs` 模块，我们建议使用 `fs.createReadStream()`： await client.files.create({ file: fs.createReadStream('input.jsonl'), purpose: 'fine-tune' }); // 或者，如果你有 Web `File` API，可以传递一个 `File` 实例： await client.files.create({ file: new File(['my bytes'], 'input.jsonl'), purpose: 'fine-tune' }); // 你也可以传递 `fetch` 的 `Response`： await client.files.create({ file: await fetch('https://somesite/input.jsonl'), purpose: 'fine-tune', }); // 最后，如果上述方法都不方便，你可以使用我们的 `toFile` 辅助函数： await client.files.create({ file: await toFile(Buffer.from('my bytes'), 'input.jsonl'), purpose: 'fine-tune', }); await client.files.create({ file: await toFile(new Uint8Array([0, 1, 2]), 'input.jsonl'), purpose: 'fine-tune', }); ## Webhook 验证 验证 webhook 签名是可选但推荐的。有关 webhook 的更多信息，请参阅 API 文档 (https://platform.openai.com/docs/guides/webhooks)。 ### 解析 webhook 负载 对于大多数用例，你可能希望同时验证 webhook 并解析负载。为了实现这一点，我们提供了 client.webhooks.unwrap() 方法，该方法会解析 webhook 请求并验证它是否由 OpenAI 发送。如果签名无效，此方法将抛出错误。请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要先对其进行解析）。.unwrap() 方法会在验证 webhook 确实来自 OpenAI 后，将此 JSON 解析为事件对象。 ts import { headers } from 'next/headers'; import OpenAI from 'openai'; const client = new OpenAI({ webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // 默认使用环境变量；此处显式声明。 }); export async function webhook(request: Request) { const headersList = headers(); const body = await request.text(); try { const event = client.webhooks.unwrap(body, headersList); switch (event.type) { case 'response.completed': console.log('响应完成:', event.data); break; case 'response.failed': console.log('响应失败:', event.data); break; default: console.log('未处理的事件类型:', event.type); } return Response.json({ message: 'ok' }); } catch (error) { console.error('无效的 webhook 签名:', error); return new Response('无效签名', { status: 400 }); } } ### 直接验证 webhook 负载 在某些情况下，你可能希望在解析负载之前单独验证 webhook。如果你倾向于分别处理这些步骤，我们提供了 client.webhooks.verifySignature() 方法，该方法仅验证 webhook 请求的签名。与 .unwrap() 一样，如果签名无效，此方法将抛出错误。请注意，body 参数必须是服务器发送的原始 JSON 字符串（不要先对其进行解析）。验证签名后，你需要自行解析 body。 ts import { headers } from 'next/headers'; import OpenAI from 'openai'; const client = new OpenAI({ webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // 默认使用环境变量；此处显式声明。 }); export async function webhook(request: Request) { const headersList = headers(); const body = await request.text(); try { client.webhooks.verifySignature(body, headersList); // 验证后解析 body const event = JSON.parse(body); console.log('已验证的事件:', event); return Response.json({ message: 'ok' }); } catch (error) { console.error('无效的 webhook 签名:', error); return new Response('无效签名', { status: 400 }); } } ## 错误处理 当库无法连接到 API，或者 API 返回非成功状态码（即 4xx 或 5xx 响应）时，将抛出 APIError 的子类： ts const job = await client.fineTuning.jobs .create({ model: 'gpt-4o', training_file: 'file-abc123' }) .catch(async (err) => { if (err instanceof OpenAI.APIError) { console.log(err.request_id); console.log(err.status); // 400 console.log(err.name); // BadRequestError console.log(err.headers); // {server: 'nginx', ...} } else { throw err; } }); 错误代码如下： | 状态码 | 错误类型 | | ———– | ––––––––––––– | | 400 | BadRequestError | | 401 | AuthenticationError | | 403 | PermissionDeniedError | | 404 | NotFoundError | | 422 | UnprocessableEntityError | | 429 | RateLimitError | | >=500 | InternalServerError | | N/A | APIConnectionError | ## 请求 ID > 有关调试请求的更多信息，请参阅这些文档 (https://platform.openai.com/docs/api-reference/debugging-requests) SDK 中的所有对象响应都提供 _request_id 属性，该属性从 x-request-id 响应头添加，以便你可以快速记录失败的请求并向 OpenAI 报告。 ts const completion = await client.chat.completions.create({ messages: [{ role: 'user', content: '说这是一个测试' }], model: 'gpt-5.2', }); console.log(completion._request_id); // req_123 你也可以使用 .withResponse() 方法访问请求 ID： ts const { data: stream, request_id } = await openai.chat.completions .create({ model: 'gpt-5.2', messages: [{ role: 'user', content: '说这是一个测试' }], stream: true, }) .withResponse(); ## 实时 API 实时 API 使你能够构建低延迟、多模态的对话体验。它目前通过 WebSocket 连接支持文本和音频作为输入和输出，以及函数调用 (https://platform.openai.com/docs/guides/function-calling)。 ts import { OpenAIRealtimeWebSocket } from 'openai/realtime/websocket'; const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-realtime' }); rt.on('response.text.delta', (event) => process.stdout.write(event.delta)); 更多信息请参见 realtime.md。 ## 微软 Azure OpenAI 要与 Azure OpenAI (https://learn.microsoft.com/azure/ai-services/openai/overview) 一起使用该库，请使用 AzureOpenAI 类代替 OpenAI 类。 > [!重要] > Azure API 形状与核心 API 形状略有不同，这意味着响应/参数的静态类型 > 并不总是正确。 ts import { AzureOpenAI } from 'openai'; import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity'; const credential = new DefaultAzureCredential(); const scope = 'https://cognitiveservices.azure.com/.default'; const azureADTokenProvider = getBearerTokenProvider(credential, scope); const openai = new AzureOpenAI({ azureADTokenProvider }); const result = await openai.chat.completions.create({ model: 'gpt-5.2', messages: [{ role: 'user', content: '说你好！' }], }); console.log(result.choices[0]!.message?.content); ### 重试 默认情况下，某些错误会自动重试 2 次，并带有短暂的指数退避。连接错误（例如，由于网络连接问题）、408 请求超时、409 冲突、429 速率限制以及 >=500 内部错误默认都会重试。你可以使用 maxRetries 选项配置或禁用此功能： js // 配置所有请求的默认值： const client = new OpenAI({ maxRetries: 0, // 默认为 2 }); // 或者，按请求配置： await client.chat.completions.create({ messages: [{ role: 'user', content: '如何在 JavaScript 中获取当前日期的名称？' }], model: 'gpt-5.2' }, { maxRetries: 5, }); ### 超时 请求默认在 10 分钟后超时。你可以使用 timeout 选项进行配置： ts // 配置所有请求的默认值： const client = new OpenAI({ timeout: 20 * 1000, // 20 秒（默认为 10 分钟） }); // 按请求覆盖： await client.chat.completions.create({ messages: [{ role: 'user', content: '如何使用 Python 列出目录中的所有文件？' }], model: 'gpt-5.2' }, { timeout: 5 * 1000, }); 超时时将抛出 APIConnectionTimeoutError。请注意，超时的请求默认将重试两次。 ## 请求 ID > 有关调试请求的更多信息，请参阅这些文档 (https://platform.openai.com/docs/api-reference/debugging-requests) SDK 中的所有对象响应都提供 _request_id 属性，该属性从 x-request-id 响应头添加，以便你可以快速记录失败的请求并向 OpenAI 报告。 ts const response = await client.responses.create({ model: 'gpt-5.2', input: '测试 123' }); console.log(response._request_id); // req_123 你也可以使用 .withResponse() 方法访问请求 ID： ts const { data: stream, request_id } = await openai.responses .create({ model: 'gpt-5.2', input: '说这是一个测试', stream: true, }) .withResponse(); ## 自动分页 OpenAI API 中的列表方法是分页的。你可以使用 for await ... of 语法遍历所有页面中的项目： ts async function fetchAllFineTuningJobs(params) { const allFineTuningJobs = []; // 根据需要自动获取更多页面。 for await (const fineTuningJob of client.fineTuning.jobs.list({ limit: 20 })) { allFineTuningJobs.push(fineTuningJob); } return allFineTuningJobs; } 或者，你可以一次请求单个页面： ts let page = await client.fineTuning.jobs.list({ limit: 20 }); for (const fineTuningJob of page.data) { console.log(fineTuningJob); } // 为方便起见，提供了用于手动分页的方法： while (page.hasNextPage()) { page = await page.getNextPage(); // ... } ## 实时 API 实时 API 使你能够构建低延迟、多模态的对话体验。它目前通过 WebSocket 连接支持文本和音频作为输入和输出，以及函数调用 (https://platform.openai.com/docs/guides/function-calling)。 ts import { OpenAIRealtimeWebSocket } from 'openai/realtime/websocket'; const rt = new OpenAIRealtimeWebSocket({ model: 'gpt-realtime' }); rt.on('response.text.delta', (event) => process.stdout.write(event.delta)); 更多信息请参见 realtime.md。 ## 微软 Azure OpenAI 要与 Azure OpenAI (https://learn.microsoft.com/azure/ai-services/openai/overview) 一起使用该库，请使用 AzureOpenAI 类代替 OpenAI 类。 > [!重要] > Azure API 形状与核心 API 形状略有不同，这意味着响应/参数的静态类型 > 并不总是正确。 ``ts import { AzureOpenAI } from ‘openai’; import { getBearerTokenProvider, DefaultAzureCredential } from ‘@azure/identity’; const credential = new DefaultAzureCredential(); const scope = ‘https://cognitiveservices.azure.com/.default’; const azureADTokenProvider = getBearerTokenProvider(credential, scope);