langchain/classic 完整指南LangChain.js v1.0 中旧版抽象的兼容包定位、迁移路径与源码级实现【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs在 LangChain.js v1.0 的架构重构中原有的 legacy Chains、Indexing API 与大量社区集成被从主包langchain中剥离形成了独立维护的langchain/classic包。本文基于仓库内的 libs/langchain-classic/README.md 并结合包源码、依赖声明与新版 libs/langchain 的结构完整讲解这个兼容包的使用场景、安装依赖要求、模块构成、导入规范以及从旧版链式 API 迁移到 v1.0createAgent的实操路径帮助你在维护存量应用与启动新项目之间做出正确的选型决策。1. 包的定位为什么会有 langchain/classiclangchain/classic的官方定位是存放 LangChain.js v0.x 时代的功能这些功能在 v1.0 发布时被移出主包langchain。它存在的目的只有一个——为仍在使用旧抽象的既有应用提供向后兼容而核心的langchain包则聚焦于现代 Agent 开发所需的最小组件集合。这一点从新版主包的源码结构可以得到印证。libs/langchain/src/index.ts 的根导出只保留了消息类型BaseMessage、AIMessage、HumanMessage等、统一模型入口initChatModel、工具原语tool、StructuredTool、Agent 体系createAgent及其预置 middleware、InMemoryStore、Document与测试工具等必要组件完全不含LLMChain、SequentialChain这类旧版链。换言之v1.0 的 API 边界是通过瘦身主包 独立 classic 包这一物理拆分来实现的。当前仓库中该包的版本与基本元信息可在 libs/langchain-classic/package.json 中确认包名为langchain/classic描述为 Old abstractions from LangChain.js许可证为 MIT。2. 适用场景与禁用场景README 对何时使用给出了非常明确的边界。2.1 应当使用 langchain/classic 的情况如果你的项目满足以下任一条件就应使用langchain/classic存量代码使用 legacy chains例如LLMChain、ConversationalRetrievalQAChain、RetrievalQAChain使用 Indexing APIRecordManager及相关的向量化文档更新能力依赖此前从langchain主包再导出的langchain/community功能仍在维护既有应用、暂时不具备迁移到createAgent新 API 的条件。2.2 不应当使用的情况新项目直接用 langchain v1.0README 的立场非常直接新项目请使用langchainv1.0理由包括createAgent更简洁且功能更强的 Agent 构建方式支持 middleware 机制更好的性能面向现代 Agent 工作流优化更聚焦的 API 面复杂度更低、学习成本更小活跃开发新特性与改进将集中在 v1.0 API 上。新版 Agent 的实现位于 libs/langchain/src/agents/index.ts其周边还配套了完整的 middleware 体系HITL、上下文编辑、工具重试、模型回退等见 libs/langchain/src/agents/middleware这是 classic 包中旧版 agent executor 所不具备的。3. 安装与依赖要求基本安装方式npm install langchain/classic该包将langchain/core声明为 peer dependency需要单独安装npm install langchain/core结合 libs/langchain-classic/package.json 的声明还有几个实操中必须注意的依赖事实Node 版本engines要求node 20可选 peer 依赖cheerioHTML 解析、peggy表达式解析语法、typeormSQL 相关功能均标记为optional: true只在用到对应功能时才需要安装内置依赖包依赖langchain/openai、langchain/textsplitters以及handlebars、js-yaml、jsonpointer、openapi-types、yaml等工具库zod 双兼容zod的依赖声明为^3.25.76 || ^4即同时支持 zod v3 与 v4 项目可选依赖langsmith0.4.0 1.0.0作为 optionalDependency 引入用于 LangSmith 追踪集成。4. 包内容构成从 README 到源码逐一对照README 将包内容分为四类以下逐一展开并对照源码目录验证。4.1 Legacy Chains旧版链实现这是 classic 包最核心的部分README 列举了 v0.x 的全部链实现包括LLMChain—— 使用提示模板调用 LLM 的基础链ConversationalRetrievalQAChain—— 面向文档的会话式问答链RetrievalQAChain—— 无会话记忆的文档问答链StuffDocumentsChain—— 将文档整体塞入提示的文档组合链MapReduceDocumentsChain—— 对文档做 map-reduce 的链RefineDocumentsChain—— 对文档做迭代精炼的链。在源码目录 libs/langchain-classic/src/chains 中可以找到与之一一对应的实现llm_chain.ts、conversational_retrieval_chain.ts、retrieval_qa.ts、combine_documents/含stuff.ts、reduce.ts、question_answering/含 map-reduce、refine、stuff 三套提示词等。此外还包括sequential_chain.ts、conversation.ts、sql_db/、router/、constitutional_ai/、graph_qa/等旧版能力配套的单元测试与集成测试也一并保留如llm_chain.int.test.ts、retrieval_chain.test.ts。仓库的 examples/src/langchain-classic 目录下还保留了这些旧链的完整可运行示例chains、memory、callbacks、prompts 等子目录是理解 legacy API 用法的最好参照。4.2 Indexing API索引/文档增量更新README 说明包中包含RecordManager及相关索引能力用于管理向量库中文档的更新。从源码看libs/langchain-classic/src/indexes/index.ts 将index、CleanupMode、IndexOptions、_batch、_deduplicateInOrder等符号从langchain/core/indexing再导出即 classic 包通过langchain/classic/indexes入口提供索引能力。底层的RecordManager抽象定义在 libs/langchain-core/src/indexing/record_manager.ts其接口要求实现以下方法方法作用createSchema()在记录管理器中创建 schemagetTime()返回当前时间戳update(keys, { groupIds, timeAtLeast })更新键timeAtLeast提供乐观并发校验exists(keys)按序返回每个键是否已存在listKeys({ before, after, groupIds, limit })按时间/分组过滤列出键deleteKeys(keys)删除键这套记录管理器 文档哈希键的设计使增量索引可以幂等地重放index流程通过_deduplicateInOrder、_getSourceIdAssigner等内部工具同样从 indexes 入口导出计算文档源 ID 与哈希再用exists/update/deleteKeys判定新增、变更与删除这正是 v0.x 文档增量更新管线的工作机制。4.3 社区集成再导出README 提到包内包含此前从主包langchain可用、现归属于langchain/community的功能再导出。从源码结构看libs/langchain-classic/src/util/entrypoint_deprecation.ts 提供了带newPackageName: langchain/community的弃用提示工具用于在用户经由旧路径导入相关功能时提示新包位置chains/graph_qa/cypher.ts等文件同样携带该指向。这说明 classic 包对社区集成的角色是过渡性入口 明确的重定向提示而非长期承载这些集成的仓库。4.4 其他弃用功能README 概括为被 v1.0 中更优替代品取代的各类工具与抽象。结合 libs/langchain-classic/src 的目录结构与 package.json 的exports映射可以确认包内还完整保留了memory/BufferMemory、BufferWindowMemory、EntityMemory、SummaryMemory、VectorStoreMemory等旧版记忆实现output_parsers/StructuredOutputParser、CommaSeparatedListOutputParser、表达式解析基于peggy等retrievers/EnsembleRetriever、ParentDocumentRetriever、MultiQueryRetriever、SelfQueryRetriever等高级检索器evaluation/、experimental/autogpt、babyagi、generative_agents 等实验性 agentdocument_loaders/fs 目录、JSON/JSONL/文本加载器、agents/旧版 agent executor、ReAct/OpenAI tools 等 executor 工厂、storage/、vectorstores/memory内存向量库等。package.json 的exports映射把这些模块都暴露为规范的子路径入口例如./chains、./chains/combine_documents、./agents、./memory、./indexes、./evaluation、./retrievers/parent_document、./document_loaders/fs/directory、./cache/file_system等开发者可以按模块做细粒度导入而不必加载整个包。5. 导入规范入口警告与子路径入口README 的迁移示例展示了两类导入写法// 子路径入口 import { LLMChain } from langchain/classic/chains; import { ConversationalRetrievalQAChain } from langchain/classic/chains; // 根入口 import { LLMChain } from langchain/classic;这里需要结合源码补充一个重要的实现事实从源码结构看libs/langchain-classic/src/index.ts 的根入口当前只输出一条警告而不导出任何符号console.warn( [WARNING]: The root langchain entrypoint is empty. Please use a specific entrypoint instead. );也就是说运行时从根入口langchain/classic导入会得到空模块并看到该警告。因此实际编码时应当优先使用langchain/classic/chains、langchain/classic/memory、langchain/classic/indexes等具体子路径入口均可在 libs/langchain-classic/package.json 的exports字段中查到完整清单这也是源码警告明确建议的用法。6. 实战示例6.1 使用 LLMChainREADME 给出的标准示例import { LLMChain } from langchain/classic/chains; import { ChatOpenAI } from langchain/openai; import { PromptTemplate } from langchain/core/prompts; const model new ChatOpenAI({ model: gpt-4 }); const prompt PromptTemplate.fromTemplate( Tell me a {adjective} joke about {content}. ); const chain new LLMChain({ llm: model, prompt }); const result await chain.call({ adjective: funny, content: chickens, }); console.log(result.text);结合 libs/langchain-classic/src/chains/llm_chain.ts 的源码这个示例背后的关键机制是输入/输出键LLMChain的inputKeys直接取prompt.inputVariablesoutputKey默认为text可由构造参数覆盖这就是示例中result.text的来源callKeys 分流_call见 llm_chain.ts#L185-L229call()传入的参数中属于模型callKeys的键如temperature会被分流给模型调用参数其余键交给提示模板渲染两种执行路径若模型实现了generatePrompt走generatePrompt生成后再经 outputParser 解析否则将llm.pipe(outputParser)组成 runnable 后invokeoutputParser 约束构造时若同时设置了outputParser与prompt.outputParser会直接抛错二者只能取其一便捷方法predictllm_chain.ts#L243-L249等价于call后直接返回output[outputKey]省去取键操作序列化支持LLMChain实现lc_serializable可通过serialize()/static deserialize()参与 LangChain 的 JSON 序列化体系_chainType()返回llm。6.2 使用 ConversationalRetrievalQAChainREADME 给出的会话式 RAG 示例import { ConversationalRetrievalQAChain } from langchain/classic/chains; import { ChatOpenAI } from langchain/openai; import { OpenAIEmbeddings } from langchain/openai; import { MemoryVectorStore } from langchain/vectorstores/memory; // 创建向量库 const vectorStore await MemoryVectorStore.fromTexts( [Document 1 text..., Document 2 text...], [{ id: 1 }, { id: 2 }], new OpenAIEmbeddings() ); // 创建链 const model new ChatOpenAI({ model: gpt-4 }); const chain ConversationalRetrievalQAChain.fromLLM( model, vectorStore.asRetriever() ); // 调用 const result await chain.call({ question: What is in the documents?, chat_history: [], }); console.log(result.text);源码 libs/langchain-classic/src/chains/conversational_retrieval_chain.ts 揭示了它的内部结构该链由三部分组合——retriever检索器、combineDocumentsChain文档组合链即 Stuff/MapReduce/Refine 之一与questionGeneratorChain一个LLMChain输入键默认是question与chat_history。其中问题改写使用的默认模板conversational_retrieval_chain.ts#L15-L20为Given the following conversation and a follow up question, rephrase the follow up question to be a standalone question. Chat History: {chat_history} Follow Up Input: {question} Standalone question:即每次调用先用 LLMChain 把带指代/省略的追问改写为独立问题再交给检索器与文档组合链作答。源码 JSDoc 还给出了更精细的等价写法用createHistoryAwareRetriever处理问题改写、用createStuffDocumentsChain与createRetrievalChain组合完成 RAG均从langchain/classic/chains/...子路径导入说明ConversationalRetrievalQAChain本质上是历史感知检索器 文档组合链 检索链这三块可独立替换的构件。7. 从旧版链迁移到 createAgentREADME 建议新开发请直接使用createAgent替代 legacy chains。其给出的LLMChain→createAgent迁移对照// Before (using LLMChain) import { LLMChain } from langchain/classic/chains; import { ChatOpenAI } from langchain/openai; import { PromptTemplate } from langchain/core/prompts; const model new ChatOpenAI({ model: gpt-4 }); const prompt PromptTemplate.fromTemplate( What is a good name for a company that makes {product}? ); const chain new LLMChain({ llm: model, prompt }); const result await chain.call({ product: colorful socks }); // After (using createAgent) import { createAgent } from langchain; const agent createAgent({ model: openai:gpt-4, systemPrompt: You are a creative assistant that helps name companies., }); const result await agent.invoke({ messages: [ { role: user, content: What is a good name for a company that makes colorful socks?, }, ], });两者的范式差异值得注意输入形态LLMChain接收与模板变量对应的扁平键值对象{ product: ... }而createAgent接收消息列表{ messages: [...] }角色system/user由消息结构显式表达模型指定旧 API 需要实例化具体的 provider 模型类ChatOpenAI新 API 支持openai:gpt-4这样的统一模型串配合主包的initChatModel体系扩展方式旧链通过 memory、outputParser、callback 等参数拼装行为新 Agent 通过 middleware 组合行为实现与测试可独立演化。createAgent的具体实现与类型定义位于 libs/langchain/src/agents/index.ts配套的 middleware如toolRetry、summarization、hitl等位于 libs/langchain/src/agents/middleware更复杂的迁移场景可参考仓库中 examples/src/createAgent 目录下按主题组织的示例streaming、structuredOutput、middleware 各场景等。8. 维护策略与配套资源README 明确了langchain/classic的维护政策——它处于维护模式会接收关键 bug 修复会接收安全漏洞补丁不再增加新特性新能力集中在langchainv1.0 API 上。这意味着选型逻辑很清晰存量 legacy 应用继续用 classic 包并保持补丁更新任何新增功能模块都建议直接落在 v1.0 API 上。包内其他可继续深入的资源变更历史libs/langchain-classic/CHANGELOG.md完整可运行示例旧链、记忆、回调、提示词等examples/src/langchain-classic许可证MIT见仓库根目录 LICENSE。9. 小结langchain/classic是 LangChain.js v1.0 架构演进中的兼容性落点它原样保留了 v0.x 的 legacy chains、Indexing API、社区集成再导出与各类弃用抽象并通过规范的子路径入口暴露如langchain/classic/chains、langchain/classic/indexes同时以维护模式仅修 bug 与安全补丁运行。掌握它的关键在于三点其一明确它与新版langchain主包的边界——新项目用createAgent存量应用用它其二注意根入口仅有警告输出务必使用具体子路径导入其三理解LLMChain的键值分流与ConversationalRetrievalQAChain的三段式内部结构后才能判断哪些旧代码值得保留、哪些可以平滑改写为新的 Agent API。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考