03-模型调用：ChatOpenAI 基础

💡 注意： 本教程适用于 LangChain.js v1.x，需要 Node.js 20+

🎯 本章目标

• ✅ 理解 ChatOpenAI 类的作用
• ✅ 掌握 invoke() 方法
• ✅ 了解所有常用配置参数

---

📦 ChatOpenAI 是什么？

ChatOpenAI 是 LangChain 提供的聊天模型类，支持所有 OpenAI 兼容的 API。

支持的模型平台：

• OpenAI (GPT-4, GPT-3.5)
• ModelScope (魔搭社区)
• Azure OpenAI
• 其他兼容 OpenAI 格式的 API

---

🔧 基本用法

1. 导入类

import { ChatOpenAI } from "@langchain/openai";
// 或者 CommonJS
const { ChatOpenAI } = require("@langchain/openai");

2. 创建模型实例

const model = new ChatOpenAI({
  modelName: "MiniMax/MiniMax-M2.5",
  apiKey: "你的 API Key",
  temperature: 0.7,
  configuration: {
    baseURL: "https://api-inference.modelscope.cn/v1",
  },
});

3. 调用模型

import { HumanMessage } from "@langchain/core/messages";

// 方式 1：invoke() - 一次性获取完整回复
const response = await model.invoke([
  new HumanMessage("你好，请介绍一下北京")
]);
console.log(response.content);

// 方式 2：stream() - 流式获取回复
const stream = await model.stream(messages);
for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

---

⚙️ 完整参数详解

构造函数参数

参数	类型	默认值	说明
modelName	string	-	模型名称，如 gpt-4、MiniMax/MiniMax-M2.5
apiKey	string	-	API Key，也可通过环境变量 OPENAI_API_KEY 提供
organization	string	-	OpenAI 组织 ID
configuration	object	-	OpenAI 客户端配置
configuration.baseURL	string	https://api.openai.com/v1	API 基础地址
configuration.timeout	number	60000	超时时间 (毫秒)
configuration.httpAgent	Agent	-	HTTP 代理
configuration.headers	object	-	自定义请求头
temperature	number	0.7	温度，控制随机性 (0-2)
maxTokens	number	-	最大输出 token 数
topP	number	1	核采样参数 (0-1)
frequencyPenalty	number	0	频率惩罚 (-2 到 2)
presencePenalty	number	0	存在惩罚 (-2 到 2)
n	number	1	生成多少个完成
logitBias	object	-	修改特定 token 的概率
stop	string|array	-	停止序列
streaming	boolean	false	是否流式输出（注意：推荐使用 stream() 方法）
modelKwargs	object	-	传递给模型的额外参数

---

🌡️ Temperature 参数详解

// 低温度 (0.0-0.3) - 更确定、保守、可预测
const conservative = new ChatOpenAI({
  temperature: 0.1,
  // 适合：事实问答、代码生成、数据提取
});

// 中温度 (0.5-0.8) - 平衡
const balanced = new ChatOpenAI({
  temperature: 0.7,  // 默认值
  // 适合：一般对话、创意写作
});

// 高温度 (1.0-2.0) - 更有创意、随机
const creative = new ChatOpenAI({
  temperature: 1.5,
  // 适合：头脑风暴、诗歌创作
});

---

📋 完整示例代码

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

async function main() {
  // 创建模型
  const model = new ChatOpenAI({
    // 必需参数
    modelName: "MiniMax/MiniMax-M2.5",
    apiKey: process.env.MODELSCOPE_API_KEY || "你的 API Key",
    
    // 可选参数
    temperature: 0.7,        // 创造性
    maxTokens: 1024,         // 最大输出长度
    topP: 1,                 // 核采样
    frequencyPenalty: 0,     // 频率惩罚
    presencePenalty: 0,      // 存在惩罚
    
    // API 配置
    configuration: {
      baseURL: "https://api-inference.modelscope.cn/v1",
      timeout: 60000,        // 60 秒超时
    },
  });

  // 构建消息
  const messages = [
    new SystemMessage("你是一个专业的翻译助手。"),
    new HumanMessage("请将以下英文翻译成中文：Hello, World!"),
  ];

  // 调用模型
  const response = await model.invoke(messages);
  
  console.log("翻译结果:", response.content);
}

main();

---

🔄 invoke() vs stream() 对比

方法	返回值	使用场景	示例
invoke()	AIMessage	短文本、需要完整结果	const res = await model.invoke(msg)
stream()	AsyncIterable	长文本、实时显示	for await (const c of await model.stream(msg))

// invoke() 示例
const response = await model.invoke([
  new HumanMessage("你好")
]);
console.log(response.content);  // 等待完成后一次性输出

// stream() 示例
const stream = await model.stream([
  new HumanMessage("请写一篇长文章")
]);
for await (const chunk of stream) {
  process.stdout.write(chunk.content);  // 逐字输出
}

---

📊 响应对象结构

const response = await model.invoke(messages);

console.log(response);
// 输出:
// AIMessage {
//   content: "回复内容",
//   additional_kwargs: {},
//   response_metadata: {
//     tokenUsage: { promptTokens: 10, completionTokens: 20, totalTokens: 30 },
//     finish_reason: "stop"
//   },
//   id: "chatcmpl-xxx"
// }

---

⚠️ 常见问题

1. API Key 无效

Error: 401 Unauthorized

解决：检查 API Key 是否正确，是否有可用额度。

2. 模型不存在

Error: 404 Model not found

解决：检查 modelName 是否正确，不同平台的模型名称不同。

3. 超时

Error: Request timeout

解决：增加 configuration.timeout 或检查网络连接。

4. 额度不足

Error: 429 InsufficientQuotaError

解决：充值或更换模型。

---

📝 本章小结

• ChatOpenAI 是调用大模型的主要类
• invoke() 用于一次性获取回复，stream() 用于流式输出
• temperature 控制输出的随机性
• configuration.baseURL 用于指定 API 端点
• 响应对象包含 content、tokenUsage 等信息

---

🏃 下一章

04-消息类型 →