LangChain 和 LangGraph 这套组合到 2026 年再看已经不是新鲜名词了。但零基础入门的难点一直没有变今天看到一个 RAG 实战明天刷到一篇 Agent 开发后天又冒出一堆 MCP 的教程资料很多学习路径却完全是乱的。这篇文章想给你一条能把 LangChain、LangGraph、RAG、Agent、MCP 串起来的实战主线。定位很直接零基础、能落地、先跑通最小例子再逐步加功能。不会把源码逐行拆开讲也不会一上来就丢一个上千行的企业级项目。它更像一套我重新整理过的学习顺序目的是让你在最短时间内建立起“我知道这东西能干什么、下一步该学什么”的判断力。如果你正卡在“LangChain 和 LangGraph 到底什么关系”“RAG 和 Agent 哪个先学”“MCP 要不要现在碰”这些问题上这篇文章可以当成你的第一份路线图。1. 先搞懂 LangChain 和 LangGraph 的关系别把学习顺序学反很多人刚入门就卡在这里LangChain 和 LangGraph 名字这么像到底有什么区别先学哪个我的答案是先理解 LangChain 的组件再学 LangGraph 的编排。顺序反了你会在状态管理、条件路由这些概念里绕很久。1.1 LangChain 解决什么问题LangChain 的核心价值是“组件化”。它把 AI 应用开发里经常用到的环节拆成了可拼装的部分提示词模板、模型调用、输出解析、记忆、文档加载、文本切分、向量存储、检索、工具调用。每个部分都是一个独立模块用组合的方式拼成一条链。比如一个最简单的问答链它的执行过程是这样的用户输入问题。组装好提示词。调用大模型。解析输出。返回结果。这条链路在 LangChain 里写起来非常短因为每一步都有现成封装。这种设计解决了什么问题它把“应用逻辑”和“模型交互细节”分开了。你不用每次写代码都关心模型请求的格式、超时处理、消息结构只需要关心业务链条怎么组织。所以 LangChain 最适合的场景是快速搭建原型、处理线性流程、把几个 AI 能力组合成一个工具。它的问题是如果流程很复杂比如要根据模型输出决定走哪个分支或者要循环调用同一个节点直到满足条件用普通的链式结构写起来会很别扭可读性也越来越差。1.2 LangGraph 在 LangChain 之上补了什么能力LangGraph 不是用来替代 LangChain 的它是给 LangChain 加状态机和图编排能力。在 LangGraph 里应用被描述成一张图。图由节点、边、状态三部分组成节点执行具体逻辑的函数比如调用模型、调用工具、处理文档。边节点之间的流转关系。状态在整个图执行过程中共享的数据比如消息列表、当前步数、中间结果。这个设计最大的价值是流程变成可以控制的了。你可以根据一个节点的返回结果来决定下一步走 A 分支还是 B 分支也可以设计循环让某个节点反复执行直到满足退出条件。这些能力正好是 Agent 开发需要的。所以更准确的理解是LangGraph 继承并扩展了 LangChain。它没有抛弃 LangChain 的模型封装、提示词模板、工具定义这些底层能力而是在上面增加了一层更灵活的编排机制。对比维度LangChainLangGraph核心思想组件和链式调用图、状态、节点、边适合场景线性流程、原型演示复杂流程、循环、条件分支状态管理较弱通常靠外部传参内置状态对象在节点间传递学习曲线入门快需要理解图结构和状态概念典型应用RAG 基础链、Prompt 拼装Agent、多智能体、人工确认流程2. 环境准备先搭出一套能启动的最小环境学这类框架最忌讳的就是还没跑通代码就开始研究概念。我自己测试新项目时会先做一件事用最快速度把最小示例跑起来让日志、输入输出、资源占用都出现在眼前。有了这个基础再去看文档和源码都更容易理解。2.1 安装依赖包的顺序LangChain 和 LangGraph 都是 Python 生态的库安装方式不复杂。建议先建一个独立的虚拟环境不要直接装到系统 Python 里避免不同项目之间互相污染依赖版本。python -m venv .venv source .venv/bin/activate # Windows 下用 .venv\Scripts\activate pip install --upgrade pip pip install langchain langchain-community langgraph注意一点这些库的版本更新速度很快接口也会调整。这里给的命令只是一个最基础组合你安装的时候要以当前官方文档的依赖说明为准。如果你要接某个具体模型服务还要额外安装对应的封装包比如 langchain-openai、langchain-ollama 或 langchain-anthropic。建议先不要安装一堆用不到的扩展包。缺什么装什么能减少很多版本冲突问题。2.2 第一个 LangChain 示例用一条链完成问答这个示例不涉及文档和向量库只验证模型调用链是否正常from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # llm 换成你实际使用的模型封装 # 例如 ChatOllama 或 ChatOpenAI llm None prompt ChatPromptTemplate.from_messages([ (system, 你是一个擅长解释概念的助手请用简洁的语言回答。), (human, {question}) ]) chain prompt | llm | StrOutputParser() result chain.invoke({question: 什么是 RAG}) print(result)这个例子里的|符号在 LangChain 里叫 LCEL表示把多个组件连接成链。上面的代码逻辑很好理解先把用户问题填入提示词模板再交给模型最后从模型输出中解析出纯文本结果。如果你的 API Key、本地模型服务没有配置好这一步就会直接暴露问题。这也是我说要先跑最小示例的原因只有把环境问题先解决掉后面学 RAG 和 Agent 时才不会把“模型连接失败”误判成“框架用错了”。2.3 第一个 LangGraph 示例感受状态、节点、边的关系LangGraph 的最小示例同样不复杂重点是让你直观感受它的三个核心概念。from typing_extensions import TypedDict from langgraph.graph import StateGraph, START, END class State(TypedDict): messages: list count: int def node_a(state): return { messages: state[messages] [A], count: state[count] 1 } def node_b(state): return {messages: state[messages] [B]} graph StateGraph(State) graph.add_node(a, node_a) graph.add_node(b, node_b) graph.add_edge(START, a) graph.add_edge(a, b) graph.add_edge(b, END) app graph.compile() result app.invoke({messages: [], count: 0}) print(result[messages])执行结果是[A, B]。这个例子很短但包含了几件关键的事State 定义了整个流程共享的数据结构。每个节点接收当前状态返回更新后的字段。边的定义决定了执行顺序。compile 之后才能正式调用。这里最容易出问题的概念是“状态不可变”。在 LangGraph 里节点返回的不是在原状态上乱改而是返回要更新的字段框架会自动合并。你只需要保证每个节点的输入输出结构一致就行。3. RAG 实战四步搭出一个最小知识库问答RAG 是现在最值得优先学的实战主题。它的核心价值一句话就能说清让模型在生成答案之前先从你的资料库里找到相关内容作为参考。这样回答不再只靠模型记忆而是有据可查。3.1 为什么要拆成四个步骤一个最小 RAG 流程通常分成这几步加载文档。切分文本。向量化并存储。检索相关片段并交给模型生成。分开做的好处是每一步都可以独立测试和优化。比如切分粒度太大导致检索不精准你不需要动模型只需要调整拆分参数。如果检索出来一堆无关内容你也不用急着换模型可以先检查向量化模型和检索策略。这个思路在我实际做知识库项目时帮了大忙。很多人一遇到效果不好就换模型换了好几个还是很差最后发现是文档切分不合理或者输入文档本身格式混乱。先拆步骤再定位问题比盲目调参高效得多。3.2 最小实现骨架先看文档加载和切分部分from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter loader TextLoader(docs/guide.txt) documents loader.load() splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100 ) chunks splitter.split_documents(documents)这里的chunk_size是每个文本块的最大字符数chunk_overlap是相邻两个块之间保留的重叠长度。为什么要重叠因为如果正好在句子的中间断开前后语义会被切断。保留一部分重叠可以让检索时更容易命中完整语义。chunk_size 的具体取值要看文档类型。代码片段、表格、合同类文档的合适粒度差异很大。我个人建议从 400 到 800 之间开始试不要一上来就追求大块文本。块越大向量化后包含的信息越多但如果块太大检索回来的内容可能有一半与问题无关。向量化和检索部分需要选择 embedding 模型和向量存储。这部分代码不同项目差异较大但整体结构是固定的# embeddings 负责把文本转成向量 # vector_store 负责存储和检索 # 组装时把切好的 chunks 写入向量库 # 查询时用问题向量到库里做相似度搜索在本地学习时可以先选一个轻量的向量库比如 Chroma 或 FAISS配合一个容易获取的 embedding 模型来跑通流程。低配置环境下重点是把运行链路打通而不是追求超大知识库。3.3 检索效果差时先检查哪里RAG 项目最常见的抱怨是“检索出来的东西不对”。遇到这个问题我一般按下面这个顺序排查看文档加载结果。是不是真的把文件内容读进来了编码是否正确某些 PDF 是不是扫图片。看切分后的块。有没有明显断开、重复、内容过少或过多的情况。看向量化模型。通用 embedding 模型对专业术语的理解有限必要时换领域相关的向量模型。看检索方式。纯向量检索不一定适合所有场景工程上经常用“多路召回”来提分。多路召回的意思是不止用向量相似度一路检索还可以结合关键词匹配、结构化筛选等方式拿到多份候选结果后再合并排序。这是 RAG 项目从“能跑”走向“好用”时很常见的优化方向。另外RAG 效果不能只靠感觉判断。可以准备一批有标准答案的测试问题看检索命中率和答案完整性。没有评测指标的 RAG 优化基本等于盲调。3.4 从检索到生成检索出来的相关片段最终要拼到提示词里交给模型生成。这个环节有几个常见问题上下文太长检索到的片段太多超过模型上下文窗口。无关内容干扰检索结果包含大量不相关内容模型被带偏。缺少引用回答没有标注出处无法回溯到原始文档。一个比较稳妥的生成提示词结构是先说明模型只根据给定参考资料回答再列出检索片段最后给出用户问题。如果检索结果与问题无关允许模型直接说“资料中没有相关内容”不要强行编造。4. Agent 开发把工具调用变成可控流程学会 RAG 之后下一个核心主题就是 Agent。Agent 和普通聊天最本质的区别是它可以调用外部工具并根据工具返回结果继续决策。4.1 最小工具定义在 LangChain 里定义一个工具通常只需要一个函数加上工具装饰器from langchain_core.tools import tool tool def get_user_balance(user_id: str) - str: 根据用户 ID 查询账户余额参数为字符串形式的用户标识。 # 这里实际会调用数据库或接口 return 128.50工具定义看似简单真正重要的其实是两件事函数上面的描述文本以及参数的类型和含义。这个描述会被模型读取模型靠它来判断“什么时候应该调用这个工具”“传入什么参数”。描述写得模糊工具就很容易被误调用。所以我在项目里会把工具描述写得像接口文档一样清楚功能是什么、参数含义、有什么限制、出错时返回什么。这比把工具数量堆上去更重要。4.2 在 LangGraph 里把工具调用变成状态机Agent 的完整循环用 LangGraph 来表达就很清晰模型节点接收消息如果决定调用工具输出 tool_calls。图根据 model 节点的输出进入工具节点。工具执行完成后把结果作为 tool 消息放回消息列表。流程回到模型节点模型根据工具结果生成最终回答或继续调用下一个工具。当模型不再请求工具时流程结束。核心代码结构类似这样def should_continue(state): last_message state[messages][-1] if last_message.tool_calls: return tools return end graph.add_conditional_edges( agent, should_continue, {tools: tools, end: END} )所谓“多智能体”本质上也是多个节点或子图的编排。不要在开始阶段被这个词吓到。你只要学会了用状态管理单智能体的工具循环多智能体只是在更高一层增加了角色拆分和消息路由。4.3 让 Agent 不卡死、不静默失败Agent 开发里最真实的体验是不是跑不起来而是跑起来之后进入死循环、报错中止、输出内容不完整。我建议提前做好这几件事设置最大迭代轮数防止模型反复调用工具停不下来。把工具执行异常封装成正常的返回消息而不是直接中断流程。记录每一步的模型输出和工具返回值方便回放调用链。不要把真相放在“最后答案”里而是放在完整 trace 里。比如你遇到一个报错“agent execution terminated due to error”。单看这句话几乎没有排查价值。此时要去看完整堆栈里最先出现异常的位置是模型调用失败、工具内部报错还是状态机结构问题。多数情况下这类错误不是模型不行而是某个工具函数内部抛了异常或者返回格式不符合预期。关于“给 Agent 增加技能”这件事理解也应该是这样的给节点新增工具或者把一组子流程封装成独立节点再由上层节点按条件调用。它不是魔法就是图的扩展。5. MCP 是协议不是框架理解它的结构比记名字更重要如果说 RAG 是数据接入方式Agent 是执行流程那 MCP 就是模型和外部工具之间的标准化连接方式。5.1 MCP 解决什么问题MCPModel Context Protocol是一套开放协议用来连接大模型应用与外部工具、数据源。它定义了模型如何发现工具、如何了解工具参数、如何发起调用、如何拿到结果。它的标准结构一般可以理解成三部分Host大模型应用本体比如聊天工具、命令行工具。Client负责和 Server 通信的客户端部分。Server提供工具、资源、提示词等能力的一方比如数据库 MCP Server、文件系统 MCP Server。你可以把 MCP 理解成“大模型世界的接口规范”。没有这个规范时每个工具接入都要单独开发适配层模型每接入一个新系统就要学一套新交互方式。有了规范之后只要两边都遵守协议就能互相识别。现在不仅聊天类应用在支持 MCP很多设计工具、建模软件、数据库客户端也在提供自己的 MCP Server。这种生态扩展对学习是好事因为你可以用真实可见的工具列表、参数定义来理解协议而不是只看概念。5.2 MCP 和普通 API 的区别这是最容易混淆的点。MCP 本身不是用来替代 REST API 的它更多是定义了大模型与工具之间的交互方式。普通 API 通常是为特定业务设计的每个系统有自己的鉴权方式、请求格式、返回结构。MCP 用一套标准结构来描述“这个服务器提供了哪些工具”“每个工具的输入输出是什么”让大模型可以动态发现并调用。对比维度普通 APIMCP关注点业务功能工具发现、调用、结果返回工具描述通常独立文档通过协议暴露给客户端接入成本每个系统单独适配统一协议后可复用的能力和模型关系通常由开发者在代码里调用模型可以按需选择工具调用这个区分很重要。很多人在学习时把 MCP 当成一个具体框架去研究结果越看越懵。它其实更像一套“语言”不同系统用这个语言对话。5.3 调试 MCP 时该看哪些信息如果你刚开始接触 MCP建议优先关注四个信息Server 是否成功启动。很多 MCP 配置错误第一时间都体现在启动阶段比如命令路径不对、环境变量缺失。工具列表是否加载。启动成功不代表工具加载成功要看 Server 暴露了哪些工具。调用参数结构。工具需要什么参数参数类型是什么哪些是必填。调用返回和错误。工具执行失败的返回值是理解问题的关键。在配置层面上常见的检查点包括Server 启动命令是否正确、依赖是否安装、工作目录是否存在、权限是否足够。如果你在配置一个读取数据库的 MCP Server还要额外确认数据库连接信息和网络连通性。这些排查思路和普通后端服务调试没有本质区别。先启动、再列表、再单次调用、最后再连模型按照这个顺序走问题会好定位很多。6. 零基础最容易踩的报错给一套通用排查链路报错是最公平的老师。你每排掉一个报错都会比看十篇教程更有收获。但是要学会用正确方式排错不要一看到英文堆栈就发慌。6.1 五类常见问题及排查方向现象常见原因排查方向模型调用报认证失败或超时环境变量没配好、模型服务地址不对检查 API Key、服务地址、网络连通性安装依赖后导入报错版本冲突或缺少子依赖确认当前版本的依赖要求重建虚拟环境文档加载结果为空路径错误、编码不支持、文件格式特殊先直接用本地文件读取验证检索结果为空或混乱向量库没写入数据、查询方式不对确认写入数量打印检索原始输出Agent 执行中止且无具体答案工具内部异常、最大轮次耗尽、状态结构错误查看完整 trace而不是只看最终报错先说明一下这里不是让你背表格而是建议你养成“分模块定位”的习惯。模型、数据、流程、工具每个模块都有各自的问题表现和排查入口。6.2 完整排查链路是什么样的假设你的 RAG 项目加载 PDF 文档时返回了空列表。第一反应不要怪 PDF 加载库按顺序走一遍确认文件路径存在路径中包含中文或空格时优先改成简单路径。确认文件内容不是扫描图片。扫描 PDF 本质上是一堆图片不做 OCR 是读不出文字的。用最简单的文本读取方式验证文件本身可读。再切到文档加载器看它支持哪些参数比如是否要指定页面范围或解析策略。最后再检查加载结果被后续哪些环节过滤掉了。这个顺序的本质是先确认数据源本身正常再确认加载环节最后确认下游处理。如果你一上来就调整解析参数很可能绕了远路。6.3 低配置机器的判断标准本地跑这些框架机器配置确实会有影响但没有一些人说的那么夸张。关键看你跑的是哪些环节文本加载、切分、流程编排CPU 和内存为主普通电脑都能跑。embedding 本地模型会有内存或显存占用低配置时尽量选小尺寸模型。大语言模型本地推理对显存或内存要求高资源不够时优先改用 API不要硬扛。向量库检索数据量大时需要足够内存小知识库用轻量向量库没问题。低配置机器能跑不代表适合批量跑。如果只是学习默认配置通常够用。如果要处理几千个文档就要考虑资源占用和任务队列了。7. 零基础 30 天学习路线把内容拆进时间计划里最后聊一下学习计划。很多人的问题不是不努力而是同时打开十几个文档今天看 LangChain明天学 LangGraph后天刷 MCP知识点全在脑子里打架。我给零基础读者建议的顺序很固定RAG 先行Agent 跟上MCP 最后。7.1 前两周把 RAG 跑稳第一周只做一件事理解 LangChain 的基本组件并用它搭一个基于文档的问答链。不着急研究 Agent 和 MCP。第 1 天到第 3 天熟悉 Prompt、模型调用、输出解析。第 4 天到第 7 天跑通文档加载、文本切分、向量化、检索。第 8 天到第 14 天把检索结果接入生成环节做一个最小 RAG 知识库并准备一批测试问题评估效果。这个阶段的关键逻辑是RAG 涉及数据侧和模型侧的协作它练的是最基本的工程能力。先把这条路跑通后面学 Agent 时你会少掉很多焦虑。第二周快结束时可以尝试做一个小项目。比如把你的学习笔记、项目文档整理成一个小知识库问它里面的问题。不要追求系统复杂重点是完整闭环。7.2 后两周进入 Agent 和 LangGraph 状态机第三个星期开始接触 LangGraph。不要一上来就复制网上的完整项目仍然从最小状态图开始。先画三步图再添加条件分支和循环最后把工具调用接进去。第 15 天到第 18 天掌握 State、Node、Edge、条件路由。第 19 天到第 21 天给 Agent 增加两三个工具让它在循环中调用工具并生成最终回答。第 22 天到第 24 天为 Agent 增加失败重试、最大轮次控制、日志追踪。最后一周再碰 MCP。先理解 Host、Client、Server 的分工再用一个现成的 MCP Server 跑通工具列表查看和调用流程。可以找一款你熟悉的设计、建模或数据库工具看看它的 MCP Server 暴露了哪些能力。第 28 天到第 30 天把三个主题串起来做一个小作品用 RAG 提供知识和检索能力用 Agent 决定何时检索、何时调用工具把外部数据源用 MCP 方式接入。这个作品不用很复杂但至少要能在你本机稳定跑通。7.3 怎么判断自己真的学懂了学完一个阶段后比起“我看完了多少篇教程”更值得关注的判断标准是能不能不查资料写出最小 RAG 流程能不能说清为什么检索结果不好时要检查切分和向量模型能不能在 LangGraph 里增加一个节点并让它在特定条件下跳转能不能定位 Agent 调用工具失败时问题出在模型、工具还是状态能不能解释 MCP Server 启动后工具没有加载时该看哪些配置这些标准不需要你背出所有 API。知道自己该查什么、问题出在哪一层、下一步要改哪里才是更重要的能力。踩过几次之后你会发现学 LangChain 和 LangGraph真正难的从来不是某一个库的 API而是在一堆新概念里保持主线的清晰。主线就五件事链、状态、检索、工具、协议。先把这条线跑通后续的新特性都只是在这条线上添加分支而已。