LangChain这个框架，从大模型应用开发刚火起来那阵子到现在，几乎成了这个领域绕不开的基础设施。我见过不少朋友，上来就找教程，结果要么被一堆新旧混杂的代码绕晕，要么被“Chain、Agent、Memory”这些概念搞得一头雾水。其实LangChain的本质并不复杂，它就是一套帮我们把大模型、外部数据和业务逻辑组合起来的开发工具集。这篇文章就围绕LangChain基础，把最核心的组件、最常见的实战链路和最容易踩的坑一次说清楚，适合刚接触大模型应用开发、想在项目里真正把LangChain用起来的开发者，哪怕你之前只用过API，这篇文章也能让你快速上手并理解背后的设计逻辑。

1. LangChain到底是什么，解决什么问题

1.1 从一个真实痛点说起

先说我一开始的经历。最早做大模型应用的时候，我直接调用大模型API，看起来挺简单：构造prompt、传参、拿返回值。但一旦需求变复杂，麻烦就来了。比如我要做一个基于内部文档的问答系统，首先得把PDF、Word、网页里的内容都读出来，然后切分成小块，再把每块转成向量存进数据库，用户提问时还要把问题也转成向量去检索，最后把检索到的片段和原问题拼在一起发给大模型。这一整套流程，如果全靠自己写，光胶水代码就要好几百行，而且每个环节都要自己处理异常、格式转换、参数传递。更麻烦的是，项目里往往不止一个这样的应用，每做一个新需求就要把这些逻辑重新写一遍。

LangChain做的，就是把这条链路上最常用、最容易出错的环节抽象成标准化组件，比如文档加载器负责读各种格式，文本分割器负责切块，向量存储接口负责存取，链（Chain）负责把多个步骤按顺序组装。你用的时候只需要把对应组件声明出来，然后像搭积木一样接在一起。这个思路和我们在工程里说的“不要重复造轮子”是一个道理，它解决的不是“能不能调用大模型”的问题，而是“如何高效、稳定地把大模型集成到真实业务系统”的问题。

1.2 LangChain的三大核心价值

第一是标准化。不管底层是大模型服务商A还是服务商B，在LangChain里它们的接口风格是统一的。你今天用这家，明天换那家，只需要改一行配置或者换个类名，业务代码不需要大改。这种解耦对于一个刚上线、随时可能换模型服务的产品来说极其重要。

第二是组合性。LangChain基于链路（Chain）的设计，让流程可以像管道一样自由组合。文本进、答案出，中间每一步都可以随时替换或增加。比如最开始你可能只做一个简单的“问题转prompt、发给模型”，后面要加知识库了，就在链里插一个检索器节点，代码结构依然清晰。

第三是生态丰富。从文件解析、向量数据库、工具调用到Agent，LangChain都有大量现成的集成模块。这意味着你不需要自己去写各种格式的解析器，也不需要对着每个向量数据库的SDK反复调试，直接拿起社区适配好的组件用就行了。我自己的经验是，很多项目在验证阶段根本没有时间从头造轮子，LangChain这种“工具箱式”的框架能明显加快迭代速度。

不过也要提醒一句，LangChain的抽象并不是银弹。它适合标准化流程、RAG、多步工具调用这些典型场景。如果你的需求极其轻量，比如只是单次调用大模型生成一段文案，那直接用SDK反而更省事。选择框架不是越重越好，而是匹配场景才算对。

2. 环境准备：五分钟跑通第一个LangChain Demo

2.1 安装与依赖配置

在动手写代码之前，先把环境说清楚。我推荐使用Python 3.10或3.11，因为LangChain的依赖链比较长，太老的Python版本容易出现兼容问题。另外，我强烈建议你在项目里使用虚拟环境，不要在全局环境里直接装，否则等到项目多了，你会发现不同项目依赖冲突到你怀疑人生。

基础的安装命令很简单：

pip install langchain

但从2024年开始，LangChain做了比较大的模块拆分，官方把模型提供商、向量存储、社区集成都拆到了单独的包里。也就是说，只安装主包，很多常用功能其实用不了。以我现在最常用的一套组合为例：

pip install langchain langchain-openai langchain-community pip install python-dotenv faiss-cpu

这里解释一下这几个包的关系：

• langchain：核心框架，包含链、Agent、prompt模板、memory等基础抽象。
• langchain-openai：对接OpenAI系列模型的封装。如果你用的是其他服务商，也有对应的包，比如langchain-anthropic，结构是类似的。
• langchain-community：社区维护的集成，包括各种文档加载器、向量数据库封装等。
• faiss-cpu：一个本地向量数据库。在学习和验证阶段，用本地FAISS就足够了，不需要一上来就上生产级数据库。

安装完成之后，在项目根目录建一个.env文件，把API密钥放进去，然后通过python-dotenv加载。这么做不只是为了代码整洁，更是为了安全，尽量不要把密钥硬编码到代码里。

2.2 模型服务的接入方式

LangChain里和模型打交道的类有很多，但核心思路是一致的：先创建一个模型对象，设置参数，然后调用它。以聊天模型为例，最常用的写法是：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="gpt-4o-mini", temperature=0.7, api_key="your-api-key" )

这里有一个关键点：LangChain的模型接口非常统一，invoke方法负责接收输入并返回结果。至于底层走的是HTTP还是别的协议，你不需要关心，那是封装层做的事情。现实的工程里，我会把模型初始化参数抽到配置中心或者.env文件里，这样切环境、切模型都非常方便。

2.3 第一个可运行的最小示例

环境装好、模型配置好之后，我们来跑一个真正的Demo。这段代码虽然短，但它把“模型接入”和“消息构造”两个基础概念都覆盖到了：

import os from dotenv import load_dotenv load_dotenv() from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage, SystemMessage llm = ChatOpenAI( model="gpt-4o-mini", temperature=0.5, api_key=os.getenv("OPENAI_API_KEY") ) messages = [ SystemMessage(content="你是一名经验丰富的技术工程师，回答风格要求简洁专业。"), HumanMessage(content="请用一句话解释什么是RAG。") ] resp = llm.invoke(messages) print(resp.content)

这里引入了两个新概念：SystemMessage和HumanMessage。你可以把消息理解为一次对话里的不同“角色”，系统消息负责设定人设或行为规则，人类消息就是用户的输入。LangChain通过这种消息列表的方式，天然支持多轮对话的场景。

我实际验证过，只要API凭证没问题，这段代码跑下来基本是零报错。当然前提是你安装了langchain-openapi包。如果提示ChatOpenAI not found，十有八九是包没装全，回到2.1节把依赖补上就行。

3. 基础组件逐个拆解

3.1 模型封装：不止是API调用

很多初学者把LangChain里的Model当成一个简单的API封装，用的时候确实很像，但它背后提供的远不止这些。除了最基础的invoke同步调用，模型对象还支持stream流式返回、batch批量请求、bind绑定工具参数等模式。

举个例子，如果你要做一个流式输出的聊天机器人，希望用户看到大模型一个字一个字地“打字”出来，你只需要这样：

for chunk in llm.stream(messages): print(chunk.content, end="", flush=True)

底层怎么处理流式协议你完全不用管。

再比如，如果模型支持工具调用（也就是Function Calling），你可以通过bind_tools把自定义函数描述绑定给模型。这一步在构建Agent时非常关键，模型会先输出一个“我打算调用某个工具”的指令，你再根据这个指令去执行实际函数，而不是让模型直接执行代码。这个设计非常重要，因为模型本身并不执行代码，它只负责“决策”。

3.2 Prompt模板：让提示词可复用

如果直接把字符串拼进代码里，写一次两次还行，一旦prompt变长、变量变多，你很快就会崩溃。LangChain提供了PromptTemplate，用来把静态的模板部分和动态的变量部分分离开。

from langchain_core.prompts import PromptTemplate template = """ 你是{domain}领域的资深专家。 请你根据以下问题给出专业且通俗的解释： 问题：{question} """.strip() prompt = PromptTemplate.from_template(template) final_prompt = prompt.format( domain="大模型应用开发", question="什么是LangChain？" ) print(final_prompt)

这样做的价值是：模板可以在不同场景复用，修改时只需改模板文件，不用动业务代码。现实项目里，我习惯把prompt模板放到独立目录甚至数据库里，通过缓存加载。这样的话，运营或产品同事想调整话术时，也不需要麻烦开发重新发版。

还有一个实用的技巧：长prompt里的换行和空格会影响模型的解析效果。我上面用了.strip()，就是为了去掉开头结尾多余的空行。很多“模型回答不听话”的问题，其实不是模型的问题，而是prompt格式给得不干净。

3.3 Chain：把多个步骤串起来

LangChain名字里的“Chain”，就是整个框架最核心的设计思想。在很早期的版本里，大家用得最多的是LLMChain，先格式化prompt，再传给模型，然后解析输出。但现在主流推荐的是LCEL（LangChain Expression Language），它用管道符|来组装组件，读起来非常直观。

from langchain_core.prompts import ChatPromptTemplate prompt = ChatPromptTemplate.from_messages([ ("system", "你是{domain}领域的专家。"), ("human", "{question}") ]) llm = ChatOpenAI(model="gpt-4o-mini") chain = prompt | llm result = chain.invoke({ "domain": "法学", "question": "合同里有哪些常见陷阱？" }) print(result.content)

看到没，prompt | llm这一行，就把“格式化prompt”和“调用模型”组装成了一条链。invoke的时候传入一个字典，chain会自动把字典里的键值填充到prompt模板中。

LCEL的强大之处在于，你可以无限叠加组件。比如：

chain = prompt | llm | StrOutputParser()

StrOutputParser会把模型的输出从消息对象转成纯字符串，这在后面的链式调用里非常方便。我建议所有刚上手LangChain的朋友，现在开始就直接学LCEL，不要再去看老的Chain类用法了。网上很多教程还在讲LLMChain，不是它不能用，而是官方已经把重心转到LCEL上，老接口迟早会被边缘化。

3.4 Memory：让对话有记忆

做过聊天机器人的朋友应该知道，大模型接口本身是无状态的，它不记得你和它说过什么。要想实现“上下文记忆”，就必须把历史消息重新传给模型。

LangChain里的Memory模块就是干这个的。最基础的用法是ConversationBufferMemory，它会把所有历史消息都保留下来。但如果对话太长，把所有历史都塞进上下文会导致token消耗越来越大，模型也可能“忘记”更早的信息。因此就有了窗口记忆：

from langchain.memory import ConversationBufferWindowMemory memory = ConversationBufferWindowMemory(k=2, return_messages=True)

k=2表示只保留最近两轮对话。这种“窗口式”的记忆方式非常适合实际生产环境，因为它在“保留上下文”和“控制token消耗”之间取得了平衡。

不过说实话，我更推荐把记忆理解为“消息历史管理”。现代LangChain版本里，你可以直接用history变量而不用专门的Memory类，尤其在通过RunnableWithMessageHistory组装会话链时，把历史的存取逻辑交给外层控制。用Memory当然可以，但你要清楚它背后的机制：每一轮对话结束后，把该轮的消息追加到列表，下次请求时把列表整体传入。理解了这一点，无论API怎么变你都不会迷路。

3.5 检索与文档加载：解锁长文本知识

这是LangChain在RAG场景中最核心的部分。你要让模型回答私有知识的问题，不能把整本手册都塞进prompt，而是要先把文档切碎、向量化、存储起来，然后在提问时检索相关内容。这个流程被LangChain抽象成了几个清晰组件。

from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 1. 加载文档 loader = TextLoader("docs/tech_manual.txt", encoding="utf-8") documents = loader.load() # 2. 切分文档 splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50 ) chunks = splitter.split_documents(documents)

chunk_size=500表示每个块大约500个字符，chunk_overlap=50表示块与块之间保留50个字符的重叠，避免正好把一段连续语义切断。这里面的参数调优直接影响最终回答质量。

有了切好的文本块，接下来就是向量化。这里把文本转成向量，用的是嵌入模型：

from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import FAISS embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = FAISS.from_documents(chunks, embeddings) retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

k=3表示每次检索返回最相关的3个文本块。这三个块会作为上下文拼进prompt，让模型基于它们来回答。

这一整套流程，就是RAG的核心。它解决的是“模型不知道你公司内部细节”的问题，用一个工程方案把业务知识注入到了模型回答的上下文里。后面第4章，我会带你把整个流程串成一个完整的应用。

4. 完整实操：实现一个本地知识库问答应用

4.1 需求与设计思路

假设现在有个需求：手头有一批会议纪要、技术文档和产品说明，存放在本地文件夹里，我们需要一个命令行问答工具，可以对这些内容提问，得到有依据的回答。

听起来很简单，但如果只是把文档整篇发给模型，一个是要花很多token，一个是模型注意力分散、回答不精准。所以正确做法就是RAG：先建立索引，再检索相关片段，最后让模型基于片段回答。

整个系统可以拆成两个阶段：

• 索引阶段（一次性）：加载文档、切分文本、向量化、写入向量库。
• 查询阶段（每次提问）：问题向量化、检索相似块、把块塞进prompt、调用模型生成回答。

对应到LangChain里，索引阶段我们用TextLoader、RecursiveCharacterTextSplitter、OpenAIEmbeddings、FAISS。查询阶段我们用create_history_aware_retriever（可选）和create_retrieval_chain。

4.2 文档加载与切分

首先把所有文件放到一个目录下，比如./docs。我们用DirectoryLoader把目录里所有文本文件加载进来，而不是一个一个手动加载。

from langchain_community.document_loaders import DirectoryLoader, TextLoader loader = DirectoryLoader( "./docs", glob="**/*.txt", loader_cls=TextLoader, loader_kwargs={"encoding": "utf-8"} ) documents = loader.load() print(f"共加载 {len(documents)} 个文档")

接下来是切分。切分策略直接决定检索效果。我在这类项目里常用的策略是RecursiveCharacterTextSplitter，它按一组分隔符从粗到细递归切分，尽量保住语义完整性。

from langchain.text_splitter import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=80, separators=["\n\n", "\n", "。", "！", "？", ". ", "! ", "? ", " "] ) chunks = splitter.split_documents(documents) print(f"切分为 {len(chunks)} 个文本块")

chunk_overlap=80是我比较推荐的经验值。切分时如果没有重叠，一个句子可能正好被拦腰截断，关键词刚好分布在两个块里，检索时哪个块都匹配不完整。保留重叠能让块与块之间有一定信息冗余，提高召回质量。

4.3 向量化与存储

向量化这一步要注意，文本块内容越长，向量维度越高，存储和检索的开销也越大。我通常选择维度适中、支持中文效果良好的嵌入模型。以text-embedding-3-small为例：

from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import FAISS # 创建嵌入模型 embeddings = OpenAIEmbeddings(model="text-embedding-3-small") # 直接基于切分好的文档创建向量库 vectorstore = FAISS.from_documents(chunks, embeddings) # 保存到本地，下次启动不需要重新生成 vectorstore.save_local("faiss_index") # 加载 # vectorstore = FAISS.load_local("faiss_index", embeddings, allow_dangerous_deserialization=True)

这里有一个安全细节值得单独提醒：FAISS在旧版加载本地索引时，存在反序列化风险，代码里会要求显式设置allow_dangerous_deserialization=True。如果你加载的是自己生成的索引文件，那没问题；如果是从不可信来源拿到的索引文件，千万别允许反序列化。

4.4 检索与问答链路搭建

当索引建立好后，查询就简单了。把向量库转成检索器，再组装成RAG链。这里我用create_stuff_documents_chain和create_retrieval_chain实现一个标准的“先检索再回答”链路：

from langchain.chains import create_history_aware_retriever, create_retrieval_chain from langchain.chains.combine_documents import create_stuff_documents_chain from langchain_core.prompts import ChatPromptTemplate retriever = vectorstore.as_retriever(search_kwargs={"k": 4}) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个企业内部知识库助手。请只根据上下文回答问题，不要编造内容。如果上下文里找不到答案，就回复‘知识库中未找到相关信息’。回答末尾列出参考来源。\n\n上下文：{context}"), ("human", "{input}") ]) doc_chain = create_stuff_documents_chain(llm, prompt) rag_chain = create_retrieval_chain(retriever, doc_chain) resp = rag_chain.invoke({"input": "如何部署新环境？"}) print(resp["answer"])

代码里的{context}和{input}是关键。create_stuff_documents_chain会自动把检索到的文档内容填充到{context}位置，而用户问题则填充到{input}。内部已经处理好了这些关联关系，这是LangChain“低代码”的典型体现。

运行之后，你可以试几个不同主题的提问。你会发现，如果知识库里确实有相关内容，回答质量明显比直接问模型要好——因为它有了“上下文依据”。如果没相关的内容，模型也会按prompt设定回复“未找到相关信息”，这就是电商客服系统里“拒绝幻觉”的核心控制手段。

5. 常见问题与排查技巧实录

5.1 依赖包版本混乱导致报错授信

LangChain的组件一直在快速迭代，网上很多教程还停留在老版本写法。我遇到最多的问题是：明明照着教程装了包，但一运行就报ModuleNotFoundError或者TypeError，查了半天发现是教程用的旧接口已经在新版被移除了。

排查思路其实很简单：

• 安装时统一指定版本组，不要混着装。
• 用pip list | grep langchain检查当前版本。
• 到官方发布页面看对应版本的Migration Guide。
• 实在不行，看错误栈里指向的具体模块，搜索模块名加“deprecated”就能看到替代API。

我个人的习惯是在项目开始时就锁定版本，并写到requirements.txt里。这虽然听起来繁琐，但能省掉后面无数个“为什么我一跑就报错”的深夜排查。

5.2 API调用失败与限流

如果你的程序在跑的时候突然报RateLimitError或AuthenticationError，我们要分层排查。认证问题相对简单，看.env里的API Key有没有正确加载、有没有过期、账户余额是否充足。限流问题就要看你的调用频率是不是超过了服务商允许的配额。

LangChain并没有自动帮你做限流重试，所以生产环境里要自定义一个重试机制。最简单的做法是使用tenacity库包装调用函数，捕获限流异常后等待退避重启。

from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10)) def call_llm(chain, payload): return chain.invoke(payload)

批量请求场景下，LangChain自带batch接口可以天然合并请求，减少限流的触发频率：

results = chain.batch([payload1, payload2, payload3])

5.3 上下文超长与token限制

当用户输入比较长，或者检索回来的文档块很多时，模型输入可能超过上下文限制，报ContextWindowExceededError。解决思路通常有两个方向：

• 减少输入内容：调低search_kwargs里的k值，比如从5降到3，减少塞入的文档块数量。
• 压缩历史消息：如果做了多轮对话，用ConversationBufferWindowMemory控制历史轮数，或者把历史消息做摘要后替代原始记录。

在实际项目里，我会给每轮对话记录一个估算token数，提前截断。虽然麻烦，但可以避免用户在一个很长的会话里突然收到报错。

5.4 检索效果差

“明明文档里有答案，模型却说查不到”是最让人头大的问题。这种情况通常不是模型的问题，而是检索没召回正确内容。我一般按照下面几个角度排查：

• 切分粒度：chunk_size太大，每个块包含太多无关信息，语义向量被冲淡；chunk_size太小，则单个块信息不足。建议从300到800之间多做几组实验。
• 重叠大小：chunk_overlap设置成0，容易把关键词恰好切掉。通常重叠设置成chunk_size的10%~20%比较稳妥。
• 检索数量：k值太小召回不全，k值太大引入噪声。试过500字块配k=4效果不错，但还是应该根据文档类型实测。
• 嵌入模型本身：如果你用的是通用嵌入模型，对垂直领域专有名词效果可能比较差。可以尝试微调嵌入模型，或者改用领域适配的模型。

这里我给一个可复现的小实验思路：随机挑10个真实问题，先人工从文档里找到标准答案，再用不同参数跑一遍RAG，统计“前3次结果里是否包含标准答案块”。这样一轮对比下来，哪个参数组合好用一目了然。

5.5 性能与并发调优

单线程跑invoke，在本地测试还行，一旦服务上线，QPS一高就扛不住了。LangChain的接口是支持并发调用的，你可以用无头Python脚本验证：

from concurrent.futures import ThreadPoolExecutor with ThreadPoolExecutor(max_workers=5) as executor: futures = [executor.submit(rag_chain.invoke, {"input": q}) for q in questions] results = [f.result() for f in futures]

这里的max_workers取决于API服务商的并发限制，建议从3开始压测，逐渐增大，直到出现限流错误就回退到上一个安全值。

另外，如果你的应用是Web服务，LangChain本身的组件初始化比较耗时，尤其是模型对象和向量库加载。这一部分应该做成全局单例，而不是每次请求都重新创建。把向量库在服务启动时加载进内存，连接复用，是为数不多性价比很高的优化手段。

我今天讲的这些，只是把LangChain的基础铺了一遍。说实话，这个框架初学觉得抽象，但一旦理解了它的“组件+链”模型，再去看Agent、Tool、多链路由这些进阶功能，会发现思路都是一脉相承的。我自己的体会是：不要试图一次学完所有模块，先把一个最典型的RAG链路跑通，再根据业务需求去查对应模块的文档，这才是最有效的学习路线。如果你正卡在某个报错上，不妨按第5章的思路从头捋一遍依赖、凭证、参数和检索效果，多数问题其实就出在这几步里。