1. 为什么大模型应用开发绕不开LangChain1.1 从“裸调API”到“框架化开发”的必然转变2023年初我接了一个需求把公司内部的客服知识库接上大模型做一个能回答产品问题的问答机器人。当时我的第一反应是——直接调API不就行了写个函数把用户问题拼进prompt发给模型拿回结果完事。结果真动手才发现事情远没有这么简单。用户问“你们的产品支持批量导出吗”我需要先去知识库里检索相关文档片段再把片段和问题一起塞给模型模型回答完之后我还得判断它有没有胡编乱造如果它说“我需要查一下订单状态”我还得让它去调一个内部API多轮对话的时候历史消息怎么截断、怎么保留上下文全是坑。这些活儿如果全部手写代码会迅速膨胀成一个几千行的意大利面条。更麻烦的是每换一个模型供应商接口格式、参数命名、返回结构都不一样迁移成本极高。LangChain解决的正是这个问题它把大模型应用开发中反复出现的模式抽象成标准组件让你用搭积木的方式组织逻辑而不是每次都从零造轮子。打个比方裸调API就像直接用砖头水泥盖房子什么都要自己砌LangChain则提供了一套预制件——门窗、梁柱、管道接口都是标准化的你只需要决定怎么组装。当然预制件也有它的代价后面我会详细讲什么时候该用、什么时候不该用。1.2 LangChain到底包含哪些核心模块很多人第一次打开LangChain文档会被吓到模块太多了。但真正日常用到的核心其实就几块我用一张表把它们和实际用途对应起来模块作用典型使用场景Models统一不同大模型的调用接口切换OpenAI、通义、本地OllamaPrompts模板化管理提示词动态填充变量、少样本示例Chains把多个步骤串成流水线检索→回答→格式化Memory管理多轮对话历史聊天机器人记住上下文Retrieval文档加载、切分、向量检索本地知识库问答Agents让模型自主决定调用哪个工具需要计算、查库、调API的任务Callbacks监控和日志调试、计费统计、追踪链路刚入门的时候我建议你先把Models、Prompts、Chains这三块吃透它们构成了80%应用的基础骨架。Memory和Retrieval是进阶Agents是另一个台阶。不要一上来就想把所有模块都用上那只会让你陷入配置地狱。1.3 适合谁学学到什么程度够用这篇文章面向的是有一定Python基础、想快速上手大模型应用开发的人。你不需要懂深度学习不需要会训练模型甚至不需要理解Transformer的内部结构。你需要的是会写Python函数、知道什么是API、能看懂JSON。学到什么程度算够用我的判断标准是能独立用LangChain搭出一个带知识库检索的问答应用并且知道每个环节出问题时该去哪里排查。这个目标听起来不高但覆盖了实际工作中大部分需求。至于更复杂的Agent编排、多智能体协作那是后面的事先把基础打牢。2. 环境搭建与第一个可运行示例2.1 Python环境与依赖安装的实操细节LangChain的安装本身不复杂但环境隔离这一步千万别省。我见过太多人因为全局环境里包版本冲突折腾半天以为是LangChain的问题其实是环境脏了。我习惯用conda建一个独立环境Python版本选3.10或3.11这两个版本兼容性最好conda create -n langchain-demo python3.11 conda activate langchain-demo pip install langchain langchain-community langchain-openai这里解释一下为什么装三个包。langchain是核心库提供基础抽象langchain-community包含大量第三方集成各种向量库、文档加载器langchain-openai是OpenAI的官方集成包。从0.1版本开始LangChain把各家模型的集成拆成了独立包这样做的好处是核心库更轻量你用什么装什么。如果你打算用本地模型比如通过Ollama跑一个开源模型那还需要装langchain-ollama。如果你要用Chroma做向量存储装langchain-chroma。记住一个原则核心库只装langchain其他按需装独立包。注意网上很多老教程还在用from langchain.llms import OpenAI这种写法这在0.1版本之后已经废弃了。如果你照着老教程写报ImportError不是你环境的问题是API变了。新写法是from langchain_openai import ChatOpenAI。2.2 用ChatOpenAI跑通第一条链路环境好了先跑一个最小可运行示例确认整条链路是通的。我建议第一段代码不要搞太复杂就是“给模型一句话让它回一句话”from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0.7, api_key你的key ) response llm.invoke(用一句话解释什么是向量数据库) print(response.content)这段代码虽然简单但包含了几个关键信息。model参数指定用哪个模型temperature控制输出的随机性0最确定1最发散invoke是LangChain统一的调用入口。注意返回的是一个AIMessage对象真正的内容在.content属性里直接print整个对象会看到一堆元数据。如果你用的是国内模型或者本地模型把ChatOpenAI换成对应的类就行invoke的用法完全一样。这就是LangChain的价值——换模型不改调用逻辑。2.3 提示词模板让输入变得可复用直接传字符串只能应付一次性任务实际应用里提示词往往是带变量的模板。LangChain的ChatPromptTemplate就是干这个的from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个{role}回答要简洁专业。), (human, {question}) ]) chain prompt | llm result chain.invoke({ role: 数据库专家, question: 索引失效的常见原因有哪些 }) print(result.content)这里出现了LangChain最有特色的语法——管道符|。它叫LCELLangChain Expression Language意思是把prompt的输出喂给llm。你可以把它理解成Unix管道左边的东西流到右边。这种写法的好处是天然支持流式输出、批量调用、异步调用而且链路清晰一眼能看出数据怎么流动。我实测下来LCEL的写法比老版本的LLMChain更直观也更灵活。老写法把prompt和llm绑死在一个Chain对象里想换个组合方式就得重写LCEL是组合式的prompt和llm各自独立想怎么拼就怎么拼。3. 核心组件深度拆解与避坑指南3.1 模型调用的参数选择与成本控制模型调用看着简单但参数选不对要么效果差要么账单爆炸。我把几个关键参数的实际影响列出来参数作用我的经验值temperature输出随机性问答0.2-0.3创意写作0.7-0.9max_tokens限制输出长度按需设置防止模型啰嗦烧钱timeout请求超时30-60秒本地模型可放宽max_retries失败重试次数2-3次配合指数退避temperature这个参数我要多说一句。很多人做知识问答时设成0.7甚至1.0结果模型开始自由发挥答案里混进不存在的信息。知识问答场景temperature设0.1到0.3就够了你要的是稳定复现不是创造力。反过来如果你让模型写营销文案temperature太低会显得干巴巴0.8左右比较合适。成本控制方面除了选便宜的模型还有一个容易被忽略的点prompt的长度直接决定输入token数。我见过有人把整篇文档塞进prompt一次调用花掉几毛钱。正确做法是先检索只把最相关的几个片段塞进去。这个后面讲RAG的时候会展开。3.2 输出解析器把模型的“话”变成程序能用的数据模型返回的是自然语言但程序需要的是结构化数据。比如你想让模型从一段文本里提取姓名、电话、公司返回一个JSON这时候就需要输出解析器。LangChain提供了几种解析器最常用的是PydanticOutputParser和JsonOutputParser。我用Pydantic举个例子from langchain_core.output_parsers import PydanticOutputParser from pydantic import BaseModel, Field class PersonInfo(BaseModel): name: str Field(description姓名) phone: str Field(description电话) company: str Field(description公司) parser PydanticOutputParser(pydantic_objectPersonInfo) prompt ChatPromptTemplate.from_messages([ (system, 从文本中提取信息。\n{format_instructions}), (human, {text}) ]).partial(format_instructionsparser.get_format_instructions()) chain prompt | llm | parser result chain.invoke({text: 张三13800138000就职于某某科技}) print(result.name, result.phone, result.company)这里的关键是get_format_instructions()它会把Pydantic模型的字段说明自动转成一段提示词告诉模型该输出什么格式。这一步非常重要没有它模型不知道你要JSON还是YAML字段名叫什么。踩过的坑模型有时候会在JSON外面包一层json的代码块标记导致解析失败。解决办法是在prompt里明确说“只输出JSON不要任何其他文字”或者用JsonOutputParser配合容错处理。我一般会在解析器外面套一个try-except解析失败就重试一次重试还失败就返回原始文本人工处理。3.3 链的组合方式顺序、分支与并行单个链只能做一件事实际应用往往是多个链组合。LCEL支持几种组合方式我按使用频率排个序顺序组合最常见就是|一路串下去。比如“检索文档 → 生成回答 → 翻译成英文”三个步骤依次执行。并行组合用RunnableParallel适合同时做多件事。比如用户提问后一边检索知识库一边查用户历史订单两边结果都拿到后再一起给模型。这样比串行快一倍。分支组合用RunnableBranch根据条件走不同路径。比如判断用户问题是“咨询”还是“投诉”走不同的处理流程。from langchain_core.runnables import RunnableParallel, RunnableBranch # 并行示例 parallel RunnableParallel( knowledgeretriever_chain, historyhistory_chain ) # 分支示例 branch RunnableBranch( (lambda x: 投诉 in x[question], complaint_chain), (lambda x: 咨询 in x[question], consult_chain), default_chain )我的建议是能用顺序就别用分支能用分支就别用Agent。每增加一层复杂度调试难度就翻一倍。很多新手一上来就想搞全自动Agent结果出了问题根本不知道是哪一步错了。4. 用RAG搭建本地知识库问答4.1 RAG的核心流程与为什么需要它RAG检索增强生成是目前大模型落地最实用的模式。它的逻辑很简单模型本身不知道你的私有数据那就在回答问题之前先从你的知识库里找到相关内容一起塞给模型让它基于这些内容回答。为什么不能直接把所有文档塞进prompt两个原因一是token成本二是模型对超长上下文的注意力会衰减塞太多反而找不到重点。RAG的本质是“先检索后生成”用检索来缩小模型需要关注的范围。完整流程分五步加载文档 → 切分文本 → 向量化 → 存入向量库 → 检索并生成。每一步都有讲究我逐个说。4.2 文档切分最容易被忽视的关键环节文档切分看着简单实际上直接决定检索质量。切太大检索出来的片段包含太多无关信息干扰模型切太小语义不完整检索不到。LangChain提供了多种切分器最常用的是RecursiveCharacterTextSplitter。它的逻辑是优先按段落切段落太长再按句子切句子还长再按字符切尽量保持语义完整。from langchain_text_splitters import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, , , , ] ) chunks splitter.split_text(long_text)chunk_size500表示每个片段大约500个字符chunk_overlap50表示相邻片段重叠50个字符。重叠是为了防止一句话正好被切断导致两边都检索不到。中文场景下separators里一定要加上中文标点否则切分器不认识中文句子边界。我的经验值技术文档chunk_size设500-800聊天记录设300-500法律合同设800-1000。没有万能参数要拿实际数据试。一个实用的技巧是切完之后随机抽几个片段读一读如果读起来语义完整、能独立理解说明切分合理。4.3 向量化与检索选对嵌入模型和检索策略切分完的文本要转成向量才能做语义检索。嵌入模型的选择直接影响检索效果。OpenAI的text-embedding-3-small性价比很高中文场景也可以用智谱、通义等国内模型的嵌入接口。from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_texts( textschunks, embeddingembeddings, persist_directory./chroma_db ) retriever vectorstore.as_retriever( search_typesimilarity, search_kwargs{k: 4} )k4表示检索最相似的4个片段。这个数字不是越大越好k太大反而引入噪声。我一般从4开始试看效果调整到3或5。检索策略除了默认的相似度检索还有MMR最大边际相关性。MMR的好处是检索结果更多样不会四个片段都在说同一件事。如果你的知识库内容重复度高建议用MMRretriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 4, fetch_k: 20} )fetch_k20表示先取20个候选再从里面挑4个最有多样性的。4.4 完整RAG链的组装与调试把上面几步串起来就是一个完整的RAG链from langchain_core.runnables import RunnablePassthrough from langchain_core.output_parsers import StrOutputParser template 基于以下资料回答问题如果资料中没有相关信息就说不知道。 资料 {context} 问题{question} prompt ChatPromptTemplate.from_template(template) def format_docs(docs): return \n\n.join(doc.page_content for doc in docs) rag_chain ( {context: retriever | format_docs, question: RunnablePassthrough()} | prompt | llm | StrOutputParser() ) answer rag_chain.invoke(你们的退货政策是什么)这段代码里RunnablePassthrough的作用是把用户的问题原样传递下去retriever | format_docs则是检索并把片段拼成字符串。整个链的数据流向是问题同时进入检索器和passthrough检索结果格式化后和问题一起填入prompt再交给模型生成答案。调试RAG链的时候我习惯先把retriever单独拿出来测看看检索出来的片段是不是真的相关。如果检索结果就不对后面怎么调prompt都没用。检索质量是RAG的天花板生成质量只是在这个天花板下面发挥。5. Agent与工具调用让模型自己决定做什么5.1 Agent和Chain的本质区别Chain是你预先定义好步骤模型按部就班执行。Agent是你给模型一堆工具让它自己决定用哪个、用几次。Chain是流水线Agent是决策者。举个例子用户问“北京今天天气怎么样适合穿什么衣服”。Chain的做法是你得先写死“先查天气再根据天气推荐衣服”。Agent的做法是你给它一个查天气的工具它自己判断需要先调天气工具拿到结果后再生成建议。LangChain的Agent核心是ReAct模式Reason推理→ Act行动→ Observe观察循环直到任务完成。模型每一步都会输出它的思考过程和要调用的工具程序执行工具后把结果返回给模型模型继续下一步。5.2 定义工具与创建Agent工具就是一个普通的Python函数加上装饰器说明它的用途from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的天气 # 实际调用天气API return f{city}今天晴气温25度 tool def calculate(expression: str) - str: 计算数学表达式 return str(eval(expression))工具的docstring非常重要模型就是靠这段描述来判断什么时候该用这个工具。描述要写清楚“这个工具做什么、什么时候用、参数是什么”。我见过有人工具描述写得含糊结果模型该调的时候不调不该调的时候乱调。创建Agentfrom langchain.agents import create_tool_calling_agent, AgentExecutor agent create_tool_calling_agent(llm, [get_weather, calculate], prompt) executor AgentExecutor(agentagent, tools[get_weather, calculate], verboseTrue) result executor.invoke({input: 北京天气怎么样顺便算一下25乘以4})verboseTrue会打印出模型的每一步思考和工具调用调试的时候必开。5.3 Agent的常见问题与限制Agent很强大但坑也多。我列几个实际遇到的死循环模型反复调用同一个工具停不下来。解决办法是设置max_iterations限制最大循环次数一般设5-10次。工具选择错误模型选了不合适的工具。这通常是工具描述不够清晰或者工具太多导致模型混淆。工具数量控制在5个以内超过就考虑分组或改用Chain。参数格式错误模型传的参数类型不对。解决办法是在工具函数里做类型校验和容错别指望模型每次都传对。成本失控Agent每一步都是一次模型调用一个复杂任务可能调十几次。生产环境用Agent一定要设预算上限和超时。我的建议是能用Chain解决的绝不用Agent。Agent适合那些步骤不确定、需要动态决策的场景比如“帮我查一下最近的订单如果有未发货的就催一下”。如果步骤是固定的Chain更稳定、更便宜、更好调试。6. 常见问题排查与实战经验6.1 版本兼容性LangChain最大的坑LangChain迭代速度极快网上大量教程是0.0.x版本的直接照抄大概率报错。我整理了几个高频的API变化老写法新写法说明from langchain.llms import OpenAIfrom langchain_openai import ChatOpenAI模型集成拆包from langchain.vectorstores import Chromafrom langchain_chroma import Chroma向量库拆包LLMChain(llmllm, promptprompt)prompt | llmLCEL替代initialize_agent(...)create_tool_calling_agent(...)Agent重构遇到ImportError先查版本再看官方文档的迁移指南。不要在网上随便找个博客就照着写LangChain官方文档更新很及时以官方为准。6.2 检索效果差的排查思路RAG效果不好按这个顺序排查先看检索结果把retriever单独跑一下看返回的片段是否相关。不相关就是切分或嵌入模型的问题。再看切分粒度片段太长包含噪声太短语义不全。调整chunk_size试试。然后看嵌入模型中文场景用英文嵌入模型效果会打折换中文优化的模型。最后看prompt前面都没问题才考虑调整prompt的措辞。很多人一上来就改prompt这是本末倒置。检索不对prompt写出花来也没用。6.3 流式输出与异步调用用户体验上流式输出几乎是必须的。LangChain的LCEL天然支持流式for chunk in rag_chain.stream(你的问题): print(chunk, end, flushTrue)异步调用用ainvoke和astream适合Web服务场景能显著提升并发能力。注意异步链里的每个组件都要支持异步如果中间某个自定义函数是同步的整个链会退化成同步。6.4 我踩过的几个典型坑坑一把API Key硬编码在代码里。正确做法是用环境变量或.env文件配合python-dotenv加载。代码提交到仓库前一定要检查有没有泄露key。坑二忽略token限制。每个模型都有最大上下文长度prompt加历史加检索结果超了就会报错。解决办法是加一个token计数和截断逻辑或者用支持更长上下文的模型。坑三Memory无限增长。多轮对话如果不过滤历史几轮之后token就爆了。LangChain提供了ConversationBufferWindowMemory只保留最近N轮和ConversationSummaryMemory把历史压缩成摘要按场景选。坑四向量库持久化没做。每次重启都重新嵌入所有文档又慢又费钱。Chroma、FAISS都支持持久化建库时指定persist_directory就行。7. LangChain与LangGraph什么时候该换工具7.1 两者的定位差异LangGraph是LangChain团队推出的另一个库专门解决复杂流程编排问题。LangChain适合线性的、步骤确定的流程LangGraph适合有循环、有分支、有状态管理的复杂流程。举个例子一个客服机器人如果只是“检索→回答”LangChain够了。但如果它需要“判断问题类型→如果是技术问题走技术流程→技术流程里可能需要多轮追问→追问后重新判断”这种带循环和状态的就该用LangGraph。LangGraph的核心概念是“图”节点是处理步骤边是流转条件状态在节点之间传递。它比LangChain的Chain更灵活但也更复杂。7.2 选型建议我的判断标准很简单流程是直线没有回头路 → LangChain需要根据中间结果决定下一步 → 先试试LangChain的RunnableBranch分支复杂、有循环、需要人工介入 → LangGraph多智能体协作 → LangGraph不要因为LangGraph新就无脑上。我见过用LangGraph写一个简单的问答流程代码量比LangChain多三倍维护成本极高。工具是拿来解决问题的不是拿来炫技的。7.3 从LangChain迁移到LangGraph的时机如果你发现代码里出现了这些信号就该考虑迁移了大量的if-else嵌套判断下一步做什么需要让流程“回到上一步重新来”需要人工审核后再继续human-in-the-loop多个Agent之间需要共享状态迁移不是重写LangGraph可以复用LangChain的模型、工具、检索器只是把编排层换掉。先把手头的LangChain应用跑通遇到瓶颈再迁移这是最务实的路径。8. 一些实际项目中的体会我做过的几个LangChain项目里最深的体会是框架能帮你省掉重复劳动但省不掉对业务的理解。检索策略怎么定、prompt怎么写、工具怎么设计这些都得结合具体场景反复试。LangChain提供的是脚手架房子盖成什么样还是取决于你。另一个体会是不要追求一步到位。先跑通最小闭环再逐步加检索、加记忆、加工具。每加一个组件就测一次确保它是有效的。我见过有人一口气把所有模块都堆上去结果出了问题根本定位不到是哪一层。最后分享一个实用习惯给每个链加callback日志。LangChain的Callback机制可以记录每一步的输入输出和耗时调试和优化的时候非常有用。生产环境还能用来做计费和监控。这个习惯帮我省了无数次排查时间。至于LangChain会不会过时我的看法是抽象层会变但“检索增强”“工具调用”“流程编排”这些模式不会变。学会这些模式就算以后换了别的框架迁移成本也很低。工具是死的思路是活的。