Skip to content
LangChain.js 概述
在 Node.js 里调用一次大语言模型很简单：拿到 API Key，发一个 HTTP 请求，把响应文本取出来。但一旦要从“调用模型”走向“构建一个可维护的应用”，就会撞上一连串重复的工程问题：
- 请求参数和响应格式因供应商而异，切换模型时需要改大量代码。
- 提示词里需要嵌入变量，字符串拼接的方式很快变得不可控。
- 模型的原始输出需要被解析成结构化数据，才能被业务逻辑消费。
- 对话历史、上下文管理、重试机制、流式输出——这些需求会逐步叠加进来。
LangChain.js 把这些常见模式抽象成了可组合的组件，在开发、调试、部署的整个过程里，提供一套一致的接口。它的核心不在于“封装 API”，而在于用表达式语言（LCEL）将各个处理步骤串联起来——从接收用户输入到产生最终响应，每一步都通过统一的接口（invoke、stream、batch）来操控。
核心组件
开始写代码之前，先看一下框架里最常接触的几个抽象。
基础组件
- ChatModel：包装一个大语言模型的调用，接收消息列表，返回消息。对接 OpenAI、Anthropic 等不同供应商时，调用方式保持一致。
- PromptTemplate：将提示词模板与变量合并，生成最终的提示词文本或消息。支持定义输入变量、部分变量和模板格式。
- OutputParser：将模型的自然语言输出解析成 JSON、枚举值等结构化数据。如果模型输出不符合预期格式，可以通过
OutputFixingParser结合 LLM 进行自动修复。
组合层
- Runnable：LCEL 中的统一调用接口，所有可执行组件都实现了
invoke、stream、batch等方法，可将任意组件组合成序列、映射或分支结构。 - Chain：多个 Runnable 按顺序组合而成的完整流程，例如“填模板 → 调模型 → 解析输出”，本质上是 LCEL 表达式的一种具体形式。
辅助机制
- Memory：在会话中保存与提取历史消息，使对话能保持上下文——不像无状态的 API 调用那样每次都要手动拼接历史。
- CallbackHandler：监听链路上各节点的运行事件，可用于记录日志、计算 token 消耗、向监控系统推送数据等辅助逻辑。
另外还有一组与检索增强生成（RAG）相关的概念：
- RAG（Retrieval-Augmented Generation）：先检索相关文档，再让模型基于检索结果生成回答，以降低幻觉。
- Embedding：将文本映射为数值向量，用于计算语义相似度。
- VectorStore：存储向量并提供相似性搜索的数据库接口。
- Retriever：根据查询从向量库或索引中获取相关文档的组件，可与 VectorStore 绑定实现文档查询。
这些术语先有个印象。接下来先走通一个最简单的 ChatModel 调用，之后再逐步引入其他组件。
准备工作
版本要求与项目初始化
LangChain.js 要求 Node.js 18.x 及以上版本，官方声明支持 20.x、22.x 和 24.x。项目可运行在 ESM 或 CommonJS 模块系统下，也兼容 Cloudflare Workers、Vercel / Next.js、Deno、Bun 等运行时。这里以 Node.js 20+ 的 CommonJS 项目为例。
bash
mkdir hello-langchain
cd hello-langchain
npm init -ypackage.json 中默认会生成 "type": "commonjs"（如果没有则显式加上），后续可用 require 引入模块。
安装依赖
主包 langchain 包含了链、代理、检索策略等上层抽象，但不含特定模型供应商的实现。调用某个模型需要额外安装对应的合作伙伴包。
bash
npm install langchain @langchain/openai如果使用 Anthropic 的模型，则对应安装 @langchain/anthropic。其他供应商的包名可查阅官方集成文档。
使用环境变量保存 API Key
API Key 不应硬编码在源码里。一种简单的做法是在项目根目录创建 .env 文件，用 dotenv 加载。
bash
npm install dotenv.env 文件内容：
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx在入口文件顶部引用：
javascript
require('dotenv').config();部署到线上时，直接在宿主环境设置环境变量，不依赖 .env 文件。同时必须将 .env 加入 .gitignore，避免敏感信息进入版本控制。
第一个示例
下面是一个最小可运行示例，向 OpenAI 的模型发出一条问候消息，并打印响应。
javascript
// 01-hello.js
require('dotenv').config();
const { ChatOpenAI } = require('@langchain/openai');
async function main() {
// 初始化 ChatModel，指定模型名称和温度参数
const model = new ChatOpenAI({
model: 'gpt-4o-mini',
temperature: 0.7,
});
// 构造消息列表
const messages = [
{ role: 'system', content: '你是一个友好的助手。' },
{ role: 'user', content: '你好！请用一句话介绍你自己。' },
];
// 调用模型并等待完整响应
const response = await model.invoke(messages);
// response 为 AIMessage 实例，content 字段即模型回复文本
console.log(response.content);
}
main().catch(err => {
console.error('调用失败:', err.message);
process.exit(1);
});运行：
bash
node 01-hello.js如果配置正确，终端输出类似：
你好！我是一个人工智能助手，专注于回答问题、提供信息以及协助完成各种任务。程序拆解
上面的代码虽短，但已覆盖从构造消息到获取响应的完整链路。
加载环境变量：
dotenv将.env中的OPENAI_API_KEY注入process.env。@langchain/openai内部默认从环境变量读取 Key，不需要手动传递。初始化 ChatModel：
new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0.7 })创建模型实例。model指定要调用的模型版本，temperature控制输出的随机程度，取值范围 0~2，值越低输出越确定。构造消息列表：每条消息包含
role（system、user或assistant）和content字段。LangChain 会将这个数组原样发送给 API。调用
model.invoke：invoke是 Runnable 接口定义的方法，表示“执行并返回完整结果”。该方法会阻塞直到模型生成完毕，返回一个AIMessage实例。其行为与stream（逐步返回生成内容）和batch（批量处理多条输入）互为补充。输出响应：
AIMessage的content字段为模型回复的文本。除此之外，还有response_metadata等附加信息，例如 token 用量、模型名称等，可用于成本统计。
运行时，LangChain 在底层执行了三步：将消息列表序列化为 API 要求的格式，用环境变量中的 Key 发起 HTTPS 请求，解析响应并封装成 AIMessage。如果网络异常或 API 返回错误，库会抛出异常——示例中用 catch 捕获并打印了错误消息。
适用场景
当应用只包含一两个硬编码的提示词时，直接用 HTTP 客户端调用 API 就足够。以下场景中，LangChain.js 的抽象才开始体现出价值：
- 多步骤流水线：需要依次执行“查询改写 → 向量检索 → 拼接上下文 → 生成回答”这类流程时，用 LCEL 把每一步串起来，整个链路即可统一支持
invoke、stream、batch，切换组件或调整顺序的成本很低。 - 聊天机器人：通过 Memory 组件自动管理历史消息，模型每次调用都能看到之前的对话上下文。
- 结构化输出：结合 OutputParser 让模型返回 JSON 或枚举值，供业务代码直接消费。
- 代理（Agent）：让模型决定调用哪些工具、按什么顺序调用，适合需要访问外部 API 或数据库的场景。
- RAG 系统：对自有文档做 Embedding 并存入 VectorStore，查询时先检索相关片段，再交给模型回答，适用于知识库问答等场景。
注意点
- API Key 安全：Key 必须通过环境变量注入，
.env文件需加入.gitignore。线上部署时，使用平台提供的环境变量配置功能。 - 网络与速率限制：
invoke是同步式等待，调用耗时取决于模型负载。需要快速首字响应的场景，可改用stream方法获取流式输出。供应商的速率限制需要自行处理，LangChain 本身不内置限流机制。 - 模型版本差异：示例中使用了
gpt-4o-mini，不同模型支持的消息格式、参数、返回结构可能存在差异，切换模型时需查阅对应供应商包的文档。 - 版本兼容性：本文基于 langchain v1.0 及以上版本编写。2025 年 10 月发布的 v1.0 对 API 做了整合，网上的旧版教程（包括部分中文资料）对应的 API 已经过时。如果参考社区示例，需留意
langchain主包的版本以及@langchain/openai等包的导入路径。当前官方文档地址为https://docs.langchain.org.cn/oss/javascript/langchain/overview。 - 温度参数：
temperature设为 0 时，模型输出接近确定，但部分模型在温度为 0 时仍可能出现微小差异，这是模型服务本身的特性，并非 LangChain 引入的问题。 - 错误处理：示例仅做了最基础的异常捕获。实际应用中，网络抖动、API 临时不可用、Token 超限等情况都需要针对性的处理，例如重试、降级、截断上下文等。
后续学习
LangChain 官方文档按“教程 → 操作指南 → 概念指南 → API 参考”组织。入门路径推荐先完成以下教程：
- 构建一个简单的 LLM 应用
- 构建一个聊天机器人
- 构建一个代理
- LangGraph.js 快速入门（有状态多角色应用）
其中 LangGraph.js 是 LangChain 生态中用于构建多步骤、有状态应用的库，适合复杂的自主代理场景。
参考链接
- LangChain.js 官方文档（v1.0）：https://docs.langchain.org.cn/oss/javascript/langchain/overview
- LangChain.js GitHub 仓库（含运行环境说明）：https://github.com/langchain-ai/langchainjs
- 社区示例（旧版，仅作概念参考）：https://github.com/webup/langchain-js-quickstart
- langchain 主包（npm）：https://www.npmjs.com/package/langchain
- @langchain/openai 集成包（npm）：https://www.npmjs.com/package/@langchain/openai
- LangChain JavaScript 中文文档（旧版）：https://js.langchain.ac.cn