LangChain-ts开发环境搭建：从Node.js版本管理到第一个AI应用

1. 项目缘起为什么从LangChain-ts开始如果你和我一样最近在捣鼓大语言模型应用开发大概率会听到一个名字LangChain。这个框架几乎成了连接LLM与外部世界事实上的标准。但当你兴冲冲地打开官方文档准备大干一场时可能会发现一个尴尬的现实——绝大多数教程、示例和社区讨论都围绕着Python版本展开。对于像我这样项目技术栈以Node.js为主或者单纯就是更喜欢TypeScript的静态类型安全和现代前端生态的开发者来说这无疑是个门槛。这就是我决定系统学习并记录LangChain-ts即LangChain的TypeScript/JavaScript版本的初衷。Python生态固然强大但Node.js在Web服务、CLI工具、桌面应用如Electron以及需要与现有前端/全栈项目无缝集成的场景下有着不可替代的优势。LangChain-ts正是为了填补这一空白而生。然而它的中文资料相对匮乏环境配置的细节也散落在官方文档和各个Issue中。因此这个系列的第一篇我们不谈高深的Agent或复杂的RAG管道就从最基础、也最容易踩坑的一步开始环境安装与配置。我会把我从零搭建一个可运行、可调试的LangChain-ts开发环境过程中遇到的所有问题、选择的方案以及背后的考量毫无保留地分享出来。2. 核心工具链选型与底层逻辑在动手安装任何包之前我们需要先理清整个技术栈的依赖关系。LangChain-ts不是一个孤立的库它运行在Node.js的生态之上并且严重依赖一系列现代JavaScript开发工具。盲目地npm install很可能导致版本冲突、类型错误或者构建失败。2.1 Node.js版本管理为什么不用系统自带的Node很多新手会直接使用操作系统自带的Node.js或者从官网下载一个安装包。这为后续的依赖管理埋下了巨大的隐患。不同的项目可能需要不同版本的Node.js而系统级的全局安装无法做到隔离。我的选择是nvmNode Version Manager。这是一个命令行工具允许你在同一台机器上安装和切换多个Node.js版本。它的优势显而易见项目隔离为每个项目目录指定一个Node版本互不干扰。安全便捷安装和切换版本无需sudo权限避免污染系统目录。社区主流是Node.js社区事实上的标准版本管理工具。对于macOS或Linux用户安装nvm非常方便。打开终端使用官方安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重启终端或执行source ~/.zshrc或~/.bashrc使配置生效。然后安装一个与LangChain-ts兼容的Node.js长期支持版本。我推荐使用Node.js 18.x或20.x的LTS版本因为它们提供了最佳的稳定性和生态兼容性。nvm install 18 nvm use 18你可以通过node -v和npm -v来验证安装是否成功。注意Windows用户可以使用nvm-windows这个移植版本但请注意其命令和路径可能与原生nvm略有不同。另一个强大的跨平台选择是fnmFast Node Manager速度更快用法类似。2.2 包管理器的抉择npm, yarn, 还是 pnpmNode.js自带npm但近年来yarn和pnpm因其更好的性能、更严格的依赖锁和更优的磁盘空间管理而备受青睐。对于LangChain-ts项目我的建议是pnpm。为什么是pnpm磁盘效率pnpm使用硬链接和符号链接在全局存储中管理依赖同一个版本的包在磁盘上只保存一份可以节省大量空间。这对于LangChain这类依赖树可能较深包含各种LLM SDK、向量数据库客户端等的项目尤其有益。安装速度得益于其独特的链接机制pnpm的安装速度通常比npm和yarn v1更快。严格性pnpm默认创建非扁平化的node_modules结构这能更好地避免幽灵依赖即使用了一个未在package.json中声明的包的问题让依赖关系更清晰可预测。安装pnpm很简单假设你已安装Node.jsnpm install -g pnpm之后在项目中使用pnpm init来初始化项目用pnpm add来安装包。当然使用npm或yarnv1或berry也完全可行。关键在于锁定依赖版本。无论你选择哪个请务必确保生成的锁文件package-lock.json,yarn.lock,pnpm-lock.yaml被提交到版本控制中这是保证团队协作和线上部署一致性的生命线。2.3 TypeScript配置不仅仅是tscLangChain-ts是用TypeScript编写的这意味着我们的项目也需要配置TypeScript编译器。这一步是类型安全的核心。首先在项目根目录初始化TypeScript配置pnpm add -D typescript types/node pnpm tsc --init这会生成一个tsconfig.json文件。官方提供的配置可能很庞大我们需要根据LangChain-ts应用的特点进行优化。下面是一个针对Node.js后端或工具类项目的推荐配置{ compilerOptions: { target: ES2022, module: commonjs, lib: [ES2022], outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true, moduleResolution: node, allowSyntheticDefaultImports: true, declaration: true, declarationMap: true, sourceMap: true }, include: [src/**/*], exclude: [node_modules, dist, **/*.test.ts] }关键配置项解析target: ES2022编译目标ECMAScript版本。ES2022提供了很多现代语法特性且Node.js 18完全支持。module: commonjs对于Node.js环境CommonJS模块系统仍然是最稳定、兼容性最好的选择。如果你确定你的环境支持ES Modules如使用了--experimental-modules标志或较新版本可以尝试node16或nodenext。rootDir与outDir清晰地分离源代码src和编译输出dist保持项目结构整洁。skipLibCheck: true这是一个重要的性能优化选项。它会跳过对.d.ts类型声明文件的类型检查。像LangChain这样依赖众多的大型库开启全类型检查会极大拖慢编译速度。对于应用开发开启此选项是安全且通用的做法。resolveJsonModule: true允许直接导入JSON文件。这在读取配置文件如API密钥时非常有用。2.4 开发体验增强ESLint与Prettier对于严肃的项目代码质量和风格一致性必不可少。ESLint负责检查代码中的潜在问题和风格问题Prettier则专注于代码的自动格式化。安装与配置pnpm add -D eslint typescript-eslint/parser typescript-eslint/eslint-plugin prettier eslint-config-prettiereslint: ESLint核心。typescript-eslint/parser: 使ESLint能解析TypeScript语法。typescript-eslint/eslint-plugin: 提供针对TypeScript的linting规则。prettier: 代码格式化工具。eslint-config-prettier: 关闭所有与Prettier冲突的ESLint规则让两者和谐共处。创建.eslintrc.js配置文件module.exports { parser: typescript-eslint/parser, extends: [ eslint:recommended, plugin:typescript-eslint/recommended, prettier // 必须放在最后用于覆盖冲突规则 ], plugins: [typescript-eslint], env: { node: true, es2022: true }, parserOptions: { ecmaVersion: latest, sourceType: module }, rules: { // 可以在这里添加或覆盖规则 typescript-eslint/no-explicit-any: warn, // 将any警告而不是报错 } };创建.prettierrc配置文件{ semi: true, trailingComma: es5, singleQuote: true, printWidth: 100, tabWidth: 2 }最后在package.json中添加脚本方便使用{ scripts: { lint: eslint src --ext .ts, lint:fix: eslint src --ext .ts --fix, format: prettier --write \src/**/*.ts\, build: tsc, dev: tsc --watch } }3. LangChain-ts核心库安装与版本策略基础环境就绪后终于可以安装LangChain-ts了。这里有一个非常重要的概念LangChain-ts是一个由众多独立包组成的模块化框架。你不需要安装一个庞大的langchain包而是按需安装你需要的功能模块。3.1 理解包结构langchain/core 与 langchain/community从LangChain v0.1.0开始其架构进行了重大重构核心思想是分离关注点langchain/core这是框架的绝对核心。它定义了最基础的抽象如BaseLanguageModel、BaseChatModel、BaseRetriever、BaseTool等以及链条Chain、提示词模板PromptTemplate的核心逻辑。几乎任何LangChain应用都需要安装它。langchain/integration这些是具体的集成包。例如langchain/openai: 集成OpenAI的GPT系列模型。langchain/google-genai: 集成Google的Gemini模型。langchain/anthropic: 集成Claude模型。langchain/community: 这是一个“大杂烩”包包含了大量第三方集成比如各种向量数据库Chroma, Pinecone、文档加载器PDF, CSV、工具SerpAPI, Wikipedia等。对于初期探索安装这个包很方便但对于生产环境建议只安装你需要的特定社区包以减少依赖体积。langchain这是一个“伞包”umbrella package它本身不包含太多代码主要作用是重新导出re-export其他所有官方包如core, openai等的API。对于新手或者想快速开始不想操心具体包名的场景安装这个包最简单。但它会引入大量你可能用不到的依赖。我的安装建议对于学习和中型项目一个平衡的方案是安装核心包、你计划使用的LLM提供商包以及社区包。pnpm add langchain/core langchain/openai langchain/community如果你想从最精简开始可以只安装核心和OpenAIpnpm add langchain/core langchain/openai3.2 版本管理与依赖解析LangChain生态迭代非常快保持版本一致性至关重要。强烈建议在安装时指定主版本号并利用锁文件。pnpm add langchain/core^0.1.0 langchain/openai^0.0.10这里的^符号表示允许安装最新的次要版本和补丁版本如0.1.x但不会跳到0.2.0。这能在获得错误修复和新功能的同时避免破坏性变更。安装后你的package.json会类似这样{ dependencies: { langchain/core: ^0.1.0, langchain/openai: ^0.0.10, langchain/community: ^0.0.10 } }而pnpm-lock.yaml或等价的锁文件则锁定了所有传递依赖的确切版本这是项目可复现性的关键。踩坑记录我曾经在一个项目中混合使用了langchain伞包和独立的langchain/openai包由于它们内部引用的langchain/core版本有细微差异导致了难以追踪的运行时类型错误。教训是在一个项目中尽量统一使用一种引用方式要么全部用独立包要么只用伞包并确保所有LangChain相关包的主版本号一致。4. 环境变量管理与API密钥安全任何LLM应用都绕不开API密钥。像OpenAI API Key这样的敏感信息绝对不能硬编码在源代码中否则一旦代码泄露后果不堪设想。标准做法是使用环境变量。4.1 使用dotenv管理本地环境在开发环境中我们使用dotenv库来从.env文件加载环境变量。pnpm add dotenv在项目根目录创建.env文件OPENAI_API_KEYsk-your-actual-openai-api-key-here ANTHROPIC_API_KEYyour-anthropic-key LANGSMITH_API_KEYyour-langsmith-key # 其他配置...重要务必在.gitignore文件中添加.env防止将其提交到版本库。# .gitignore node_modules dist .env .env.local在你的应用入口文件如src/index.ts的最顶部加载配置import * as dotenv from dotenv; dotenv.config(); // 这会读取项目根目录的.env文件 // 现在可以通过 process.env 访问 const openAIApiKey process.env.OPENAI_API_KEY; if (!openAIApiKey) { throw new Error(OPENAI_API_KEY is not defined in environment variables.); }4.2 结构化配置与验证对于更复杂的项目直接使用process.env会显得散乱且缺乏验证。我推荐使用zod这个强大的模式验证库来定义和验证环境变量模式。pnpm add zod创建一个专门的配置文件例如src/config.tsimport { z } from zod; import * as dotenv from dotenv; dotenv.config(); const envSchema z.object({ OPENAI_API_KEY: z.string().min(1, OpenAI API key is required), ANTHROPIC_API_KEY: z.string().optional(), // 可选 LANGSMITH_TRACING: z.enum([true, false]).default(false).transform(val val true), LOG_LEVEL: z.enum([error, warn, info, debug]).default(info), }); // 解析并验证环境变量 const envParseResult envSchema.safeParse(process.env); if (!envParseResult.success) { console.error(❌ Invalid environment variables:, envParseResult.error.format()); process.exit(1); // 验证失败退出应用 } export const env envParseResult.data;这样在你的应用代码中你就可以从env对象中安全地、带有类型提示地访问配置了import { env } from ./config; const llm new ChatOpenAI({ apiKey: env.OPENAI_API_KEY, model: gpt-4, }); if (env.LANGSMITH_TRACING) { // 启用LangSmith追踪 }这种方式将配置集中管理提供了运行时验证和完整的TypeScript类型支持是生产级应用的最佳实践。5. 可选但推荐的组件LangSmith集成与调试当你开始构建复杂的LangChain应用时调试会变得困难。链条Chain的输入输出、工具Tool的调用、LLM的请求和响应这些信息如果只靠console.log会非常低效。LangSmith是LangChain官方推出的一个平台用于追踪、调试和评估LLM应用。它提供了一个可视化的界面让你可以清晰地看到每一次执行的完整链路包括每个步骤的输入、输出、耗时、token使用量以及发生的任何错误。5.1 注册与配置LangSmith访问 smith.langchain.com 并注册一个账户通常可以使用GitHub账号。在设置页面创建一个API密钥。在你的.env文件中添加这个密钥LANGSMITH_API_KEYlsv2_your_actual_langsmith_api_key LANGSMITH_TRACINGtrue # 启用追踪 LANGSMITH_PROJECTmy-first-langchain-project # 设置项目名便于在界面中分类查看安装LangSmith SDKpnpm add langsmith/langsmith在你的应用初始化代码中通常在入口文件的最开始配置LangSmith。根据官方文档在LangChain v0.1.x中通常是通过设置环境变量自动集成的但为了更明确的控制可以手动初始化import { Client } from langsmith/langsmith; // 如果环境变量已设置以下代码是可选的但显式初始化更清晰 if (process.env.LANGSMITH_API_KEY) { // LangChain内部会自动读取 LANGSMITH_API_KEY 和 LANGSMITH_TRACING 等环境变量 // 你也可以手动创建client用于更复杂的操作 const client new Client({ apiKey: process.env.LANGSMITH_API_KEY, }); console.log(LangSmith tracing is enabled.); }5.2 在开发中利用LangSmith配置完成后运行你的LangChain应用。所有对LLM的调用、链的执行都会被自动记录并发送到LangSmith平台。你可以查看Trace列表在LangSmith网页界面可以看到所有历史执行的概览。深入单个Trace点击任何一个执行记录可以看到详细的流程图展开每个节点查看具体的输入Prompt、输出Response、使用的模型、消耗的token和耗时。调试与复现如果某次调用出错了你可以直接在LangSmith里看到错误堆栈和上下文甚至可以复制这次调用的确切参数在本地或Playground中复现问题。比较不同Prompt或模型通过为不同的运行设置标签Tags或元数据Metadata你可以横向比较不同配置下的效果和成本。对于初学者即使只是运行一些简单的示例打开LangSmith追踪也能极大地帮助你理解LangChain内部的工作流程直观地看到你的提示词模板被渲染成什么样子LLM到底接收到了什么信息。这比任何文字描述都来得有效。6. 验证环境创建并运行你的第一个LangChain-ts脚本理论说了这么多是时候动手验证一下我们的环境是否真正工作了。我们来创建一个最简单的脚本使用OpenAI的Chat模型进行一次对话。6.1 项目结构初始化首先确保你的项目结构如下my-langchain-project/ ├── .env # 环境变量已加入.gitignore ├── .eslintrc.js # ESLint配置 ├── .prettierrc # Prettier配置 ├── .gitignore ├── package.json ├── pnpm-lock.yaml # 或 package-lock.json, yarn.lock ├── tsconfig.json ├── src/ │ ├── config.ts # 环境配置可选但推荐 │ └── index.ts # 主入口文件 └── dist/ # TypeScript编译输出目录6.2 编写第一个脚本在src/index.ts中写入以下代码// 加载环境变量 import * as dotenv from dotenv; dotenv.config(); import { ChatOpenAI } from langchain/openai; import { HumanMessage } from langchain/core/messages; async function main() { // 1. 初始化Chat模型 // 确保你的.env文件中有 OPENAI_API_KEY const chatModel new ChatOpenAI({ model: gpt-3.5-turbo, // 或 gpt-4 temperature: 0.7, verbose: true, // 在控制台输出详细日志有助于调试 }); // 2. 构造消息 const messages [new HumanMessage(用一句话介绍你自己。)]; // 3. 调用模型 console.log(正在调用LLM...); const response await chatModel.invoke(messages); // 4. 处理响应 console.log(\n--- AI回复 ---); console.log(response.content); console.log(--- 结束 ---\n); // 5. 查看响应元数据如token使用情况 console.log(响应元数据:, JSON.stringify(response.response_metadata, null, 2)); } main().catch(console.error);6.3 运行与调试编译TypeScript运行pnpm build这会将src/index.ts编译到dist/index.js。直接运行Nodenode dist/index.js。使用ts-node进行开发推荐为了在开发时实现更快的热重载循环我们可以使用ts-node和nodemon。pnpm add -D ts-node nodemon在package.json中添加开发脚本{ scripts: { dev: nodemon --watch src/**/*.ts --exec ts-node src/index.ts } }现在只需运行pnpm devnodemon会监视src目录下的所有.ts文件变化并自动用ts-node重新执行你的脚本。ts-node会在内存中直接执行TypeScript省去了手动编译的步骤。运行脚本后你应该在控制台看到类似以下的输出正在调用LLM... --- AI回复 --- 我是OpenAI开发的AI语言模型旨在通过理解和生成自然文本来协助用户解决问题、提供信息或进行对话。 --- 结束 --- 响应元数据: { tokenUsage: { completionTokens: 28, promptTokens: 10, totalTokens: 38 }, finishReason: stop, model_name: gpt-3.5-turbo-0613 }看到AI的回复和token使用统计恭喜你你的LangChain-ts开发环境已经成功搭建并运行起来了。实操心得第一次运行时如果遇到API key not valid之类的错误请首先检查1).env文件是否在项目根目录2) 变量名OPENAI_API_KEY是否拼写正确3) API密钥本身是否有效且未过期。如果使用了代理网络可能还需要配置OPENAI_PROXY环境变量或使用自定义的baseURL参数。调试这类网络问题开启verbose: true并查看详细的请求日志会非常有帮助。