做过几轮大模型应用开发之后你大概率会发现一个规律最初写的那段“调用接口→拼接提示词→解析结果”的脚本一旦功能变多就会迅速腐化成一个巨大的、全是耦合的“屎山”。提示词、模型调用、格式解析、上下文管理全部纠缠在一起改一处就要翻遍整个文件。LangChain 就是为解决这类痛点而生的。它不是某个单一的模型封装库而是一整套面向 LLM 应用开发的框架把构建过程中反复出现的模式比如模型调用、提示词管理、数据连接、代理决策、记忆存储全部抽象成标准模块。这篇教程面向刚接触 LangChain 的开发者先从核心设计思路讲起再逐层拆解基础组件最后带你自己动手搭一个能读取本地文档并回答问题的系统。整体节奏从概念到实践适合跟着一步步操作。1. 为什么需要 LangChain从零散调用到模块化编排1.1 裸写 LLM 调用的真实痛点先回想一下不用任何框架写一个“给用户生成摘要”的工具需要做什么。你要先构建提示词通常是一段带占位符的字符串然后调用某个模型接口传入提示词和参数拿到返回结果后要么直接展示要么用正则或字符串操作把关键字段抠出来。如果还要连续跟模型多轮对话就得手动维护一个消息历史列表每次把之前的内容全部传进去。这些逻辑看起来简单但叠加起来就非常痛苦。举一个我实际经历过的例子。某次我写一个知识库问答脚本提示词里需要注入用户当前的问题、系统设定、历史对话三条信息。第一版代码里我直接在函数内部用 f-string 拼字符串再调用模型接口。当时功能正常可后来要增加“记忆超时清理”“问题改写”“引用来源”三个功能时那一段代码彻底失控了。每次修改都要重新理顺上下文顺序而且只要一个条件分支没处理好提示词格式就出错模型返回质量也急剧下降。这还不是最麻烦的。换成不同的模型服务商接口参数就不同调用方式也不同想把应用从一套模型迁移到另一套等于重写一遍调用层。更别提如果要做检索增强生成还要自己管理文档切分、向量化、向量索引、相似度检索每一步都容易踩坑。裸写不是不行但复杂度和可维护性很快就会超过你的承受范围。1.2 LangChain 的核心设计思路是什么LangChain 的思路是把这些零散的步骤拆成带有明确职责的模块再用“链”Chain把模块串起来。它不强迫你一定要用某种架构而是提供一套组合积木让开发标准流程可以流水线化。每个模块只管一件事模型封装只管调用接口模板只管生成提示词输出解析只管把结果变成结构化数据记忆只管存储历史。然后由链负责编排它们之间的调用顺序和数据流。这种设计的最大价值是解耦。提示词怎么写、模型怎么调、结果怎么解析都可以独立修改而不影响其他部分。比如你想从一套模型服务商切换到另一套只要换一个模型封装对象其他代码基本不用动。同样的逻辑如果你要改变提示词风格只需要修改模板文件模型调用和结果解析的部分不需要碰。对于经常需要迭代调优的 LLM 应用来说这种模块化能力太重要了。LangChain 还统一了组件之间的交互数据格式。模型输入输出、提示词变量、解析结果都有明确的类型和约定这样不同开发者写出的模块也可以互相拼接。再加上框架本身提供了大量预构建的链和工具很多人连链都不用自己写直接拿现成的组合即可。2. 基础组件逐一拆解模型、提示模板与输出解析2.1 Chat 模型的统一封装LangChain 里所有模型交互都被封装成统一的接口最常见的是 Chat 模型组件。你不再需要关心底层服务商的具体 HTTP 请求格式只需要创建一个模型对象传入参数然后调用它的接口传入消息列表就能拿到回答。更贴心的是LangChain 对消息的类型有清晰划分比如系统消息、用户消息、AI 消息符合主流大模型的对话习惯。创建一个模型对象非常简单。以我自己常用的做法为例先安装对应模型服务的包再创建模型实例设定温度参数然后直接调用。这里要注意温度参数不是越高越好它对代码生成、结构化输出这类任务影响很大。实践经验是写代码或做分类时温度设低一点比如 0.0 到 0.3创意写作再适当调高。下面是一个最基础的调用示例from langchain.chat_models import ChatMyLLM # 以某主流模型服务商为例请替换成你自己的提供方和模型名 model ChatMyLLM( api_keyyour-api-key, model_namemy-llm-model, temperature0.2 ) response model.invoke(给我一个用Python判断回文串的示例代码) print(response.content)这里的统一封装带来的直接收益是你以后可以无缝切换模型提供方只需要换一个类改动量通常控制在几行以内。我自己在迁移过一次模型之后对这种封装就再也离不开了。注意如果你用的是本地模型或自建推理服务LangChain 同样有对应的封装接口思路一致只是参数稍有差异。2.2 Prompt Template把提示词变成可复用模块很多人低估提示词管理的重要性直到项目里出现十几段风格完全不同、分散在不同文件里的字符串拼接。Prompt Template 就是为了解决这个问题而存在的。它支持把固定的系统设定、变量化的用户输入、示例样本分离让提示词定义更清晰也更容易做版本管理。使用 Prompt Template 时你可以定义模板字符串用占位符表示动态内容然后通过传递实际值来填充。比如一个客服问答模板系统指令是固定的用户问题是变量历史对话也可以做成变量。这样以后调整措辞只改这一处不需要在代码里搜字符串。from langchain.prompts import ChatPromptTemplate template ChatPromptTemplate.from_messages([ (system, 你是一位严谨的技术支持工程师请简明扼要地回答问题。), (user, 用户的问题是{question}) ]) chain template | model # 先填充模板再调用模型 result chain.invoke({question: 为什么我的服务器连接超时}) print(result.content)在 LangChain 新版本中管道符|可以把组件串起来可读性非常高。你甚至可以把多个提示模板拼接起来形成更复杂的输入结构。我个人最推崇的做法是把系统提示词单独放到一个配置文件中代码里通过模板加载器读取这样真正运营时调整提示词不需要发布新代码非常实用。2.3 输出解析器从自然语言到结构化数据让模型返回一段自然语言很简单但把它变成 JSON、列表或代码就麻烦了。LangChain 提供了大量输出解析器专门负责把模型返回的内容转成程序更容易处理的结构。因为模型输出格式不稳定解析器还会做格式校验和修正配合带格式要求的提示词使用效果特别好。最常见的场景是让模型返回 JSON。你可以预先定义好期望的 JSON 结构在提示词里指定输出格式再用解析器加载。LangChain 中有专门的结构化输出解析器你只需要定义一个带类型说明的类解析器就能根据类结构指导模型生成对应字段并把结果转换为类实例。from langchain.output_parsers import PydanticOutputParser from pydantic import BaseModel, Field class MovieInfo(BaseModel): title: str Field(description电影标题) score: float Field(description豆瓣评分保留两位小数) reason: str Field(description推荐理由) parser PydanticOutputParser(pydantic_objectMovieInfo) format_instructions parser.get_format_instructions() prompt ChatPromptTemplate.from_messages([ (system, 根据用户输入提取电影信息严格按格式输出。\n{format_instructions}), (user, 帮我看看《盗梦空间》值得看吗) ]) chain prompt | model | parser parsed chain.invoke({format_instructions: format_instructions}) print(parsed.title, parsed.score)这里有一个很关键的技巧当你使用结构化解析器时提示词里必须完整写入格式说明否则模型很可能会返回多余的文字。实践下来与其靠提示词魔法不如先让模型严格输出 JSON再用解析器兜底。不要指望解析器能修复过度乱七八糟的输出它的容错能力是有限的。3. 动手实操20分钟搭一个文档问答系统3.1 环境准备与依赖安装在动手写代码之前先准备好基础环境。我建议你新建一个虚拟环境避免依赖互相污染。直接用 pip 安装核心库具体安装命令取决于你使用的模型提供方通常需要安装langchain和对应模型服务的扩展包。下面是我习惯的安装方式pip install langchain pip install langchain-community # 社区版通用组件 pip install langchain-experimental # 实验性功能按需安装如果你要做文档相关任务还需要安装文档加载和向量化相关的依赖比如文本切分器、向量计算库。这些都是标准化库安装即可。注意版本兼容问题尤其是 Python 版本不要盲目追求最新。我遇到过几次因为新版框架调整接口导致示例代码跑不通的情况所以如果卡住先看看自己的版本和官方文档。创建项目目录编写一个入口脚本后续所有代码都写在一个文件里便于演示。真实项目里我建议拆模块但初学阶段一个文件反而更容易理解调用流程。3.2 连接模型并实现基础问答首先实现最基础的问答功能。创建模型对象定义一个简单的提示模板然后从命令行接收用户输入返回模型回答。这一步可以把之前讲过的模型封装和模板拼接串联起来。from langchain.chat_models import ChatMyLLM from langchain.prompts import ChatPromptTemplate model ChatMyLLM(api_keyyour-api-key, model_namemy-llm-model) prompt ChatPromptTemplate.from_messages([ (system, 你是我的私人知识助手只依据给定资料回答不要编造。), (user, 资料{context}\n\n问题{question}) ]) chain prompt | model while True: question input(请输入问题) if question exit: break context 暂无资料请直接回答。 result chain.invoke({context: context, question: question}) print(result.content)这一步的核心是理解 chain 的调用方式。invoke传入的是模板中所有占位符的字典少一个都会报错。我经常看到新手在多个模板变量时漏掉某个字段导致运行失败。调试时如果报缺少关键字段先检查模板中的变量名和传入的键是否完全一致尤其是带下划线和驼峰命名的区别。3.3 引入文档加载、切分与向量检索光靠模型自身知识还不够真正的知识库问答必须引入外部文档。这里我用一个更完整的方案加载本地 Markdown 或 TXT 文件把内容切分成小块然后用向量化模型把每一段转成向量存入内存向量库回答用户问题时先检索最相关的内容再交给模型处理。from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import MyEmbeddings from langchain.vectorstores import Chroma loader TextLoader(knowledge.txt) documents loader.load() text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) texts text_splitter.split_documents(documents) embeddings MyEmbeddings(api_keyyour-api-key) vectorstore Chroma.from_documents(texts, embeddings)这段代码做了什么第一步加载文档第二步把文档切成多个 chunks第三步用嵌入模型将 chunks 向量化并存入向量库。运行时它会默认持久化到本地目录方便下次复用。chunk_size和chunk_overlap是经验参数需要根据文档类型调整。太大会导致检索粒度粗太小会丢失上下文。我用 500 字加 50 字重叠的效果比较均衡。检索出来之后把相关片段拼接进上下文字段再喂给模型。整个链路就变成用户问题 → 向量检索 → 拼接上下文 → 模型生成。这是最基本的检索增强生成应用。retriever vectorstore.as_retriever(search_kwargs{k: 3}) def answer_with_source(question): docs retriever.get_relevant_documents(question) context \n.join([doc.page_content for doc in docs]) result chain.invoke({context: context, question: question}) return result.content检索器返回的文档对象有序且带有元数据你可以把来源文件名、原始段落打印出来方便核实。我强烈建议开发阶段都加上来源展示至少自己能看到模型回答是不是真的基于资料避免产生幻觉。后续如果要提升精度可以调整检索参数比如限制检索相似度阈值或者尝试不同的嵌入模型。这一步没有最优解只有最适合你数据和场景的组合。4. 常见问题与排查技巧实录4.1 API 密钥与连接异常新手最容易踩的坑就是 API 密钥缺失或格式不对。LangChain 的模型封装会从环境变量或你传入的参数里读取密钥如果读不到运行时会抛认证错误提示信息往往不够直观。建议你在项目根目录建一个.env文件用合适的工具加载环境变量不要把密钥硬编码进代码里。from dotenv import load_dotenv load_dotenv()另外还要检查网络环境不同服务商的 API 域名可能不同有些区域访问延迟高超时报错让人误以为是代码问题。如果你是自建模型服务地址配置也要写对。排查时先从最简单的模型调用开始确认能返回内容再逐步叠加链、检索、代理等复杂结构。4.2 提示词与模型返回格式不一致使用输出解析器时模型偶尔会返回 JSON 之外的内容比如开头解释、多余的空格或者引用。解析失败会直接抛异常。解决办法有两个方向一是强制提示词更加严格比如要求只输出 JSON不要包含解释说明二是捕捉解析异常然后做重试用模型纠正自己的输出。我常用的一种方式是把上一次失败的输出作为上下文让模型重写为正确格式。LangChain 有一些链能自动实现这种修复但你自己写也不难。关键点是调试时要打印原始模型输出不要只看最终报错。很多时候问题不在解析器而在模型生成阶段。4.3 上下文过长与内存泄漏文档问答中常见的隐藏问题就是上下文长度超限。把所有检索到的片段全塞进提示词很容易超过模型允许的 token 数量。解决办法是严格控制检索片段数量比如只取前 3 段同时把每段进一步裁剪。如果多轮会话历史消息也不能无限增长一定要做滑动窗口或摘要压缩。内存泄漏这块使用内存向量库时尤其明显。每次创建新向量库对象都会占用内存长时间运行要注意复用已有向量库从本地目录加载而不是每次重新向量化。我有一次运行服务连续两天内存占用涨了近一倍最后发现是反复创建嵌入对象而没有复用。提示进度到这一步你已经掌握了 LangChain 最核心的基础链路。对于那些觉得框架太抽象的人来说最好的方式就是先跑通一个最小示例然后再回头理解每个组件的职责模型效率会高得多。我个人在实际操作中的体会是LangChain 的学习曲线并不平缓前期容易被各种抽象概念绕晕。但只要你亲手搭过一遍文档问答后面再看代理、记忆、工具调用这些进阶模块就会非常顺。每个组件本质上都是在回答一个固定的问题输入从哪来输出去哪去中间怎么转换。顺着这条主线你很快就能把框架用出属于你自己的最佳实践。