LangChain.js 是 LangChain 生态的 JavaScript/TypeScript 实现目标很直接把大模型接入应用这件事从“手写一堆请求逻辑”变成“用标准组件拼装链路”。它不是一个模型也不是一个能一键部署的模型服务而是一套面向 AI 应用开发的编排框架。提示词模板、模型调用、输出解析、文档检索、工具调用、多轮记忆、Agent 编排都有对应的模块可以直接组合使用。如果你用 Node.js 做后端开发或者想把大模型能力接进现有系统LangChain.js 是目前最值得先了解的框架之一。它解决的具体问题包括同一套链路可以在不同模型之间切换提示词和业务逻辑解耦RAG 流程可以标准化复用Agent 工具调用的循环也不需要自己从零写。这篇文章不打算铺陈概念而是直接围绕“能不能用、怎么装、怎么跑、怎么接接口、怎么做批量任务”展开。我们会在 Node.js 环境里从零搭建一个 LangChain.js 项目依次验证对话链路、提示词模板、输出解析、多轮记忆、RAG 检索、Agent 工具调用最后包一层 HTTP API 服务并给出批量请求的写法。全程不涉及 GPU 部署也不要求你有一张高性能显卡这是它和本地大模型部署最大的区别。1. LangChain.js 核心能力速览能力项说明项目类型大模型应用开发编排框架JavaScript / TypeScript开源情况开源项目LangChain 生态的 JS/TS 版本主要功能模型调用封装、提示词模板、输出解析、RAG 检索、多轮记忆、Agent 与工具调用运行环境Node.js 环境也可在部分浏览器场景使用硬件要求本身不直接消耗 GPU使用云端大模型时只需要正常网络接入本地模型时取决于本地模型的显存和算力要求启动方式npm 安装依赖后通过 Node.js 脚本运行API 能力可以把处理链路封装为 HTTP 接口适合接入现有系统批量任务支持用脚本并发处理批量输入需要自己控制并发与重试适合场景智能问答、知识库问答、文档解析、Agent 工具链、内容生成、聊天机器人从这张表能看出LangChain.js 的核心价值不在“模型本身”而在“应用层编排”。只要你需要调用大模型完成业务功能它就能减少大量重复代码同时让链路更可维护。2. 适用场景与使用边界LangChain.js 适合的人群非常明确已经有 Node.js 基础、想快速把大模型能力产品化的开发者。它的优势场景包括做一个带业务规则的聊天机器人而不是简单套一个模型接口。搭建企业知识库问答需要把文档切分、向量化、检索、生成串成一条流水线。开发 AI Agent让模型可以调用内部工具完成查询、计算、工单处理等操作。把统一的模型调用层封装给前端或微服务避免每个业务都写一遍模型请求代码。同样重要的是知道它不适合什么。LangChain.js 不解决模型本身的能力上限也不会自动让提示词变得完美。如果你的业务只是“请求一次模型、返回一段文本”直接用官方 SDK 可能更轻量。引入编排框架本身会带来学习成本和依赖成本小场景没必要硬套。合规和使用边界也需要提前想清楚。LangChain.js 会把你的输入发送到所配置的模型服务端因此要注意几件事不要在没有授权的情况下把用户隐私数据、商业敏感信息发送到第三方接口如果走云端大模型 API要提前评估数据出境和存储政策生成内容发布或商用前必须复核避免出现事实错误、版权风险或不当内容。涉及人脸、声音、商标、他人作品等素材时必须确认授权链条完整。技术框架本身是中立的但使用方式和数据边界由开发者负责。3. LangChain.js 环境准备与前置条件先确认本地环境。LangChain.js 的核心运行环境是 Node.js官方文档和社区实践中通常建议 Node.js 18 及以上版本因为较新的 LangChain.js 依赖比较现代的 JavaScript 特性低版本 Node 容易出现语法不兼容。建议先用命令检查版本node -v npm -v如果node -v输出的版本低于 18建议先升级 Node.js 环境再继续。接下来需要准备模型访问能力二选一云端大模型 API准备 API Key并确认模型服务商提供的接口地址和模型名称。本地模型服务通过 Ollama 等工具在本地启动大模型服务LangChain.js 可以通过langchain/ollama接入。这种方式需要你本地有足够的 CPU 或 GPU 资源具体显存占用取决于模型大小和 LangChain.js 本身无关。包管理器用 npm 或 pnpm 都可以。数据库方面如果只做示例RAG 部分可以用内存向量存储不依赖外部数据库生产环境再接 Redis、Chroma、PGVector 之类的向量存储。最后是一个容易被忽略的前置条件理解 JavaScript 的异步编程。LangChain.js 的接口大量基于 Promiseawait、并发控制、错误处理都是日常操作这部分基础不牢的话调试会花很多时间。4. LangChain.js 安装部署与快速启动4.1 初始化项目与安装依赖先创建一个空目录初始化 npm 项目并安装基础依赖mkdir langchain-demo cd langchain-demo npm init -y npm install langchain/openai langchain/core dotenv这里的依赖说明langchain/core核心抽象包含提示词模板、输出解析器、消息模型、Runnable 等基础组件。langchain/openaiOpenAI 兼容接口的模型封装这是目前最常用的模型接入包。dotenv读取.env文件管理密钥和配置。如果后续要用到 Agent还需要安装 LangGraph 相关包npm install langchain/langgraph zod如果要用本地 Ollama 模型则安装npm install langchain/ollama安装完成后建议在package.json中加一行type: module这样可以直接使用import语法。不同版本的项目结构可能略有差异以实际拉取到的版本提示为准。4.2 配置模型密钥在项目根目录创建.env文件写入模型服务配置OPENAI_API_KEYsk-你的密钥 OPENAI_BASE_URLhttps://api.example.com/v1说明一下OPENAI_BASE_URL是通用配置方式。如果你使用的是 OpenAI 官方接口可以不填如果使用的是兼容 OpenAI 协议的模型服务或本地网关就把它指向对应地址。具体字段名和取值以你使用的模型服务商文档为准密钥不要提交到 Git 仓库。4.3 跑通第一条对话链路创建index.js写一个最小可运行的对话链路import dotenv/config; import { ChatOpenAI } from langchain/openai; import { ChatPromptTemplate } from langchain/core/prompts; import { StringOutputParser } from langchain/core/output_parsers; const model new ChatOpenAI({ model: gpt-4o-mini, temperature: 0.7, }); const prompt ChatPromptTemplate.fromMessages([ [system, 你是一名资深技术编辑擅长把复杂概念讲清楚。], [human, 请用三句话向初学者解释{topic}], ]); const chain prompt.pipe(model).pipe(new StringOutputParser()); const result await chain.invoke({ topic: RAG 检索增强生成 }); console.log(result);然后运行node index.js如果配置正确控制台会输出一段对 RAG 的解释文本。这段代码演示了 LangChain.js 最核心的组装方式prompt.pipe(model).pipe(parser)。注意模型名称需要替换成你实际可用的模型示例中的模型名称只是常用选择。5. LangChain.js 功能测试与效果验证5.1 基础对话链路第一条链路跑通后可以做几个快速验证。第一测试不同提问的稳定性连续输入几个不同类型的问题观察回答质量。第二调整temperature参数低温输出更稳定高温更有创造性但代码结构不需要变。第三测试流式输出用户体验上会更接近“打字机”效果const stream await chain.stream({ topic: AI Agent }); for await (const chunk of stream) { process.stdout.write(chunk); }判断标准很简单能流式输出、链路不报错、内容符合预期。如果流式输出有问题先看模型服务商是否支持流式接口再看依赖版本是否一致。基础对话链路是最常用的调试入口建议先在这一步把所有环境问题解决再进入后面的复杂功能。5.2 提示词模板与结构化输出大模型返回的是文本但业务系统往往需要结构化数据。LangChain.js 提供了输出解析器可以把模型输出转换为 JSON、CSV 或其他格式。下面是用StructuredOutputParser提取信息的示例import { StructuredOutputParser } from langchain/core/output_parsers; import { ChatPromptTemplate } from langchain/core/prompts; import { ChatOpenAI } from langchain/openai; const parser StructuredOutputParser.fromZodSchema({ type: object, properties: { title: { type: string, description: 文章标题 }, keywords: { type: array, items: { type: string }, description: 关键词列表 }, }, required: [title, keywords], }); const prompt ChatPromptTemplate.fromMessages([ [system, 根据用户输入生成标题和关键词。{format_instructions}], [human, {input}], ]); const chain prompt.pipe(new ChatOpenAI()).pipe(parser); const result await chain.invoke({ input: 写一篇关于 LangChain.js 的文章, format_instructions: parser.getFormatInstructions(), }); console.log(JSON.stringify(result, null, 2));测试时重点看几件事模型能不能严格按格式输出解析器在模型输出不合法时会不会抛错错误提示是否足够定位问题。结构化输出是 LangChain.js 在实际工程中用得非常多的能力因为它解决了“模型输出不可靠”这个关键问题让下游程序可以安全消费。5.3 多轮对话与记忆聊天类应用需要多轮记忆。LangChain.js 提供了消息历史和带记忆的 Runnable 包装器。这里的关键点是默认情况下每次invoke都是独立的模型不记得上一轮内容必须显式把历史消息传入。import { ChatMessageHistory } from langchain/stores/message/in_memory; import { RunnableWithMessageHistory } from langchain/core/runnables; import { ChatOpenAI } from langchain/openai; import { ChatPromptTemplate } from langchain/core/prompts; const messageHistory new ChatMessageHistory(); const prompt ChatPromptTemplate.fromMessages([ [system, 你是一个友好的助手。], [placeholder, {history}], [human, {input}], ]); const chain prompt.pipe(new ChatOpenAI()); const withHistory new RunnableWithMessageHistory({ runnable: chain, getMessageHistory: () messageHistory, inputMessagesKey: input, historyMessagesKey: history, }); await withHistory.invoke( { input: 你好我是小林。 }, { configurable: { sessionId: session-1 } } ); const reply await withHistory.invoke( { input: 我叫什么名字 }, { configurable: { sessionId: session-1 } } ); console.log(reply.content);如果一切正常第二次提问模型应该能回答出“小林”。这里有个典型误区会话标识sessionId决定了加载哪段历史。生产环境中要把历史存到 Redis 或数据库而不是内存对象否则服务重启后记忆就丢了。这个示例只用于验证机制是否跑通。5.4 文档加载与 RAG 检索问答RAG 是 LangChain.js 最核心的用法之一流程是加载文档 → 切分 → 向量化 → 检索 → 拼接提示词 → 生成回答。先准备一个知识文件docs/knowledge.txt内容随意比如 LangChain.js 的介绍文本。然后运行下面的脚本import { TextLoader } from langchain/document_loaders/fs/text; import { RecursiveCharacterTextSplitter } from langchain/text_splitter; import { OpenAIEmbeddings } from langchain/openai; import { MemoryVectorStore } from langchain/vectorstores/memory; import { ChatPromptTemplate } from langchain/core/prompts; import { ChatOpenAI } from langchain/openai; import { StringOutputParser } from langchain/core/output_parsers; import { RunnableSequence, RunnablePassthrough } from langchain/core/runnables; const loader new TextLoader(./docs/knowledge.txt); const docs await loader.load(); const splitter new RecursiveCharacterTextSplitter({ chunkSize: 500, chunkOverlap: 50, }); const splits await splitter.splitDocuments(docs); const vectorStore await MemoryVectorStore.fromDocuments( splits, new OpenAIEmbeddings() ); const retriever vectorStore.asRetriever(3); const prompt ChatPromptTemplate.fromMessages([ [system, 你是一个知识库助手只根据参考资料回答问题。如果资料中没有相关内容请直接说明不知道。], [human, 参考资料\n{context}\n\n问题{question}], ]); const formatDocs (docs) docs.map((d) d.pageContent).join(\n---\n); const ragChain RunnableSequence.from([ { context: retriever.pipe(formatDocs), question: new RunnablePassthrough(), }, prompt, new ChatOpenAI({ model: gpt-4o-mini }), new StringOutputParser(), ]); const answer await ragChain.invoke(LangChain.js 的核心特点是什么); console.log(answer);运行时要确认文档能被正确加载切分后的块数合理向量化成功检索能召回相关内容。判断标准是当问题与知识库内容相关时回答应引用资料内容而不是凭空生成。RAG 链路最容易出问题的地方是切分粒度和检索召回质量chunkSize太大上下文容易被无关内容稀释太小单块信息量不足。这个参数需要针对实际文档反复调。5.5 Agent 与工具调用Agent 是 LangChain.js 进阶玩法。模型本身不能调用工具但 Agent 可以让模型根据用户需求决定调用哪个工具再把工具返回结果交给模型生成最终回答。下面是一个简单示例通过预编译 Agent 让模型调用自定义的天气工具import { createAgent } from langchain/langgraph/prebuilt; import { ChatOpenAI } from langchain/openai; import { tool } from langchain/core/tools; import { z } from zod; const getWeather tool( async ({ city }) { // 这里只是演示工具格式实际使用要接入真实天气服务 if (city 杭州) { return 杭州今天多云气温 22-28 度。; } return 暂时没有 ${city} 的天气数据。; }, { name: get_weather, description: 查询指定城市的天气, schema: z.object({ city: z.string().describe(城市名称), }), } ); const agent createAgent({ llm: new ChatOpenAI({ model: gpt-4o-mini }), tools: [getWeather], }); const result await agent.invoke({ messages: [{ role: user, content: 杭州今天天气怎么样 }], }); console.log(result.messages[result.messages.length - 1].content);注意这里天气数据是示例用的假数据真实场景要替换成天气 API 调用。测试 Agent 时重点观察两点模型是否能正确识别“需要调用工具”的意图工具返回后模型能否把结果整理成自然的回答。如果 Agent 没有调用工具通常说明工具描述不清楚或者模型能力不足。工具数量建议从少到多先验证一个工具再逐步叠加否则模型容易在工具选择上出错。6. LangChain.js 接口 API 与批量任务6.1 用 Express 封装 HTTP 接口脚本能跑通后下一步就是把它变成服务。安装 Expressnpm install express然后创建一个简单的 API 服务把 LangChain 链路包装成 HTTP 接口import express from express; import { ChatOpenAI } from langchain/openai; import { ChatPromptTemplate } from langchain/core/prompts; import { StringOutputParser } from langchain/core/output_parsers; const app express(); app.use(express.json()); const model new ChatOpenAI({ model: gpt-4o-mini, temperature: 0.3 }); const prompt ChatPromptTemplate.fromTemplate(用户问题{question}\n请给出简洁准确的回答。); const chain prompt.pipe(model).pipe(new StringOutputParser()); app.post(/api/generate, async (req, res) { try { const { question } req.body; if (!question) { return res.status(400).json({ error: question 不能为空 }); } const answer await chain.invoke({ question }); res.json({ answer }); } catch (err) { res.status(500).json({ error: err.message }); } }); app.listen(3000, () { console.log(API 服务已启动: http://127.0.0.1:3000); });启动服务后用 curl 验证curl -X POST http://127.0.0.1:3000/api/generate \ -H Content-Type: application/json \ -d {question:LangChain.js 适合做什么}能返回 JSON 结构的内容就说明接口通了。接口封装要注意几个细节请求体要校验超时要给客户端明确提示错误信息不要直接泄露到响应里生产环境还要加鉴权。这里用的是同步等待模式对耗时敏感的场景建议改成流式响应或异步任务。6.2 批量任务与失败重试批量任务在 LangChain.js 里不需要特殊框架无非是循环加并发控制。但要特别注意大模型接口有速率限制直接一次性并发几十个请求很容易触发限流必须做并发上限和失败重试。下面是一个通用批量处理模板async function runWithRetry(fn, maxRetries 3) { let lastError; for (let i 0; i maxRetries; i) { try { return await fn(); } catch (err) { lastError err; const delay 1000 * Math.pow(2, i); console.log(第 ${i 1} 次失败${delay}ms 后重试${err.message}); await new Promise((resolve) setTimeout(resolve, delay)); } } throw lastError; } async function runBatch(questions, concurrency 3) { const results []; for (let i 0; i questions.length; i concurrency) { const batch questions.slice(i, i concurrency); const batchResults await Promise.allSettled( batch.map((q) runWithRetry(() chain.invoke({ question: q })) ) ); results.push(...batchResults); } return results; } const questions [ 什么是 LangChain, 什么是 RAG, 什么是 AI Agent, 什么是提示词工程, 什么是向量数据库, ]; const results await runBatch(questions, 2); results.forEach((r, i) { if (r.status fulfilled) { console.log(问题 ${i 1} 回答完成); } else { console.error(问题 ${i 1} 失败${r.reason.message}); } });Promise.allSettled可以保证单个任务失败不会拖垮整批任务runWithRetry用指数退避的方式规避限流。批量任务一定要加日志记录每个输入的成功或失败状态方便事后定位和重跑失败项。7. 资源占用与性能观察LangChain.js 本身是请求编排层不承担模型推理计算所以资源占用逻辑和本地大模型部署完全不同。本地 Node 进程的内存消耗主要来自依赖加载、文档向量化过程中的中间对象、消息历史和缓存。不要用“显存占用”去衡量这个框架它不直接占用 GPU。性能瓶颈通常在三个位置模型服务端的响应时间、网络延迟、以及你的业务链路里是否有耗时操作比如文档解析、向量化。观察方式也很直接在invoke前后记录耗时对比不同模型、不同提示词长度下的延迟。用process.memoryUsage()观察 Node 进程内存检查是否随请求数增长而持续上升。在批量任务里打印每批次完成时间判断是否触发了速率限制。查看模型服务商的后台用量统计 token 消耗和成本。流式输出能显著改善用户感知延迟虽然总耗时不一定会变短但首字返回时间会明显缩短这对聊天类产品很重要。如果本地资源紧张优先减少并发数、缩短消息历史、限制单次输入长度。如果目标是低成本可以先用小型模型做粗筛再用大模型做精加工。8. LangChain.js 常见问题与排查方法问题现象可能原因排查方式解决方案npm install 安装失败Node 版本过低或网络问题检查 node -v查看 npm 日志升级 Node.js换 npm 镜像源重试启动报 Cannot find module依赖未安装或版本不匹配检查 package.json 和 node_modules重新安装依赖确认包名正确401 / 鉴权失败API Key 无效或未加载打印 process.env 检查环境变量确认 .env 文件存在且 key 正确返回 model not found模型名称不正确查看服务商文档核对模型名替换成实际可用的模型名称请求超时网络延迟或模型响应慢查看请求耗时和错误堆栈增加超时时间改用流式输出批量任务大量失败并发过高触发限流查看返回的状态码和错误消息降低并发数增加重试和退避机制结构化输出解析报错模型输出不符合格式要求打印模型原始输出调整提示词增加 few-shot 示例Ollama 连接不上本地模型服务未启动或地址错误检查 Ollama 进程和 baseUrl启动 Ollama确认端口和模型名这里有一个通用调试思路先把链路拆到最小。比如 RAG 链路出错不要直接怀疑整个链路而是分别测试文档加载、切分、向量化、检索、生成每一步的输出。LangChain.js 支持回调机制可以打印每一步的输入输出具体导入路径以安装的版本为准。逐段验证通常比全局猜测效率高很多。9. LangChain.js 最佳实践与使用建议第一密钥管理。.env文件要加入.gitignore密钥不要硬编码到代码里也不要在日志中打印完整 key。如果团队协作用环境变量或密钥管理服务统一分配。第二依赖版本锁定。LangChain.js 迭代速度很快接口时有调整。生产项目建议锁定主版本升级前先在测试环境跑通回归用例。文档里的代码在旧版本上可能出现导入路径变化这是正常现象按报错提示调整即可。第三提示词与代码分离。提示词模板单独维护不要散落在业务代码里。改动提示词时最好记录版本因为提示词对输出质量的影响往往比代码改动更明显。第四先小后大。第一次跑通项目时用最小的模型、最短的输入、最简单的链路确认环境没问题后再逐步加功能。这样能快速区分“环境问题”和“业务问题”。第五数据安全与合规。明确哪些数据可以发送到模型服务端哪些必须脱敏或过滤。对输出内容增加审核和复核机制特别是面向 C 端用户或对外发布的内容。使用第三方模型服务时确认服务商的数据处理条款是否符合你的合规要求。第六监控与成本。上线后要记录每次请求的 token 消耗、耗时、成功率。成本失控是大模型应用最容易被忽视的问题建议设置每日预算告警对批量任务设置单批上限。10. 总结与下一步LangChain.js 值得先跑通的目标是基础对话链路因为它验证了环境、依赖、模型访问这条最关键的路径。接下来再进 RAG因为知识库问答是绝大多数业务需求的基础。最后再尝试 Agent因为它依赖前两项的稳定性踩坑时也更容易定位。最容易踩的坑有三个一是依赖版本和文档不一致二是模型输出不稳定导致解析失败三是批量任务没有控制并发触发限流。这三个问题在本文的示例和排查表里都有对应处理方式遇到时按步骤来不要急着改业务逻辑。后续可以继续扩展的方向很多用 LangGraph 编排复杂工作流把内存存储换成 Redis 或数据库引入向量数据库支撑更大规模知识库接入 LangSmith 做链路观测或者把现有接口服务接到前端做真实产品。这篇文章的示例代码都适合作为起点按自己的业务改造即可。建议收藏备用构建第一个 LangChain.js 应用时拿出来对照。