打开你的浏览器收藏夹大概率躺着这样的标题LangChain 入门、LangGraph 实战、Agent 开发、RAG 知识库……收藏的时候信心满满真的打开 IDE 准备写代码又开始迷茫到底先学哪个项目该从哪下手为什么照着别人的代码敲还是报错这不是你不够努力而是很多人把学习顺序搞反了。LangChain、LangGraph、Agent、RAG 这四个词并不是并列的新框架而是一条层层递进的技术链。先理解这条链再动手写代码才能真正把技术吃到项目里。这篇文章不打算帮你收藏更多视频而是给出一条从入门到企业级实战的完整路线并配上一套能直接跑通的最小示例。1. 这篇文章真正要解决的问题先给一个明确判断LangChain 生态真正降低的不是“调用大模型”的入门门槛而是“把大模型能力编排进业务系统”的工程门槛。很多人以为学 LangChain 就是学 API其实学的是如何组织提示词、如何管理状态、如何接入工具、如何控制流程。不同阶段的读者痛点完全不同刚入门的人卡在环境配置和第一个调用上看到的一堆概念术语让大脑过载。已经会调用模型的人不知道下一步该学什么总觉得自己是在“调包”。正在做企业项目的开发者发现本地 Demo 跑得通一到生产环境就崩性能、成本、可观测性、权限管理全是问题。所以这篇文章的重点不是列出所有 API而是帮你建立一张地图每个技术解决什么问题、和前后环节怎么衔接、写代码时哪里容易踩坑、生产环境怎么兜底。读完你能得到两样东西一条清晰的学习路线和一套可以直接复制运行的最小代码示例。2. 四个核心概念LangChain、LangGraph、Agent、RAG2.1 LangChain编排底座LangChain 可以理解为一个“大模型工具链的粘合层”。没有它你需要自己写函数去拼接 Prompt、调用模型、解析输出有了它这些动作变成了一条标准化管道。它的核心抽象有几个Model统一封装不同厂商的大模型接口。Prompt Template把提示词变成可复用的模板而不是散落在代码里的字符串。Output Parser把模型输出解析成结构化数据比如 JSON、列表。Chain把 Prompt、Model、Parser 串起来形成一条可执行的管道。Memory在多次对话中保留历史信息解决“模型默认无状态”的问题。Retriever从外部知识源检索内容为 RAG 打基础。如果只看表面很容易误以为 LangChain 只是在包装 API。它的真正价值是让你用声明式的方式组合大模型能力后面接入 RAG、Agent 时这套抽象能大幅降低代码的耦合度。2.2 RAG把私域知识接入大模型RAG全称 Retrieval-Augmented Generation检索增强生成。它在模型回答问题之前先从外部知识库检索相关文档片段再把这些片段作为上下文传给模型。为什么需要 RAG大模型的知识是训练时固化的无法覆盖你公司内部的制度、项目文档、产品手册也无法自动更新到最新知识。RAG 的解决思路是“不重新训练模型而是在推理时补充上下文”。一个典型的 RAG 流程是加载文档比如 PDF、Markdown、文本文件。拆分成小的文本块避免超出模型上下文窗口。用 Embedding 模型把文本块转成向量。保存到向量数据库。用户提问时把问题转成向量检索最相似的文本块。把检索结果拼进 Prompt交给模型生成答案。这里容易出问题的地方集中在加载、拆分和检索质量上。很多人跑通了 RAG Demo但回答效果很差往往不是模型不行而是文档解析太粗糙、分块策略不合理、检索召回不准确。2.3 Agent让模型调用工具Agent 的核心是让模型不再是“只输出文字”而是能够决定“调用哪个工具”来完成一个任务。比如查天气、查数据库、调用内部 API、执行计算。传统程序是“人写死逻辑”Agent 的思路是“模型根据用户意图动态决策”。它的基本循环是接收用户任务。模型判断需要哪个工具。调用工具拿到结果。模型根据工具结果组织最终回答。这里最容易踩的坑是“过度信任模型”。模型可能选错工具、传错参数甚至在被赋予高权限工具时做出危险操作。所以在工程上Agent 不是“给模型一个工具列表”那么简单还需要做边界控制、参数校验、日志审计和失败回退。2.4 LangGraph有状态、可控的工作流引擎LangGraph 解决的问题是复杂流程里的“状态管理”和“流程控制”。前面提到的 Agent 是循环过程实际业务里往往是更复杂的流程先做意图识别再决定走 RAG 分支还是普通对话分支中间可能要调用多个工具还要处理失败重试。用普通 Python 代码写这种逻辑容易变成一大堆 if-else 和全局状态很难维护。LangGraph 把流程建模成一张图Graph节点是处理逻辑边是流转关系。它借鉴了图计算和状态机的设计思路让流程变得明确、可控、可测试。对比来看技术关注点比喻LangChain组件编排和链路拼接流水线上的传送带RAG外部知识接入给模型配一本资料库Agent模型动态决策调用工具给模型配一双手LangGraph复杂流程的状态流转整个车间的控制系统2.5 它们之间的关系网上最常见的问题就是“LangGraph 会不会取代 LangChain”。更稳妥的判断是它们有不同的定位。LangChain 提供组件和链路抽象LangGraph 提供复杂流程的控制能力。在实际项目中LangChain 的模型、提示词、检索器组件完全可以嵌入 LangGraph 的节点里使用。学习顺序建议是先用 LangChain 跑通单条链路再用 RAG 解决知识接入接着用 Agent 扩展工具能力最后用 LangGraph 把复杂流程工程化。这个顺序才是“少走弯路”的核心。3. 环境准备与前置条件3.1 运行环境本文的示例代码以 Python 为主。推荐环境如下Python 3.10 或更高版本3.9 也可以但 3.10 及以上对类型注解和异步支持更友好。一个可以访问大模型 API 的环境示例中会使用 OpenAI 兼容接口你需要准备好 API Key。操作系统不限Windows、macOS、Linux 都可以。LangChain 的版本迭代比较快网上的课程标题和教程版本经常不一致。学的时候不要把版本号当成唯一标准关键是理解对象、链、检索器、图这几个核心抽象。安装时建议直接安装最新稳定版具体以官方文档为准。3.2 安装依赖建议先创建虚拟环境避免污染系统级 Python 环境。python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate安装核心依赖。下面的命令会安装 LangChain、LangGraph、LangChain OpenAI 集成、文档加载器、文本拆分器和 FAISS 向量库。pip install langchain langgraph langchain-openai langchain-community langchain-text-splitters faiss-cpu如果你的环境网络受限可以配置国内 PyPI 镜像pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain langgraph langchain-openai langchain-community langchain-text-splitters faiss-cpu安装完成后建议验证一下关键包是否可用python -c import langchain; import langgraph; print(ok)如果输出 ok环境就准备好了。如果你使用 OpenAI 兼容的本地模型服务比如 Ollama 或 vLLM 启动的服务也可以在代码中把 base_url 指向本地地址原理是一样的。4. 学习路线与核心流程拆解4.1 第一步跑通一次标准模型调用不要一上来就写 RAG 和 Agent先完成最小闭环一条消息进入模型模型返回文本。这一步的目标是确认 API Key 和网络环境没问题。如果这一步失败后面的所有代码都没有意义。常见错误包括API Key 写错、模型名不存在、网络不通、环境变量未读取。4.2 第二步加入提示词模板和输出解析让 Prompt 变成可复用模板让输出变成结构化数据。这步让你从“写死字符串”过渡到“组织语言资产”。在很多项目里提示词是需要单独管理的而不是散落在业务代码中。4.3 第三步实现一个最小 RAG从本地文本文件开始用 FAISS 做向量检索。你需要理解“文档加载、拆分、向量化、检索、生成”这五个环节。注意这五个环节里检索质量决定了整个 RAG 的上限。4.4 第四步加入 Agent 工具调用给模型一个简单的工具比如计算器或查天气函数让模型学会在需要时调用工具。这步会让你理解“模型不是直接输出答案而是先调用工具拿结果再组织答案”。4.5 第五步用 LangGraph 控制流程把上面的能力组合成一张图根据用户输入判断走 RAG 还是普通对话或者是否需要调用工具。这步会让你从“线性链路”走向“有状态的工作流”。下面按这个学习路线给出可直接运行的代码。5. 完整示例与代码实现5.1 LangChain 基础调用示例先实现最基本的模型调用。这里使用 OpenAI 兼容接口如果你使用其他服务商只需要改模型名称和 base_url。# 文件路径examples/01_basic_chain.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser llm ChatOpenAI( modelgpt-4o-mini, temperature0, ) prompt ChatPromptTemplate.from_messages([ (system, 你是一名资深技术编辑擅长用简洁的语言解释复杂概念。), (human, 请用不超过50个字解释一下{topic}), ]) chain prompt | llm | StrOutputParser() result chain.invoke({topic: 什么是 RAG}) print(result)这段代码的逻辑是先定义模型对象设置温度和模型名再定义提示词模板其中{topic}是占位符然后通过|运算符把提示词、模型、输出解析器串成一条链最后传入参数并执行。运行方式export OPENAI_API_KEY你的API Key python examples/01_basic_chain.py如果 API Key 是通过环境变量配置的代码中的ChatOpenAI会自动读取。输出应该是模型返回的一段简短解释。5.2 最小 RAG 示例这里用一个本地文本文件作为知识库演示完整的 RAG 流程。先准备一份知识文件。# 文件路径docs/knowledge.txt LangGraph 是一个用于构建有状态 AI 应用的工作流引擎。 它适合处理需要多步决策、条件分支和工具调用的复杂场景。 RAG 技术通过在生成前检索外部知识可以显著提升回答的准确性。 Agent 是能够根据用户意图动态调用工具的程序模块。然后运行下面的代码# 文件路径examples/02_rag.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import FAISS from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 1. 加载文档 loader TextLoader(docs/knowledge.txt, encodingutf-8) docs loader.load() # 2. 拆分文档 splitter RecursiveCharacterTextSplitter(chunk_size200, chunk_overlap20) chunks splitter.split_documents(docs) # 3. 向量化并存储 embeddings OpenAIEmbeddings() vectorstore FAISS.from_documents(chunks, embeddings) retriever vectorstore.as_retriever(search_kwargs{k: 2}) # 4. 构建生成链路 prompt ChatPromptTemplate.from_messages([ (system, 请根据以下资料回答问题。如果资料中没有答案请直接说不知道。\n\n资料\n{context}), (human, {question}), ]) llm ChatOpenAI(modelgpt-4o-mini, temperature0) def format_docs(docs): return \n\n.join(doc.page_content for doc in docs) chain ( { context: retriever | format_docs, question: lambda x: x[question], } | prompt | llm | StrOutputParser() ) # 5. 提问 result chain.invoke({question: LangGraph 适合什么场景}) print(result)代码的关键点有四个文档拆分使用chunk_size200表示每个块约 200 个字符chunk_overlap20表示块之间保留 20 个字符的重叠。这个参数需要根据实际文档调整。FAISS 是内存向量库适合本地学习和原型验证。企业项目中通常会替换为 Milvus、pgvector 或 Elasticsearch。retriever | format_docs表示检索结果先经过format_docs函数格式化成字符串再填充到 Prompt 的context位置。lambda x: x[question]的作用是从输入字典中取 question 字段。运行后回答应该来自知识文件中的内容而不是模型凭记忆生成的答案。这就是 RAG 的基本效果。5.3 LangGraph 状态图示例下面用 LangGraph 实现一个简单流程根据用户输入判断是否需要走 RAG 分支。# 文件路径examples/03_langgraph.py from typing import TypedDict from langgraph.graph import StateGraph, START, END class State(TypedDict): input_text: str decision: str result: str def analyze(state: State): 判断用户输入是否涉及知识库查询 text state[input_text] if 知识库 in text or RAG in text or 文档 in text: decision rag else: decision chat return {decision: decision} def handle_rag(state: State): 模拟 RAG 处理流程 return {result: 走 RAG 流程检索知识库后回答} def handle_chat(state: State): 模拟普通对话流程 return {result: 走普通对话流程直接回答} graph StateGraph(State) graph.add_node(analyze, analyze) graph.add_node(handle_rag, handle_rag) graph.add_node(handle_chat, handle_chat) graph.add_edge(START, analyze) graph.add_conditional_edges( analyze, lambda state: state[decision], { rag: handle_rag, chat: handle_chat, }, ) graph.add_edge(handle_rag, END) graph.add_edge(handle_chat, END) app graph.compile() result app.invoke({input_text: 我需要用 RAG 做知识库问答}) print(result)这段代码的核心是add_conditional_edges。它的作用是从analyze节点出来之后根据函数返回的decision决定下一个节点是handle_rag还是handle_chat。这就是 LangGraph 里“条件路由”的基本用法。运行输出大概是{input_text: 我需要用 RAG 做知识库问答, decision: rag, result: 走 RAG 流程检索知识库后回答}如果你把输入改成“你好”输出中的result会变成“走普通对话流程直接回答”。5.4 LangGraph Agent 工具调用示例LangGraph 提供了一个基于 ReAct 模式的预置 Agent 实现可以快速把工具接入模型。# 文件路径examples/04_agent.py from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent tool def multiply(a: int, b: int) - int: 返回两个整数的乘积。 return a * b tools [multiply] llm ChatOpenAI(modelgpt-4o-mini, temperature0) agent create_react_agent(llm, tools) response agent.invoke( {messages: [{role: user, content: 6乘以7等于多少}]} ) print(response[messages][-1].content)tool装饰器把一个普通函数变成模型可调用的工具。create_react_agent是 LangGraph 预置的 Agent 创建函数它会自动处理“模型决定调用工具 → 执行工具 → 把结果返回模型 → 模型生成回答”的循环。这里真正容易踩坑的地方是Agent 能不能选对工具很大程度上取决于工具的docstring写得是否清晰。模型是根据函数名、参数和 docstring 来决定是否调用该工具的所以不要写“函数说明”这种无信息量的话要写清楚“什么时候用、参数含义是什么”。6. 运行结果与效果验证如果你按顺序运行了上面的代码验证标准如下示例 5.1 输出一段 50 字以内的 RAG 解释说明 LangChain 基础链路正常。示例 5.2 输出的回答能引用docs/knowledge.txt里的内容说明 RAG 检索链路正常。示例 5.3 能根据输入关键词进入不同分支说明条件路由逻辑正常。示例 5.4 能算出乘法结果说明 Agent 工具调用正常。如果运行失败不要急着改代码先按下面顺序排查看 API Key 是否正确设置错误信息是否提示 401。看网络能否访问模型服务错误信息是否提示连接超时。看模型名是否存在错误信息是否提示 model not found。看包版本是否兼容错误信息是否提示某个函数不存在。其中包版本问题最常见。LangChain 和 LangGraph 的 API 更新频率很高网上代码不一定适用于你安装的版本。遇到 ModuleNotFoundError 或 AttributeError 时优先去官方文档查对应版本的写法而不是盲目降级。7. 常见问题与排查思路问题现象可能原因排查方式解决方案调用模型报 401API Key 缺失或无效检查环境变量是否设置重新配置正确的 API Key调用模型报连接超时网络无法访问模型服务ping 或 curl 模型接口地址检查网络代理、白名单配置提示 model not found模型名拼写错误或服务商不支持对照服务商文档核对模型名修改模型名为有效值安装多个 langchain 包后版本冲突依赖范围不一致查看 pip freeze 和报错堆栈在虚拟环境中统一依赖版本RAG 回答不准确文档拆分太大或太小打印检索到的 chunk 内容检查相关性调整 chunk_size 和 chunk_overlapRAG 检索不到内容文档未正确加载或嵌入维度不一致打印检索结果数量检查加载器路径和 Embedding 模型Agent 不调用工具工具 docstring 不清晰或模型无法理解参数类型打印 Agent 的中间推理日志重写工具描述细化参数说明LangGraph 图编译失败节点或边配置错误查看编译报错信息中的节点名检查 add_node 和 add_conditional_edges 参数长文本超过模型上下文窗口Prompt 中拼接内容过多统计输入 token 数量减少检索返回数量或拆分任务处理排查问题时建议开启 LangChain 的调试日志它会把每一步执行的输入输出打印出来。这样能快速定位是检索环节、模型环节还是解析环节出了问题。from langchain.globals import set_debug set_debug(True)8. 企业级落地最佳实践与工程建议8.1 提示词与模型的版本管理在本地写几个 Prompt 没问题但企业项目里提示词会像代码一样持续迭代。建议把 Prompt 模板放到独立目录或配置中心用版本号管理。模型名也不要散落在代码各处统一配置在环境变量或配置文件中。一个简单的目录结构参考config/ prompts/ rag_system_v1.txt chat_system_v1.txt models.yaml# 文件路径config/models.yaml llm: chat_model: gpt-4o-mini embedding_model: text-embedding-3-small temperature: 0这样改 Prompt 和换模型都不需要改业务代码。8.2 检索质量是 RAG 的生命线RAG 的效果上限由检索决定。模型再强检索结果不对回答也不会对。以下几点值得重视文档解析PDF 转文字时表格、图片、页眉页脚都可能引入噪声。需要验证解析结果不要盲目相信解析库。分块策略普通文本可以按字符数分块代码或表格可能需要按结构分块。可以从 200 到 800 之间测试找到适合你自己文档的长度。召回评估建立一个小规模测试集比如 50 个“问题-标准答案”对每次调整检索参数后跑一遍用召回率判断效果而不是靠感官判断。检索后重排如果前期检索结果不够精准可以引入 Rerank 模型对召回结果二次排序但会增加系统复杂度和延迟需权衡。8.3 Agent 的边界与安全控制企业级 Agent 最容易出问题的不是“模型不够聪明”而是“权限太大”。给 Agent 挂工具时必须遵守最小权限原则。比如一个只能查天气的 Agent永远不需要数据库的删除权限。一个能调用内部 API 的 Agent必须在工具层做参数校验而不是信任模型每次都能传对参数。工具调用日志要完整记录方便事后再现和审计。如果你在生产环境使用 Agent建议在 Agent 外层加“允许执行的工具白名单”和“敏感操作二次确认”机制。模型输出不直接执行而是先进入校验层通过后才真正调用系统能力。8.4 可观测性与成本控制在本地调试时你看不到每一步消耗了多少 token。企业项目中成本和延迟必须纳入监控。需要记录的数据至少包括每次请求的输入 token 数和输出 token 数。每次检索耗时、模型响应耗时。每次 Agent 调用了哪些工具参数是什么。失败请求的错误类型和占比。可以在 LangChain 的调用链路中插入日志回调或者使用 LangSmith 这类可观测性平台。成本控制方面可以按用户维度做配额限制避免异常流量打爆预算。缓存也是常用手段重复问题直接走缓存答案能大幅降低 API 费用。8.5 从小步验证到灰度发布很多项目死在“第一版就想做全”。一个合理的实施路径是先用最简单的 Chat 接口跑通业务闭环。加入 RAG解决是否要用私域知识。评估哪些操作真正需要 Agent 调工具不要为了 Agent 而 Agent。等流程稳定后再用 LangGraph 把多分支逻辑可视化梳理。上线时用灰度策略先放小流量监控错误率和用户反馈再逐步放量。每一步都要有明确的验证指标。不要一次性把 LangChain、LangGraph、Agent、RAG 全部塞进一个项目否则出问题时根本不知道是哪一环造成的。9. 总结与后续学习方向到这里你应该能理解 LangChain、LangGraph、Agent、RAG 的分工也知道了一条从零跑通到工程化落地的路径。真正值得记住的结论是LangChain 是编排底座RAG 解决知识接入Agent 扩展工具能力LangGraph 负责复杂流程的可控执行。学习时按这个递进关系走比同时打开五个教程更有效。下一步你可以做三件事第一把文章里的四个示例代码跑通不用背代码但要理解每一步改了什么会产生什么影响。第二换一批自己的文档做一个围绕你业务资料的知识库问答体验从通用 Demo 到领域应用的差异。第三阅读 LangGraph 官方文档中关于状态、节点、条件边、子图和并行分支的部分这是从“会写示例”走向“能设计复杂工作流”的必经之路。等技术栈熟悉后建议深入源码看一两个核心模块。比如 LangChain 的 Chain 是如何被执行的LangGraph 的 StateGraph 是如何管理状态的。源码里藏着文档里没写清楚的边界条件。建议收藏这篇文章作为你从入门到工程实践的索引。更重要的是把示例代码跑起来遇到报错就按文章里的排查表对照处理。技术学习没有捷径但有一条更清晰的路总比在收藏夹里吃灰要快得多。