OpenAI Node.js 依赖库（官方）详细参数说明

以下是 OpenAI 官方 Node.js/TypeScript SDK（当前版本 6.32.0）的完整参数说明，包含客户端配置、核心 API 请求参数及响应格式，基于官方 OpenAPI 规范与类型定义整理。

---

一、客户端配置参数（OpenAI 构造函数）

初始化 OpenAI 客户端时的配置选项，用于全局设置 API 访问参数。

参数名	类型	是否必填	默认值	说明
apiKey	string	是（除非使用 apiKey 环境变量）	process.env.OPENAI_API_KEY	OpenAI API 密钥，服务器端使用，切勿在浏览器暴露
organization	string	否	undefined	组织 ID，用于关联 API 调用到特定组织账户
baseURL	string	否	"https://api.openai.com/v1"	API 基础 URL，可用于代理或私有化部署
timeout	number	否	600000（10 分钟）	单个请求超时时间（毫秒）
maxRetries	number	否	2	请求失败自动重试次数
fetch	Function	否	node-fetch（Node.js）/内置 fetch（浏览器）	自定义 fetch 实现
headers	Record<string, string>	否	{}	全局请求头，可在单个请求中通过设置为 null 移除
defaultQuery	Record<string, string>	否	{}	全局默认查询参数
dangerouslyAllowBrowser	boolean	否	false	允许在浏览器环境使用（不推荐，存在密钥泄露风险）
httpAgent	http.Agent	否	undefined	Node.js 环境下的 HTTP 代理配置
httpsAgent	https.Agent	否	undefined	Node.js 环境下的 HTTPS 代理配置

初始化示例：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  organization: 'org-xxxxxxxxxxxxxxxxxxxxxxxx',
  timeout: 30000, // 30秒
  maxRetries: 3,
});

---

二、核心 API 请求参数

2.1 聊天补全（Chat Completions）- client.chat.completions.create()

创建聊天对话的模型响应，适用于 GPT-3.5/4/5 等模型。

参数名	类型	是否必填	默认值	说明
model	string	是	-	使用的模型 ID（如 gpt-4-turbo, gpt-5.2）
messages	Array	是	-	对话历史，每个元素包含 role（system/user/assistant/tool）和 content
temperature	number	否	1.0	控制输出随机性（0.0-2.0），值越高越随机，建议与 top_p 二选一
top_p	number	否	1.0	核采样阈值（0.0-1.0），模型仅考虑累计概率达 top_p 的 token
n	number	否	1	生成的响应数量
stream	boolean	否	false	是否启用流式响应，返回 Server-Sent Events
stop	string/Array	否	null	停止序列，模型生成到此处停止
max_tokens	number	否	无限（受模型上下文限制）	生成的最大 token 数
presence_penalty	number	否	0.0	存在惩罚（-2.0-2.0），正值增加新主题出现概率
frequency_penalty	number	否	0.0	频率惩罚（-2.0-2.0），正值减少重复内容概率
logit_bias	Record<string, number>	否	null	调整特定 token 的生成概率（-100-100）
user	string	否	undefined	终端用户唯一标识，用于监控和滥用检测
response_format	{ type: "text" | "json_object" }	否	{ type: "text" }	响应格式，设置为 json_object 启用 JSON 模式
tools	Array	否	undefined	可用工具列表，支持函数调用
tool_choice	"none" | "auto" | "required" | { type: "function", function: { name: string } }	否	"auto"	工具调用策略，required 强制调用工具，none 禁用工具
tool_prompt	string	否	undefined	工具调用提示，指导模型如何使用工具
parallel_tool_calls	boolean	否	true	是否允许并行调用多个工具
seed	number	否	undefined	随机种子，相同种子可复现结果
metadata	Record<string, string>	否	undefined	自定义元数据，用于追踪请求

ChatCompletionMessage 结构：

interface ChatCompletionMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string | null; // 工具调用时可为 null
  name?: string; // 工具名称（仅 tool 角色）
  tool_call_id?: string; // 关联的工具调用 ID（仅 tool 角色）
}

示例：

const response = await client.chat.completions.create({
  model: "gpt-4-turbo",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain quantum computing in simple terms." }
  ],
  temperature: 0.7,
  max_tokens: 200
});

2.2 函数调用相关参数

工具调用（函数调用）参数细节：

参数名	类型	说明
tools	Array<{ type: "function", function: FunctionDefinition }>	函数定义数组，每个函数需包含 name、description 和 parameters（JSON Schema）
tool_choice	string | object	控制工具调用行为： - "none": 禁用工具 - "auto": 模型自主决定 - "required": 强制调用工具 - 特定函数：{ type: "function", function: { name: "function_name" } }

FunctionDefinition 结构：

interface FunctionDefinition {
  name: string; // 函数名（必须）
  description?: string; // 函数功能描述，帮助模型判断何时调用
  parameters?: Record<string, any>; // 函数参数的 JSON Schema 定义
}

2.3 嵌入生成（Embeddings）- client.embeddings.create()

生成文本的向量表示，用于语义搜索、聚类等场景。

参数名	类型	是否必填	默认值	说明
model	string	是	-	嵌入模型 ID（如 text-embedding-3-large）
input	string | Array	是	-	输入文本或文本数组
encoding_format	"float" | "base64"	否	"float"	输出格式，float 返回浮点数数组，base64 返回 base64 编码字符串
dimensions	number	否	undefined	输出向量维度（仅适用于 text-embedding-3 及更高版本）
user	string	否	undefined	终端用户标识，用于监控和滥用检测

2.4 图像生成（Images）- client.images.generate()

使用 DALL·E 模型生成图像。

参数名	类型	是否必填	默认值	说明
model	string	否	"dall-e-2"	图像生成模型（dall-e-2, dall-e-3, gpt-image-1）
prompt	string	是	-	图像描述文本，越详细越好
n	number	否	1	生成图像数量（1-10，取决于模型）
size	string	否	"1024x1024"	图像尺寸（如 256x256, 512x512, 1024x1024, 1792x1024）
quality	"standard" | "hd"	否	"standard"	图像质量，hd 仅适用于 DALL·E 3
response_format	"url" | "b64_json"	否	"url"	响应格式，url 返回图像 URL，b64_json 返回 base64 编码
style	"natural" | "vivid"	否	"natural"	图像风格，仅适用于 DALL·E 3
user	string	否	undefined	终端用户标识，用于监控和滥用检测

2.5 文本补全（Completions）- client.completions.create()

传统文本补全 API，适用于 GPT-3 等模型（不推荐新应用使用，建议使用 Chat Completions）。

参数名	类型	是否必填	默认值	说明
model	string	是	-	模型 ID（如 text-davinci-003）
prompt	string | Array	是	-	输入提示文本
suffix	string	否	null	追加到生成文本后的后缀
max_tokens	number	否	16	生成的最大 token 数
temperature	number	否	1.0	同 Chat Completions
top_p	number	否	1.0	同 Chat Completions
n	number	否	1	同 Chat Completions
stream	boolean	否	false	同 Chat Completions
logprobs	number	否	null	返回前 N 个 token 的对数概率
echo	boolean	否	false	是否回显输入提示
stop	string | Array	否	null	同 Chat Completions
presence_penalty	number	否	0.0	同 Chat Completions
frequency_penalty	number	否	0.0	同 Chat Completions
best_of	number	否	1	生成 best_of 个候选，返回最佳结果
logit_bias	Record<string, number>	否	null	同 Chat Completions
user	string	否	undefined	同 Chat Completions

---

三、响应格式说明

3.1 聊天补全响应（ChatCompletion）

interface ChatCompletion {
  id: string; // 请求唯一标识
  object: "chat.completion"; // 对象类型
  created: number; // 创建时间（Unix 时间戳）
  model: string; // 使用的模型
  choices: Array<{
    index: number; // 结果索引
    message: ChatCompletionMessage; // 生成的消息
    finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call"; // 结束原因
  }>;
  usage: {
    prompt_tokens: number; // 提示 token 数
    completion_tokens: number; // 完成 token 数
    total_tokens: number; // 总 token 数
  };
  system_fingerprint: string; // 后端配置指纹，用于追踪模型版本
}

3.2 流式聊天补全响应

流式响应时，每个数据块包含 delta（增量内容）而非完整消息：

interface ChatCompletionChunk {
  id: string;
  object: "chat.completion.chunk";
  created: number;
  model: string;
  choices: Array<{
    index: number;
    delta: Partial<ChatCompletionMessage>; // 增量消息内容
    finish_reason: string | null; // 结束原因（最后一块才有值）
  }>;
}

3.3 嵌入响应（Embedding）

interface Embedding {
  id: string;
  object: "embedding";
  created: number;
  model: string;
  data: Array<{
    index: number;
    embedding: Array<number> | string; // 向量嵌入，格式由 encoding_format 决定
    object: "embedding";
  }>;
  usage: {
    prompt_tokens: number;
    total_tokens: number;
  };
}

3.4 图像生成响应（Image）

interface Image {
  created: number;
  data: Array<{
    url?: string; // 图像 URL（response_format 为 url 时）
    b64_json?: string; // base64 编码（response_format 为 b64_json 时）
  }>;
}

---

四、错误处理

API 调用可能抛出以下类型的错误：

错误类型	说明
APIError	通用 API 错误，包含 status（HTTP 状态码）和 error（错误详情）
TimeoutError	请求超时
RateLimitError	超出 API 速率限制
AuthenticationError	API 密钥无效或缺失
NotFoundError	请求资源不存在
ConflictError	资源冲突
UnprocessableEntityError	请求参数验证失败

错误处理示例：

try {
  const response = await client.chat.completions.create({
    model: "gpt-4-turbo",
    messages: [{ role: "user", content: "Hello!" }]
  });
} catch (error) {
  if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit exceeded. Please try again later.");
  } else if (error instanceof OpenAI.AuthenticationError) {
    console.error("Invalid API key.");
  } else {
    console.error("An error occurred:", error);
  }
}

---

五、请求选项覆盖

单个请求可覆盖全局配置，通过第二个参数传递请求选项：

const response = await client.chat.completions.create(
  {
    model: "gpt-4-turbo",
    messages: [{ role: "user", content: "Hello!" }]
  },
  {
    timeout: 30000, // 覆盖全局超时设置
    headers: { "X-Custom-Header": "value" }, // 添加自定义请求头
    signal: AbortSignal.timeout(10000) // 添加请求取消信号
  }
);

---

六、关键注意事项

1. API 密钥安全：切勿在客户端代码中暴露 API 密钥，建议使用环境变量或后端代理
2. token 计算 ：输入输出的 token 数会影响成本和响应时间，可使用 tiktoken 库预估
3. 流式响应：流式响应可提升用户体验，但需处理 Server-Sent Events 连接管理
4. 函数调用：工具调用需实现工具执行逻辑，并将结果返回给模型进行多轮交互
5. 模型选择：根据任务需求选择合适模型，Chat 模型适用于对话，Embedding 模型适用于语义搜索

以上参数说明基于 OpenAI 官方 Node.js SDK v6.x 版本，具体细节请以官方文档和API 参考为准。