这段时间接连做了两个和文档处理相关的小项目绕不开一套叫 LangChain 的框架干脆把官方文档、源码和社区案例过了一遍顺手输出了这份学习笔记。如果你也是刚开始接触大语言模型应用开发想把模型能力真正接到业务里而不是停留在“调 API 的示例代码”阶段那 LangChain 几乎是绕不开的一座桥。它本身不直接提供模型也不帮你炼丹它做的是把“调用模型”这件事扩展成“组合模型能力”一整条链路。这篇文章不会逐条翻译官方文档而是按我实际学习的顺序把组件拆开讲清楚再带一个文档问答的实战最后附上那些文档里看不出来的坑。1. LangChain 是什么为什么值得花时间学1.1 从“调 API”到“编排应用”的思维转变先说一个很多人都会有的误解LangChain 是“方便调大语言模型接口的工具包”。其实调接口那一步它并没有简化多少无非是封装了一层让你少写几个请求头。真正值钱的是它把“从输入到输出”这条业务链路拆成了一个个可组合的环节。什么叫链路拿一个最简单的文档问答举例。用户问“报销流程是什么”背后至少要做这几件事读取文档内容、把内容切成小块、把块转成向量、根据问题做相似度检索、把检索结果和问题拼成一段提示词、送给模型生成答案、再把答案格式化返回。如果只调模型 API你从第一步就得自己写每一步都会有各自的数据格式和异常情况。LangChain 做的事情是把这些步骤抽象成组件然后用一条链把它们串起来。这种思维转变很关键。我之前带的一个实习生一开始写的代码把所有逻辑都塞在一个函数里能跑但换个文档格式、换套检索策略就得重写。用 LangChain 之后加载器换一个、检索器换一个链的骨架完全不用动。所以学这个框架学到的不只是 API更是一种“组件化编排”的设计思路。1.2 LangChain 解决的三类核心问题我自己的实践感受LangChain 真正在解决的是下面三件事。第一多模型切换的统一入口。不同厂商的模型接口风格、参数名、返回结构各不相同。用 LangChain 的模型层做一层封装之后上层业务拿到的都是一个统一的“invoke”接口。切换模型时多数情况下只需要改配置不用改业务逻辑。总比哪天真要替换模型厂商结果发现每个调用处都要改一遍好得多。第二有状态对话的实现成本。大语言模型接口本身没有记忆每次调用都是一次全新的请求。你要做多轮对话就得自己维护历史消息、决定截断策略、控制 tokens 占用。LangChain 把记忆做成了组件你可以选侧缓冲、摘要型、还是混合型细节被封装掉了一大部分。第三模型与外部世界的连接。模型只会“想”不会“做”它没法查数据库、没法查实时信息、没法调用业务接口。Agent 和工具机制解决了这个问题模型根据任务决定调用哪个工具、传什么参数拿到结果之后再继续推理。这套机制往小了说是“给模型加技能”往大了说就是智能体的雏形。1.3 适合谁来学学到什么程度给一个比较实际的判断标准。如果你满足下面三个条件LangChain 值得系统性学一遍有 Python 基础写过简单的函数和类调过大语言模型的接口理解“输入提示词-得到回复”这个过程手里的项目开始需要接入多个模型能力、或者要处理文档检索、多轮对话这些稍微复杂一点的需求。反过来如果你只是想在笔记本上跑一个单次问答示例那直接调模型接口更快没必要被框架绊住。我的建议是先理解组件再背 API。不要一上来就把整个框架的功能列表背一遍而是带着自己项目的需求用到哪个模块就学哪个模块学的时候顺手读一读对应源码。这样学一遍下来框架是长在自己身上的而不是飘在文档里。2. 核心模块逐个拆解LangChain 的模块划分其实很清晰我建议按下面的顺序去理解模型接入、Prompt 模板、输出解析、链、记忆、Agent。这六个模块也是绝大多数应用的基础。2.1 模型接入层把各家模型藏在统一接口后面模型层是入门的第一步但也是最容易学完就忘的一层。先说清楚它的定位LangChain 定义了一套统一接口各家模型通过适配器接入。你可以理解为“统一的充电接口”接口长什么样由框架定义能不能充电由厂商适配器决定。代码上大概长这样from langchain.chat_models import create_chat_model # 通过配置指定厂商和模型名 llm create_chat_model( provider某个模型厂商, model某个模型版本, temperature0.7, ) response llm.invoke(用一句话解释什么是向量数据库) print(response.content)这段代码里provider换成哪家厂商模型名换成对应版本上层代码完全不用改。我自己常用的做法是写一个函数根据环境变量去加载模型配置这样测试环境用便宜的小模型生产环境切大模型业务代码一行不动。不过这里有个要注意的地方不要为了“统一”把所有能力都磨平。比如有的模型支持额外的工具调用格式有的模型有特殊的停止序列设置这些差异在统一接口里不一定暴露出来。我踩过的坑是换了一个模型之后原来能稳定输出的 JSON 格式彻底乱了因为新模型的输出习惯和旧模型不一样。所以模型层统一的是调用方式不是模型能力。你自己得记录每个模型的特性和坑不能完全依赖框架层屏蔽。2.2 Prompt 模板把提示词变成可复用资产很多人写提示词是“写死在代码里”的比如直接在字符串里拼接。这种方式在小 demo 里没问题但一旦提示词变长、需要多处复用就会非常痛苦。Prompt 模板解决的就是这件事把提示词结构和变量分开。from langchain.prompts import ChatPromptTemplate template ChatPromptTemplate.from_messages([ (system, 你是一个严谨的技术助手只能根据提供的资料回答资料里没有的内容就说不知道。), (human, 资料如下\n{context}\n\n我的问题是{question}), ]) messages template.format_messages( context向量数据库是用于存储和检索向量的数据库。, question什么是向量数据库, )模板的最大价值不是省那几行拼接代码而是把提示词变成了可以管理的资产。你可以把不同场景的模板放进单独的文件按版本管理可以给模板写单元测试专门验证“变量缺失时的表现”可以在团队里沉淀一套“高质量提示词模板库”新同事不用从空白开始编提示词。用模板还有个隐藏好处变少了还要实现容易在保留字、分隔符、示例格式上犯低级错误。比如模板里的变量名和后面传入的参数名不一致大多数时候不会报错只是那个位置变成空字符串。这种错误排查起来比较隐蔽所以模板最好固定写法在每个链的关键位置主动做一次变量完整性的检查。2.3 输出解析与结构化返回大语言模型返回的是字符串但业务系统要的是结构化数据。你不能让下游接一个“纯文本回复”就完事更可靠的做法是让模型按约定格式输出然后做校验和解析。LangChain 的输出解析器就是这个角色。一个常见方案是让模型输出 JSON然后用解析器转成 Python 对象from langchain_core.output_parsers import JsonOutputParser from pydantic import BaseModel class Answer(BaseModel): summary: str confidence: float sources: list[str] parser JsonOutputParser(pydantic_objectAnswer) result parser.parse(model_output)这段代码用到了参数校验库它会在解析失败时给出比较具体的错误信息。但我要提醒一点解析器的可靠性上限取决于模型输出质量。你指望模型一次就输出完美的 JSON那大概率会出问题。实战中我会在提示词里给出一个“输出示例”让模型照着样子来同时解析失败时加一次重试让模型根据错误信息自我修正成功率高很多。结构化输出的意义不只是方便解析更重要的是让后续流程变得可控。比如我可以让模型先输出一个“是否需要查询额外信息”的布尔字段然后根据这个字段决定走哪条分支这比从纯文本里猜意图要稳得多。2.4 链的组装与执行流程链Chain是 LangChain 的灵魂。理解链之前先理解一个概念某个模块的“可运行接口”——你给它输入它返回输出如果你把这个输入输出串起来一条链就是若干可运行单元的管道。LangChain 新版本推荐的写法是用管道符类似 Unix 管道。from langchain_core.runnables import RunnablePassthrough chain ( {context: retriever, question: RunnablePassthrough()} | template | llm | parser )这条链的意思是先把从外部拿到的 question 原样传给后续同时用 retriever 检索出 context然后组装 prompt再送给模型最后解析输出。你可以把它读成“数据从左边流到右边每一站只做一件事”。这种写法的好处很明显。想加一个“过滤敏感词”的步骤就往管道里插一个函数。想替换检索策略就换掉retriever这个对象。几乎所有组件都遵循同一套协议所以可以随意拼接而不用给每个组合方式单独写胶水代码。不过链也不一定越复杂越好。我见过有人把十来个步骤串成一条巨链最后排查问题时根本不知道哪一步出了问题。我的建议是链里只保留必须的步骤能拆成两条链的就不要硬合成一条在关键节点加回调或者日志输出方便定位。2.5 记忆机制让对话有上下文大模型接口是无状态的而聊天需要有状态。记忆模块解决的就是“把历史对话存下来、在合适的时机放回去”。LangChain 提供了几种记忆形式缓冲记忆把最近 N 轮对话原样塞进提示词摘要记忆把历史对话压缩成摘要再放进提示词混合记忆最近几轮用原文更早的用摘要。以缓冲记忆为例from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory( return_messagesTrue, k5, # 保留最近 5 轮 )它会自动把你和模型之间的问答存下来在下一轮组装提示词时附上。用起来确实方便但千万别忽略 token 成本。每轮会话都带着历史一起发给模型输入 tokens 会随着轮数增长。如果用户聊了 30 轮每轮都很长成本可能翻好几倍。我实际项目里更常用摘要记忆或者干脆自己控制历史窗口。实现上也没那么神秘如果只想保留最近三轮就在提示词模板里拼上最近的对话记录如果想用摘要就在每轮结束后让模型把上一轮内容压缩成摘要存起来。记忆选型的核心就一句话在你的场景里用户需要记住多久以前的上下文为此你愿意付出多少 token 成本。2.6 Agent 与工具调用让模型具备行动力Agent 是 LangChain 里概念上最“高级”的组件也是很多人学得云里雾里的一块。它的直觉解释是模型不直接给你最终答案而是先决定做什么、用什么工具、得到什么结果再决定下一步。整个过程可能循环多轮直到它认为任务完成。一个最简单的工具调用示例from langchain.tools import tool tool def calculator(expression: str) - str: 对简单的数学表达式求值。 return str(eval(expression, {__builtins__: {}}, {})) agent create_agent( llmllm, tools[calculator], max_rounds5, )这个 Agent 收到“12 乘以 18 等于多少”时会调用 calculator 工具拿到结果再生成最终回答。这比让模型直接心算要可靠得多因为模型在数学运算上并不擅长。但 Agent 的“自由”也意味着风险模型可能在循环里反复调用工具迟迟不收敛可能传错参数可能被骗去调用危险操作。所以用 Agent 的第一原则就是凡是模型能接触的工具都要做权限控制和调用限制任何时候都要设置最大循环轮数关键动作必须有审计日志。免费的“让模型自己决定”代价往往是不可控的成本和安全风险。3. 实战拿一个文档问答系统练手理论部分讲完还是得动手。下面这个文档问答系统是我给一个模拟项目做的叫它“内部知识库问答”。目标很简单把一堆 Markdown 文档变成一个能聊天的知识库新来的同事问“报销流程是什么”系统能从文档里找出答案。3.1 场景设计与数据准备一开始不要贪多我准备了大约 30 篇 Markdown 文档内容涵盖报销、请假、出差、采购、会议制度加起来大概 20 万字。这个规模对个人电脑来说完全跑得动又能覆盖大多数真实问题。场景就这么定用户向系统提问系统返回答案并在答案后面附上引用来源。要求是“只基于文档回答文档里没有的内容要明确说不知道”。这个限制很重要没有它,模型就会开始自由发挥把文档问答变成“模型常识问答”那就失去意义了。3.2 切片、向量化与检索这是整个系统里最影响效果的一环重要性超过模型本身。我当时的做法加载文档按标题拆成大段落再把长段落按固定大小切块这里设了块大小 500 个字符重叠 50 个字符对每个块做向量化得到向量并写入向量库提问时把问题转成向量检索最相似的 4 个块。切片为什么要设重叠因为一段话可能被硬生生截断后半句的问题可能丢失上下文。加 50 个字符的重叠虽然会有一点重复存储但能明显减少信息断裂。块大小为什么要 500块太大检索返回的结果不够精准模型输入也浪费 token块太小上下文不完整模型很难理解。500 是一个先试出来的初始值你可以看检索效果再调。向量库这块我用了最简单的本地版本数据量再大一些再用持久化版本。这一步不要纠结工具选型关键是跑通链路。3.3 组装问答链核心代码如下retriever vector_store.as_retriever( search_typesimilarity, search_kwargs{k: 4}, ) chain ( { context: retriever, question: RunnablePassthrough(), } | ChatPromptTemplate.from_messages([ (system, 你是一个知识库助手只能基于给定的资料回答。资料不足时回答资料中没有相关信息。), (human, 资料\n{context}\n\n问题{question}), ]) | llm ) resp chain.invoke(申请差旅费需要走什么样的流程)跑完之后看效果大部分问题都能回答得比较靠谱引用来源也顺带带上了。但也有一些回答明显偏了排查下来发现是检索召回的相关性不行模型拿到的资料本来就不对再聪明也答不对。所以记住这个结论RAG 系统的上限由检索质量决定而不是由模型的聪明程度决定。先优化切片策略和检索策略不要一上来就换更大的模型。3.4 加一点记忆后效果对比跑通基础问答之后我又试着加了一轮多轮对话。用户先问“报销流程是什么”收到回答后接着追问“那第二点具体怎么操作”。如果系统没有记忆第二个问题拿不到任何上下文不知道“第二点”指的是什么回答自然就废了。加上缓冲记忆之后第二个问题会被自动拼上第一轮的内容模型就能理解用户问的是“报销流程中提到的第二点”。我把两种效果做了个对比场景无记忆表现有记忆表现追问“第二点具体怎么操作”无法理解“第二点”要求用户澄清能定位到之前回答中的第二点追问“时间限制呢”不知道在问谁的限制能关联到对应的文档主题隔 5 轮后问“那我来补充一下”完全丢失上下文无法衔接仍能维持基本连贯性加了记忆后体验提升很明显但也带来一个副作用输入 token 明显变多。用户问 10 轮每轮带着全部历史成本直线上升。后来我改成只保留最近 4 轮会话作为记忆再多就丢掉了兼顾了效果和开销。3.5 性能与成本观察做个粗算的话一次问答的输入 token 由这几部分组成系统提示词约 50 个 token、检索到的 4 块内容约 800~1000 个 token、历史会话若干、当前问题若干。也就是说即使每轮问题只有十几个字实际输入成本也被检索内容拉得非常高。如果你要索引一个大知识库比如几万篇文章嵌入成本也要提前估算。按平均每块 500 字符来算一篇一万字的文档大约切成 20 块每块转一次向量整体成本等于“块数 × 每次嵌入单价”。在自己的电脑上跑小规模数据没感觉上云、上大数据时这笔账一定要提前算清楚。4. 学习路径与避坑指南这部分是我最想分享的。LangChain 是一个迭代速度极快的框架你 3 个月前看到的写法现在可能就废弃了。所以入门的关键不是背某个版本的 API而是掌握底层思维同时学会应对“变化”本身。4.1 我推荐的六步学习路径第一步只读概念不碰代码。把组件地图——模型、模板、解析、链、记忆、Agent——搞清楚它们各自干什么就够起步了。第二步手写一条最小链。用一个模板、一个模型、一个解析器串一条“输入问题-输出结构化结果”的链。跑通后再试着换一个模型感受一下“统一接口”的优势。第三步做一个带检索的问答。自己准备一批文档做切片、向量化、检索接到链上。这个阶段你会真正理解 RAG 的每一步在干什么。第四步加记忆。先加最简单的缓冲记忆体验一下“多轮对话”是怎么实现的再评估 token 成本。第五步体验一次 Agent。给模型挂一个计算器之类的可控工具让它多轮调用自己搞定问题体会“模型行动力”的边界和风险。第六步回头读源码。选一个你最常用的组件看不懂全部没关系看懂关键方法的输入输出就已经超过了大部分停留在 API 层的使用者。能改组件才算真正脱离“调包侠”阶段。4.2 实战中踩过的坑记几个真实的坑都是我踩过之后才明白的。第一个坑是版本变化导致的示例失效。网上能找到大量旧版代码直接复制大概率跑不通。解决办法每篇示例都先确认它对应的版本号。官方文档里如果标注了版本优先按文档走。第二个坑是提示词模板变量不匹配。前面提到过缺变量的时候不会报错只会默默变成空字符串。为此我养成了一个习惯模板写完后先手动调用一次格式化确认所有变量都正常渲染然后再跑整条链。第三个坑是模型幻觉尤其在你加“只根据资料回答”之前。模型发现资料里没有答案时本能是编一个而不是承认不知道。有效的对策是在系统提示词里写得非常具体“如果资料中没有明确提到请直接回答‘资料中没有相关信息’不要推测。”并且把这句放在提示词靠前的位置效果比藏在最后好很多。第四个坑是 Agent 循环失控。有一次我没设最大轮数模型一直调用一个查询工具来回折腾了近一分钟才结束。从那以后凡是 Agent我都会先设置最大循环轮数再设一个整体超时时间预算并且每次调用都打日志。第五个坑是切块太暴力。我一开始按固定长度切结果把一些表格和代码从中间截断了检索效果惨不忍睹。后来改成优先按结构切——标题、段落、表格分别处理——明显好转。这步需要多试别指望一把参数吃到所有文档类型。第六个坑是输出解析不稳定。模型偶尔会返回 JSON 前后带说明性文字或者引号不配对。不要直接解析先做个清洗函数再配合重试机制成功率才会高。4.3 追问从会用走向会改如果上面的内容你都吃透了说明你已经能从“调 API”变成“搭应用”了。但我还建议你往前走一步自己动手改一个内部组件。比如写一个自定义回调把每条链路各环节的耗时打出来。这个很简单却非常有用。我在调试文档问答的时候发现大部分时间都花在检索上而不是模型推理上这直接改变了我的优化方向——先优化索引结构而不是换更大的模型。再比如写一个缓存组件。对完全相同的输入直接返回之前的输出在测试阶段能省不少调用费用。这类小改造会逼着你理解组件的接口约定比看十篇文章都有用。做个学习笔记的收尾LangChain 给我最大的启发不是它提供了多少现成组件而是它把“大模型应用开发”这件事从一个模糊的感觉变成了一条条清晰可组合的流水线。我到现在也没有背完所有 API但每接到一个新需求都能快速拆解成“用哪个组件、怎么组合、要防什么坑”这大概就是学习这套框架的真正回报。如果这篇文章能帮你少走一些弯路那就值了。