最近经常被问到一个问题LangChain 到底还值不值得学LangGraph 是来替代 LangChain 的吗企业做知识库问答、Agent 自动化到底应该先学什么这些问题的答案其实指向同一条主线LangChain 负责组件生态LangGraph 负责流程编排Agent 是应用形态RAG 是内容增强手段。把它们串起来基本就是当前企业级 LLM 应用开发的核心能力栈。这篇文章不打算做概念堆砌而是按“从入门到可上线”的顺序把这条技术栈的学习主线、代码骨架、工程化方法和常见坑位拆开讲清楚。先给结论LangChain 没有过时但学习重心已经变了。早期大家学 Chain、LCEL、快速封装模型调用现在官方和社区更强调 LangGraph 的工作流编排能力RAG 也从基础的“向量检索 拼接 Prompt”升级到了 Agentic RAGAgent 则从简单的工具调用演变成多节点、可持久化、可监控的图结构应用。这篇文章适合三类读者一是刚入门、想规划 LangChain 学习路线的开发者二是写过简单 RAG Demo、但不知道如何工程化上线的后端工程师三是在评估 LangGraph 能不能接入现有业务系统的技术负责人。文中代码均为可运行的示意具体版本、模型名、目录路径需要按你自己的环境替换。文章会先给一套“核心能力速览”再依次拆解 LangChain 基础、RAG 实战、Agent 设计、LangGraph 编排和企业级工程化最后给出一条可以按周执行的学习路线。1. LangChain LangGraph Agent RAG 核心能力速览能力项说明技术栈组成LangChain 组件层 LangGraph 工作流编排 Agent 应用形态 RAG 检索增强核心目标让开发者快速构建基于大模型的问答、知识库、自动化决策类应用适合读者Python 开发者、后端工程师、AI 应用落地团队前置知识Python 基础、HTTP/API 调用基础了解 Prompt 基础更佳运行环境入门阶段有模型 API Key 即可本地部署需要 GPU显存按模型规模评估模型支持兼容 OpenAI 风格 API、国产大模型、Ollama/vLLM 等本地推理服务交付形态Web API、Streamlit 演示系统、业务系统内嵌、定时任务、消息队列消费端企业关注点可观测、可评测、可回滚、权限可控、数据不泄露常见误区只抄示例不追踪版本一上来叠概念忽略评测和回归不设兜底策略这条技术栈的定位很明确它不是某个“开箱即用的一键大模型工具”而是一套面向大模型应用开发的编程框架和设计范式。你可以用它写 20 行的内部小工具也可以构建支持多轮对话、动态规划、多工具协作的中大型业务系统。不同的复杂度对应不同的学习深度这也是为什么后面要做分阶段规划。2. 这套技术栈在解决什么问题在没有 LangChain 这类框架之前写一个调用大模型的应用并不难难的是把“模型调用”变成“可靠业务逻辑”。比如多个文档要加载解析切成合适的块回答要引用出处用户提问要先判断要不要查库再判断要不要调用工具一次任务可能拆成多个步骤某一步失败要重试整个流程要能被监控出了问题要能回溯。LangChain 解决的是连接问题。它对模型调用、Prompt 模板、文档加载、文本切分、向量库、外部工具做了统一的抽象避免每个项目都从零开始造轮子。LangGraph 解决的是流程问题。它把一次 AI 任务建模成一张有状态的状态图节点可以增删边可以按条件跳转状态可以被持久化任务可以在中途被打断并恢复。Agent 解决的是决策问题。它让模型不再是“答一句话”而是根据目标决定“先做什么、再做什么、何时结束”。RAG 解决的是知识来源问题。它把企业私有文档变成模型在生成时可以参考的上下文缓解幻觉也让回答可以有出处。从适用边界看这套技术栈最适合“知识密集型”和“流程密集型”场景比如企业内部知识库问答、客服工单分类与回复草稿、结构化工单抽取、数据报表的自然语言查询、自动化测试用例生成等。不适合的场景包括完全依赖模型输出做最终决策的高风险环节没有人工复核的自动化操作以及对延迟极其敏感的实时系统——在这些场景中需要先做好权限、缓存、兜底和评测机制再上线。需要特别强调合规边界RAG 一旦接入企业真实文档就要确认文档来源合法、是否包含敏感信息、是否可以用于指定业务Agent 如果涉及自动调用外部系统必须设计操作审计、权限隔离和干预期发布到面向公众的应用前要对生成内容做一轮人工抽检。技术能力只是“能做”合法合规之后才是“可上线”。3. 入门阶段LangChain 基础组件怎么学3.1 环境准备入门阶段不一定要 GPU优先准备一个可以稳定调用的大模型 API 即可。无论是云厂商的模型服务还是本地 Ollama 启动的模型只要能通过 OpenAI 兼容接口调用就行。Python 版本建议使用当前的稳定版本比如 3.10 及以上包管理建议用 venv 或 conda 隔离环境避免依赖冲突。# 创建虚拟环境实际命令需要根据系统路径调整 python -m venv .venv source .venv/bin/activate然后安装 LangChain 生态的核心依赖。需要说明的是LangChain 包拆分比较频繁安装前建议先查看官方文档确认当前推荐包名和版本。# 示意安装具体包名和版本以官方文档为准 pip install langchain langchain-openai langchain-community langgraph3.2 第一次调用模型初学阶段最重要的不是背 API而是建立一条“模型调用 - 结构化输出 - 异常处理”的最小闭环。下面这段代码使用 OpenAI 兼容接口调用模型如果你使用的是其他服务商把base_url和api_key换成自己的即可from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0, # 如果使用本地推理服务这里改成对应的 base_url # base_urlhttp://127.0.0.1:8000/v1, # api_keylocal-model-key, ) resp llm.invoke(用一句话解释什么是 RAG) print(resp.content)这段代码跑通之后下一步不是继续加功能而是反推框架里的几个关键概念model对应模型层temperature对应生成参数response对应标准化输出结构。LangChain 的核心价值之一就是把“不同模型的差异”隐藏在统一接口后面业务代码不需要跟着模型供应商变化频繁改动。3.3 入门阶段最容易踩的坑版本混装网上代码大多来自不同时期的 LangChain 版本直接复制会导致import报错。解决办法是固定版本并在环境里查看pip show langchain确认版本号。跳过 Prompt 工程直接做 RAG检索再准Prompt 写得含糊生成质量也会受影响。不设超时和重试模型服务偶尔不稳定生产环境必须配置超时、重试和兜底回答。4. RAG 实战从文档加载到知识库问答RAG 是目前 LangChain 技术栈里最容易“跑通 Demo、最难做好效果”的方向。先理解全链路再调参。4.1 RAG 的标准链路一条完整的 RAG 链路至少包含四步文档加载从 PDF、Word、Markdown、网页、数据库等来源取得原始文本。文本切分把长文本切成适合向量化的块并保留上下文重叠。向量化与存储用 Embedding 模型把文本块变成向量写入向量库或支持向量检索的数据库。检索与生成用户提问后用问题向量召回最相关的文档块拼进 Prompt 交给生成模型输出答案。下面的代码演示了从本地文本文件构建向量库的示意流程from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma # 1. 加载文档 loader TextLoader(service_docs.md, encodingutf-8) docs loader.load() # 2. 文本切分参数需要根据文档类型调整 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks splitter.split_documents(docs) # 3. 向量化并写入向量库 embedding OpenAIEmbeddings() vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db ) # 4. 构建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3})这个流程跑通之后你会遇到第一个真实问题为什么检索结果看起来相关但回答质量不稳定原因通常在切分策略和召回数量上。切分太小会丢上下文切分太大又会混入噪声召回数量太少可能漏信息太多又会稀释 Prompt 中的关键内容。这些问题没有统一的“最优参数”要根据你的文档类型和问题分布来做回归测试。4.2 生成阶段把检索结果接入 Prompt构建一个“检索 - 生成”的问答链可以用 LangChain 提供的create_retrieval_chain也可以手动拼装 Prompt。手动拼装的好处是逻辑透明方便插入你自己的业务逻辑。from langchain.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 请基于以下知识库内容回答问题。如果知识库中没有可靠依据请直接说明不知道不要编造。\n\n知识库内容\n{context}), (human, 问题{question}) ]) def rag_answer(question: str) - str: docs retriever.invoke(question) context \n\n.join([doc.page_content for doc in docs]) chain prompt | llm resp chain.invoke({context: context, question: question}) return resp.content print(rag_answer(我们公司的退款政策是什么))这里有一个很关键的工程判断RAG 的输出质量不仅取决于模型更取决于召回链路。当回答效果不好时不要第一时间换大模型先检查召回的内容是否准确、是否完整、是否存在互相矛盾的信息。等检索质量稳定后再去调整 Prompt 或换模型。4.3 企业级 RAG 需要补什么入门版 RAG 能回答“单文档、单库”的问题但企业级落地通常需要补充多路召回相同问题同时召回向量相似结果和关键词匹配结果再做合并排序。引用溯源返回答案时把来源文档 ID、页码、切块 ID 一起返回方便用户点开原文核对。权限过滤不同角色只能检索自己有权限访问的文档集合。数据更新机制文档变更后增量更新向量库而不是每次全量重建。评测与回归准备一批“标准问答对”每次调整 Prompt、切分参数、召回策略后用同一套题目验证效果是否回退。5. Agent 实战从思维链到工具调用RAG 解决的是“不知道”的问题Agent 解决的是“不会做”的问题。所谓 Agent简单说就是让模型根据用户目标自己规划行动步骤、调用外部工具、观察返回结果、再决定下一步动作的智能体应用。5.1 Agent 的最小设计开发一个 Agent 前先想清楚三件事模型流程如何驱动、Agent 可以调用哪些工具、如何避免循环和失控。一个常见的 Agent 形态是 ReAct 模式模型先分析当前状态决定调用什么工具拿到工具结果后再继续推理直到得出最终答案。下面是一个基于 LangGraph 思路的 Agent 骨架示意from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): messages: list current_tool: str def agent_node(state: State): # 这一步让模型决定下一步动作返回要调用的工具或最终答案 return {messages: state[messages]} def tool_node(state: State): # 这里根据 current_tool 执行真实函数调用 return {messages: state[messages]} graph StateGraph(State) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(agent, tools) graph.add_edge(tools, agent) graph.set_entry_point(agent) app graph.compile()这个骨架虽然简单但已经体现了 Agent 的三个关键特征有状态所有历史消息在 State 中传递、有循环agent 和 tools 之间可以反复跳转、有出口需要设计条件判断在得到最终答案时结束循环。实际开发时会在agent_node中判断是返回“调用工具”的指令还是“最终答案”然后通过条件边决定走向tool_node还是END。5.2 Agent 的工程化要点工具数量要克制不是工具越多越好工具太多会增大模型选错工具的概率。每个工具都要有清晰的描述、参数定义和调用边界。要设最大迭代次数Agent 可能陷入反复调用工具的循环必须设置最大步数超过就强制结束并返回正在处理中的提示。要做操作审计涉及查询订单、修改配置、推送消息等操作时记录每次工具调用方便追踪。要容忍失败工具可能超时、报错、结果为空Agent 设计要包含“工具失败后的备选行动”而不是直接崩溃。要做好权限控制让模型自动调用有权限风险的工具前先评估是否需要人工确认环节。这里要特别提醒Agent 的“自动化”会放大模型误判的后果。如果 Agent 自动发送消息、自动下单、自动改配置一定要设计人工审批和灰度开关避免一次误调用造成连锁问题。6. LangGraph 实战把流程变成可维护的工作流6.1 LangGraph 和 LangChain 到底是什么关系这两个概念经常被混在一起讨论。简单理解LangChain 是组件库LangGraph 是编排引擎。LangChain 提供模型封装、文档加载、向量库、Prompt 模板等“积木”LangGraph 负责决定这些积木按照什么顺序、什么条件、什么状态去组合执行。早期 LangChain 官方主推 Chain 和 LCEL适合线性流程但企业应用普遍有分支、循环、多角色协作、人工介入等复杂需求LangGraph 显然更适合承载这些场景。这也是为什么很多人说“LangGraph 会替代 LCEL”。更准确的说法是LangGraph 替代了 LangChain 中“流程编排”那一层的位置而组件层依然是 LangChain 生态的强项。6.2 LangGraph 的核心概念LangGraph 的核心抽象是状态图StateGraph围绕它有五个关键概念概念作用学习重点State定义节点间传递的数据结构所有节点只能修改 State 中声明的字段Node图中的执行单元一个函数或一个可调用对象接收 State 返回新 StateEdge节点之间的连接决定执行顺序普通边固定跳转Conditional Edge条件边根据 State 内容动态决定下一个节点Checkpointer状态持久化支持任务中断、恢复、回放是企业级核心能力从代码层面看LangGraph 的“图”并不是什么新概念但它把 AI 应用中的复杂控制流变成了可视化、可测试、可回放的对象这让团队协作和线上排障都容易很多。比如一个客服 Agent如果流程写成十几个 if-else没人敢改如果用状态图表达每个节点独立测试条件边单独调试整体风险会小很多。6.3 条件路由示例判断该走 RAG 还是直接生成下面用条件边实现一个常见需求根据用户问题是否涉及知识库决定走 RAG 节点还是普通生成节点。from typing import TypedDict from langgraph.graph import StateGraph, END class QueryState(TypedDict): question: str need_retrieval: bool context: str def judge_node(state: QueryState): # 这里用模型或规则判断是否要检索 need 退款政策 in state[question] or 知识库 in state[question] return {need_retrieval: need} def rag_node(state: QueryState): return {context: 从向量库检索到的内容...} def direct_node(state: QueryState): return {context: } def route_by_need(state: QueryState): return rag if state[need_retrieval] else direct graph StateGraph(QueryState) graph.add_node(judge, judge_node) graph.add_node(rag, rag_node) graph.add_node(direct, direct_node) graph.add_conditional_edges( judge, route_by_need, {rag: rag, direct: direct} ) graph.add_edge(rag, END) graph.add_edge(direct, END) graph.set_entry_point(judge) app graph.compile()这个例子展示的是 LangGraph 的典型用法每个节点只做一件事节点之间的跳转逻辑通过条件边表达整体流程清晰也方便在每两个节点之间插入日志、埋点、人工审核。7. 从入门到企业级工程化与上线清单跑通 Demo 之后离上线还有一段距离。企业级改造通常围绕接口化、部署、评测、监控四个方向展开。7.1 把链路封装成 API后端项目最常用的是 FastAPI 把 RAG 或 Agent 流程包装成 HTTP 接口from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class QueryRequest(BaseModel): question: str user_id: str app.post(/api/ask) def ask(req: QueryRequest): # 这里替换为真实 RAG 或 Agent 的调用逻辑 answer rag_answer(req.question) return {answer: answer, request_id: req.user_id}接口层需要额外考虑鉴权方式、请求频率限制、超时时间、日志结构、错误返回格式。不要把模型链路直接暴露到公网建议在服务前面加 API 网关统一处理认证和限流。7.2 部署形态的选择单体服务适合工具函数、接口数量少的内部系统启动快部署成本低。异步任务队列适合耗时较长的 Agent 任务如批量文档处理、多步分析把请求放入队列后台 Worker 消费。容器化部署用 Docker 打包应用利用环境变量管理 API Key 和模型地址方便迁移和扩容。部署时需要注意不要把 API Key 写死在代码里不同环境的模型名、向量库地址、切分参数、Prompt 模板要有独立的配置项发布前要备份可用的上一个配置方便回滚。7.3 质量评测上线前的底线很多项目死在“Demo 效果不错、上线后效果崩了”原因是没有评测集。最少准备 30 到 50 组有标准答案的问题覆盖不同类型的提问方式比如直接提问、模糊提问、跨文档提问、无答案提问。每次修改 Prompt、切分参数、召回策略后用同一套评测集跑一遍记录答对数量、未召回数量、错误引用数量用数据判断改动是否正向。评测指标不需要一开始就上完整体系先关注三个正确率答案是否准确、召回率关键信息是否出现在答案中、幻觉率是否出现知识库中不存在的内容。等基础评测稳定后再逐步引入更细粒度的指标和自动化回归。7.4 监控与安全线上服务必须能看到“链路里发生了什么”。建议至少在三个位置打日志模型调用前后、检索前后、Agent 的每一步工具调用。日志内容包括请求 ID、耗时、token 消耗、使用的文档 ID、工具名、入参出参以及异常堆栈。安全方面需要注意用户输入可能包含恶意指令需要对输入长度做限制并过滤敏感内容RAG 涉及企业内部数据时要做好权限隔离Agent 调用外部系统时必须设置操作白名单并对敏感操作做二次确认。8. 学习路线图一周时间怎么分配结合当前的版本趋势给出一条偏实践的学习路线按周为单位规划时间学习内容产出物第 1 天LangChain 基础组件能用代码调用模型理解 Chat、Prompt、Output Parser第 2 天LangChain 文档处理与切分能加载一个文档并完成向量化第 3 天RAG 完整链路跑通一个带引用来源的问答 Demo第 4 天Agent 理论基础与工具封装实现一个能调用 2 个工具的简单 Agent第 5 天LangGraph 状态图与条件边用 LangGraph 重构 Agent支持分支和最大步数第 6 天API 封装与本地化部署把链路封装成 FastAPI 接口做数据评测第 7 天综合实战与复盘选一个真实业务场景完成从文档到接口的全流程这个路线不追求把所有概念都覆盖核心原则是先跑通链路再优化质量再研究高级特性。如果时间紧张优先级是 RAG 大于 AgentLangGraph 大于其他高级技巧因为 RAG 是大多数企业内部知识库场景的刚需LangGraph 是让复杂 Agent 可控的基础。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装依赖时 import 报错包版本不兼容查看pip list中的版本对比报错信息固定版本号按官方文档推荐的版本组合安装模型调用超时网络不稳定或模型服务响应慢查看超时堆栈测试网络连接增加超时时间配置重试机制切换更快模型RAG 回答与文档无关切分不合理或向量模型效果弱打印检索到的上下文人工核对是否相关调整 chunk_size/chunk_overlap更换 Embedding 模型Agent 反复调用工具不结束缺少最大迭代限制或工具描述不清晰查看日志确认每次工具调用设置最大步数优化工具描述为“何时用、怎么用”LangGraph 编译报错图和状态定义不一致检查节点返回字段是否在 State 中声明统一 State 字段确保节点返回 Key 对齐上线后效果不如 Demo评测样本不足或 Prompt 过拟合用多组真实问题回归测试建立评测集分阶段调参先稳定检索再优化生成接口返回慢检索链路耗时或模型推理慢拆解各部分耗时加缓存、换轻量模型、控制上下文长度数据权限泄露风险向量库未做权限过滤检查检索代码是否按用户范围过滤在检索前增加文档集合过滤条件排查问题的通用思路是“分段隔离”先确认请求是否到达接口再确认模型是否被调用再确认检索结果是否准确再确认生成结果是否被 Prompt 影响。逐段打日志问题基本能定位到具体环节。另外要特别提醒网上关于 LangChain 的代码很多来自不同版本遇到报错时先看版本号再查官方文档对应版本的写法。不要一报错就怀疑框架能力大多数情况下是参数名或包引入路径已经变化。10. 总结与下一步这套技术栈最值得投入的不是背诵 API而是理解“组件、状态、流程、工具、评测”这几个工程维度。LangChain 帮你把模型接入和文档处理变简单LangGraph 帮你把复杂流程变可控Agent 帮你把应用从问答升级成交互式决策RAG 帮你把私有知识安全地带进生成链路。建议最开始先完成三件事用 LangChain 调用一个真实模型用 RAG 跑通一个带文档来源的问答接口用 LangGraph 把同一个流程改写成状态图。这三步做完你就已经把最核心的框架思路掌握了。接下来的扩展方向可以是把 RAG 升级成多路召回并加权限过滤把 Agent 接入更多企业工具并加人工审核把应用容器化并接入监控系统。方向不唯一但主线始终是工程化落地。
LangChain与LangGraph实战：Agent+RAG企业级应用开发主线
最近经常被问到一个问题LangChain 到底还值不值得学LangGraph 是来替代 LangChain 的吗企业做知识库问答、Agent 自动化到底应该先学什么这些问题的答案其实指向同一条主线LangChain 负责组件生态LangGraph 负责流程编排Agent 是应用形态RAG 是内容增强手段。把它们串起来基本就是当前企业级 LLM 应用开发的核心能力栈。这篇文章不打算做概念堆砌而是按“从入门到可上线”的顺序把这条技术栈的学习主线、代码骨架、工程化方法和常见坑位拆开讲清楚。先给结论LangChain 没有过时但学习重心已经变了。早期大家学 Chain、LCEL、快速封装模型调用现在官方和社区更强调 LangGraph 的工作流编排能力RAG 也从基础的“向量检索 拼接 Prompt”升级到了 Agentic RAGAgent 则从简单的工具调用演变成多节点、可持久化、可监控的图结构应用。这篇文章适合三类读者一是刚入门、想规划 LangChain 学习路线的开发者二是写过简单 RAG Demo、但不知道如何工程化上线的后端工程师三是在评估 LangGraph 能不能接入现有业务系统的技术负责人。文中代码均为可运行的示意具体版本、模型名、目录路径需要按你自己的环境替换。文章会先给一套“核心能力速览”再依次拆解 LangChain 基础、RAG 实战、Agent 设计、LangGraph 编排和企业级工程化最后给出一条可以按周执行的学习路线。1. LangChain LangGraph Agent RAG 核心能力速览能力项说明技术栈组成LangChain 组件层 LangGraph 工作流编排 Agent 应用形态 RAG 检索增强核心目标让开发者快速构建基于大模型的问答、知识库、自动化决策类应用适合读者Python 开发者、后端工程师、AI 应用落地团队前置知识Python 基础、HTTP/API 调用基础了解 Prompt 基础更佳运行环境入门阶段有模型 API Key 即可本地部署需要 GPU显存按模型规模评估模型支持兼容 OpenAI 风格 API、国产大模型、Ollama/vLLM 等本地推理服务交付形态Web API、Streamlit 演示系统、业务系统内嵌、定时任务、消息队列消费端企业关注点可观测、可评测、可回滚、权限可控、数据不泄露常见误区只抄示例不追踪版本一上来叠概念忽略评测和回归不设兜底策略这条技术栈的定位很明确它不是某个“开箱即用的一键大模型工具”而是一套面向大模型应用开发的编程框架和设计范式。你可以用它写 20 行的内部小工具也可以构建支持多轮对话、动态规划、多工具协作的中大型业务系统。不同的复杂度对应不同的学习深度这也是为什么后面要做分阶段规划。2. 这套技术栈在解决什么问题在没有 LangChain 这类框架之前写一个调用大模型的应用并不难难的是把“模型调用”变成“可靠业务逻辑”。比如多个文档要加载解析切成合适的块回答要引用出处用户提问要先判断要不要查库再判断要不要调用工具一次任务可能拆成多个步骤某一步失败要重试整个流程要能被监控出了问题要能回溯。LangChain 解决的是连接问题。它对模型调用、Prompt 模板、文档加载、文本切分、向量库、外部工具做了统一的抽象避免每个项目都从零开始造轮子。LangGraph 解决的是流程问题。它把一次 AI 任务建模成一张有状态的状态图节点可以增删边可以按条件跳转状态可以被持久化任务可以在中途被打断并恢复。Agent 解决的是决策问题。它让模型不再是“答一句话”而是根据目标决定“先做什么、再做什么、何时结束”。RAG 解决的是知识来源问题。它把企业私有文档变成模型在生成时可以参考的上下文缓解幻觉也让回答可以有出处。从适用边界看这套技术栈最适合“知识密集型”和“流程密集型”场景比如企业内部知识库问答、客服工单分类与回复草稿、结构化工单抽取、数据报表的自然语言查询、自动化测试用例生成等。不适合的场景包括完全依赖模型输出做最终决策的高风险环节没有人工复核的自动化操作以及对延迟极其敏感的实时系统——在这些场景中需要先做好权限、缓存、兜底和评测机制再上线。需要特别强调合规边界RAG 一旦接入企业真实文档就要确认文档来源合法、是否包含敏感信息、是否可以用于指定业务Agent 如果涉及自动调用外部系统必须设计操作审计、权限隔离和干预期发布到面向公众的应用前要对生成内容做一轮人工抽检。技术能力只是“能做”合法合规之后才是“可上线”。3. 入门阶段LangChain 基础组件怎么学3.1 环境准备入门阶段不一定要 GPU优先准备一个可以稳定调用的大模型 API 即可。无论是云厂商的模型服务还是本地 Ollama 启动的模型只要能通过 OpenAI 兼容接口调用就行。Python 版本建议使用当前的稳定版本比如 3.10 及以上包管理建议用 venv 或 conda 隔离环境避免依赖冲突。# 创建虚拟环境实际命令需要根据系统路径调整 python -m venv .venv source .venv/bin/activate然后安装 LangChain 生态的核心依赖。需要说明的是LangChain 包拆分比较频繁安装前建议先查看官方文档确认当前推荐包名和版本。# 示意安装具体包名和版本以官方文档为准 pip install langchain langchain-openai langchain-community langgraph3.2 第一次调用模型初学阶段最重要的不是背 API而是建立一条“模型调用 - 结构化输出 - 异常处理”的最小闭环。下面这段代码使用 OpenAI 兼容接口调用模型如果你使用的是其他服务商把base_url和api_key换成自己的即可from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0, # 如果使用本地推理服务这里改成对应的 base_url # base_urlhttp://127.0.0.1:8000/v1, # api_keylocal-model-key, ) resp llm.invoke(用一句话解释什么是 RAG) print(resp.content)这段代码跑通之后下一步不是继续加功能而是反推框架里的几个关键概念model对应模型层temperature对应生成参数response对应标准化输出结构。LangChain 的核心价值之一就是把“不同模型的差异”隐藏在统一接口后面业务代码不需要跟着模型供应商变化频繁改动。3.3 入门阶段最容易踩的坑版本混装网上代码大多来自不同时期的 LangChain 版本直接复制会导致import报错。解决办法是固定版本并在环境里查看pip show langchain确认版本号。跳过 Prompt 工程直接做 RAG检索再准Prompt 写得含糊生成质量也会受影响。不设超时和重试模型服务偶尔不稳定生产环境必须配置超时、重试和兜底回答。4. RAG 实战从文档加载到知识库问答RAG 是目前 LangChain 技术栈里最容易“跑通 Demo、最难做好效果”的方向。先理解全链路再调参。4.1 RAG 的标准链路一条完整的 RAG 链路至少包含四步文档加载从 PDF、Word、Markdown、网页、数据库等来源取得原始文本。文本切分把长文本切成适合向量化的块并保留上下文重叠。向量化与存储用 Embedding 模型把文本块变成向量写入向量库或支持向量检索的数据库。检索与生成用户提问后用问题向量召回最相关的文档块拼进 Prompt 交给生成模型输出答案。下面的代码演示了从本地文本文件构建向量库的示意流程from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma # 1. 加载文档 loader TextLoader(service_docs.md, encodingutf-8) docs loader.load() # 2. 文本切分参数需要根据文档类型调整 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks splitter.split_documents(docs) # 3. 向量化并写入向量库 embedding OpenAIEmbeddings() vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db ) # 4. 构建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3})这个流程跑通之后你会遇到第一个真实问题为什么检索结果看起来相关但回答质量不稳定原因通常在切分策略和召回数量上。切分太小会丢上下文切分太大又会混入噪声召回数量太少可能漏信息太多又会稀释 Prompt 中的关键内容。这些问题没有统一的“最优参数”要根据你的文档类型和问题分布来做回归测试。4.2 生成阶段把检索结果接入 Prompt构建一个“检索 - 生成”的问答链可以用 LangChain 提供的create_retrieval_chain也可以手动拼装 Prompt。手动拼装的好处是逻辑透明方便插入你自己的业务逻辑。from langchain.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 请基于以下知识库内容回答问题。如果知识库中没有可靠依据请直接说明不知道不要编造。\n\n知识库内容\n{context}), (human, 问题{question}) ]) def rag_answer(question: str) - str: docs retriever.invoke(question) context \n\n.join([doc.page_content for doc in docs]) chain prompt | llm resp chain.invoke({context: context, question: question}) return resp.content print(rag_answer(我们公司的退款政策是什么))这里有一个很关键的工程判断RAG 的输出质量不仅取决于模型更取决于召回链路。当回答效果不好时不要第一时间换大模型先检查召回的内容是否准确、是否完整、是否存在互相矛盾的信息。等检索质量稳定后再去调整 Prompt 或换模型。4.3 企业级 RAG 需要补什么入门版 RAG 能回答“单文档、单库”的问题但企业级落地通常需要补充多路召回相同问题同时召回向量相似结果和关键词匹配结果再做合并排序。引用溯源返回答案时把来源文档 ID、页码、切块 ID 一起返回方便用户点开原文核对。权限过滤不同角色只能检索自己有权限访问的文档集合。数据更新机制文档变更后增量更新向量库而不是每次全量重建。评测与回归准备一批“标准问答对”每次调整 Prompt、切分参数、召回策略后用同一套题目验证效果是否回退。5. Agent 实战从思维链到工具调用RAG 解决的是“不知道”的问题Agent 解决的是“不会做”的问题。所谓 Agent简单说就是让模型根据用户目标自己规划行动步骤、调用外部工具、观察返回结果、再决定下一步动作的智能体应用。5.1 Agent 的最小设计开发一个 Agent 前先想清楚三件事模型流程如何驱动、Agent 可以调用哪些工具、如何避免循环和失控。一个常见的 Agent 形态是 ReAct 模式模型先分析当前状态决定调用什么工具拿到工具结果后再继续推理直到得出最终答案。下面是一个基于 LangGraph 思路的 Agent 骨架示意from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): messages: list current_tool: str def agent_node(state: State): # 这一步让模型决定下一步动作返回要调用的工具或最终答案 return {messages: state[messages]} def tool_node(state: State): # 这里根据 current_tool 执行真实函数调用 return {messages: state[messages]} graph StateGraph(State) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(agent, tools) graph.add_edge(tools, agent) graph.set_entry_point(agent) app graph.compile()这个骨架虽然简单但已经体现了 Agent 的三个关键特征有状态所有历史消息在 State 中传递、有循环agent 和 tools 之间可以反复跳转、有出口需要设计条件判断在得到最终答案时结束循环。实际开发时会在agent_node中判断是返回“调用工具”的指令还是“最终答案”然后通过条件边决定走向tool_node还是END。5.2 Agent 的工程化要点工具数量要克制不是工具越多越好工具太多会增大模型选错工具的概率。每个工具都要有清晰的描述、参数定义和调用边界。要设最大迭代次数Agent 可能陷入反复调用工具的循环必须设置最大步数超过就强制结束并返回正在处理中的提示。要做操作审计涉及查询订单、修改配置、推送消息等操作时记录每次工具调用方便追踪。要容忍失败工具可能超时、报错、结果为空Agent 设计要包含“工具失败后的备选行动”而不是直接崩溃。要做好权限控制让模型自动调用有权限风险的工具前先评估是否需要人工确认环节。这里要特别提醒Agent 的“自动化”会放大模型误判的后果。如果 Agent 自动发送消息、自动下单、自动改配置一定要设计人工审批和灰度开关避免一次误调用造成连锁问题。6. LangGraph 实战把流程变成可维护的工作流6.1 LangGraph 和 LangChain 到底是什么关系这两个概念经常被混在一起讨论。简单理解LangChain 是组件库LangGraph 是编排引擎。LangChain 提供模型封装、文档加载、向量库、Prompt 模板等“积木”LangGraph 负责决定这些积木按照什么顺序、什么条件、什么状态去组合执行。早期 LangChain 官方主推 Chain 和 LCEL适合线性流程但企业应用普遍有分支、循环、多角色协作、人工介入等复杂需求LangGraph 显然更适合承载这些场景。这也是为什么很多人说“LangGraph 会替代 LCEL”。更准确的说法是LangGraph 替代了 LangChain 中“流程编排”那一层的位置而组件层依然是 LangChain 生态的强项。6.2 LangGraph 的核心概念LangGraph 的核心抽象是状态图StateGraph围绕它有五个关键概念概念作用学习重点State定义节点间传递的数据结构所有节点只能修改 State 中声明的字段Node图中的执行单元一个函数或一个可调用对象接收 State 返回新 StateEdge节点之间的连接决定执行顺序普通边固定跳转Conditional Edge条件边根据 State 内容动态决定下一个节点Checkpointer状态持久化支持任务中断、恢复、回放是企业级核心能力从代码层面看LangGraph 的“图”并不是什么新概念但它把 AI 应用中的复杂控制流变成了可视化、可测试、可回放的对象这让团队协作和线上排障都容易很多。比如一个客服 Agent如果流程写成十几个 if-else没人敢改如果用状态图表达每个节点独立测试条件边单独调试整体风险会小很多。6.3 条件路由示例判断该走 RAG 还是直接生成下面用条件边实现一个常见需求根据用户问题是否涉及知识库决定走 RAG 节点还是普通生成节点。from typing import TypedDict from langgraph.graph import StateGraph, END class QueryState(TypedDict): question: str need_retrieval: bool context: str def judge_node(state: QueryState): # 这里用模型或规则判断是否要检索 need 退款政策 in state[question] or 知识库 in state[question] return {need_retrieval: need} def rag_node(state: QueryState): return {context: 从向量库检索到的内容...} def direct_node(state: QueryState): return {context: } def route_by_need(state: QueryState): return rag if state[need_retrieval] else direct graph StateGraph(QueryState) graph.add_node(judge, judge_node) graph.add_node(rag, rag_node) graph.add_node(direct, direct_node) graph.add_conditional_edges( judge, route_by_need, {rag: rag, direct: direct} ) graph.add_edge(rag, END) graph.add_edge(direct, END) graph.set_entry_point(judge) app graph.compile()这个例子展示的是 LangGraph 的典型用法每个节点只做一件事节点之间的跳转逻辑通过条件边表达整体流程清晰也方便在每两个节点之间插入日志、埋点、人工审核。7. 从入门到企业级工程化与上线清单跑通 Demo 之后离上线还有一段距离。企业级改造通常围绕接口化、部署、评测、监控四个方向展开。7.1 把链路封装成 API后端项目最常用的是 FastAPI 把 RAG 或 Agent 流程包装成 HTTP 接口from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class QueryRequest(BaseModel): question: str user_id: str app.post(/api/ask) def ask(req: QueryRequest): # 这里替换为真实 RAG 或 Agent 的调用逻辑 answer rag_answer(req.question) return {answer: answer, request_id: req.user_id}接口层需要额外考虑鉴权方式、请求频率限制、超时时间、日志结构、错误返回格式。不要把模型链路直接暴露到公网建议在服务前面加 API 网关统一处理认证和限流。7.2 部署形态的选择单体服务适合工具函数、接口数量少的内部系统启动快部署成本低。异步任务队列适合耗时较长的 Agent 任务如批量文档处理、多步分析把请求放入队列后台 Worker 消费。容器化部署用 Docker 打包应用利用环境变量管理 API Key 和模型地址方便迁移和扩容。部署时需要注意不要把 API Key 写死在代码里不同环境的模型名、向量库地址、切分参数、Prompt 模板要有独立的配置项发布前要备份可用的上一个配置方便回滚。7.3 质量评测上线前的底线很多项目死在“Demo 效果不错、上线后效果崩了”原因是没有评测集。最少准备 30 到 50 组有标准答案的问题覆盖不同类型的提问方式比如直接提问、模糊提问、跨文档提问、无答案提问。每次修改 Prompt、切分参数、召回策略后用同一套评测集跑一遍记录答对数量、未召回数量、错误引用数量用数据判断改动是否正向。评测指标不需要一开始就上完整体系先关注三个正确率答案是否准确、召回率关键信息是否出现在答案中、幻觉率是否出现知识库中不存在的内容。等基础评测稳定后再逐步引入更细粒度的指标和自动化回归。7.4 监控与安全线上服务必须能看到“链路里发生了什么”。建议至少在三个位置打日志模型调用前后、检索前后、Agent 的每一步工具调用。日志内容包括请求 ID、耗时、token 消耗、使用的文档 ID、工具名、入参出参以及异常堆栈。安全方面需要注意用户输入可能包含恶意指令需要对输入长度做限制并过滤敏感内容RAG 涉及企业内部数据时要做好权限隔离Agent 调用外部系统时必须设置操作白名单并对敏感操作做二次确认。8. 学习路线图一周时间怎么分配结合当前的版本趋势给出一条偏实践的学习路线按周为单位规划时间学习内容产出物第 1 天LangChain 基础组件能用代码调用模型理解 Chat、Prompt、Output Parser第 2 天LangChain 文档处理与切分能加载一个文档并完成向量化第 3 天RAG 完整链路跑通一个带引用来源的问答 Demo第 4 天Agent 理论基础与工具封装实现一个能调用 2 个工具的简单 Agent第 5 天LangGraph 状态图与条件边用 LangGraph 重构 Agent支持分支和最大步数第 6 天API 封装与本地化部署把链路封装成 FastAPI 接口做数据评测第 7 天综合实战与复盘选一个真实业务场景完成从文档到接口的全流程这个路线不追求把所有概念都覆盖核心原则是先跑通链路再优化质量再研究高级特性。如果时间紧张优先级是 RAG 大于 AgentLangGraph 大于其他高级技巧因为 RAG 是大多数企业内部知识库场景的刚需LangGraph 是让复杂 Agent 可控的基础。9. 常见问题与排查方法问题现象可能原因排查方式解决方案安装依赖时 import 报错包版本不兼容查看pip list中的版本对比报错信息固定版本号按官方文档推荐的版本组合安装模型调用超时网络不稳定或模型服务响应慢查看超时堆栈测试网络连接增加超时时间配置重试机制切换更快模型RAG 回答与文档无关切分不合理或向量模型效果弱打印检索到的上下文人工核对是否相关调整 chunk_size/chunk_overlap更换 Embedding 模型Agent 反复调用工具不结束缺少最大迭代限制或工具描述不清晰查看日志确认每次工具调用设置最大步数优化工具描述为“何时用、怎么用”LangGraph 编译报错图和状态定义不一致检查节点返回字段是否在 State 中声明统一 State 字段确保节点返回 Key 对齐上线后效果不如 Demo评测样本不足或 Prompt 过拟合用多组真实问题回归测试建立评测集分阶段调参先稳定检索再优化生成接口返回慢检索链路耗时或模型推理慢拆解各部分耗时加缓存、换轻量模型、控制上下文长度数据权限泄露风险向量库未做权限过滤检查检索代码是否按用户范围过滤在检索前增加文档集合过滤条件排查问题的通用思路是“分段隔离”先确认请求是否到达接口再确认模型是否被调用再确认检索结果是否准确再确认生成结果是否被 Prompt 影响。逐段打日志问题基本能定位到具体环节。另外要特别提醒网上关于 LangChain 的代码很多来自不同版本遇到报错时先看版本号再查官方文档对应版本的写法。不要一报错就怀疑框架能力大多数情况下是参数名或包引入路径已经变化。10. 总结与下一步这套技术栈最值得投入的不是背诵 API而是理解“组件、状态、流程、工具、评测”这几个工程维度。LangChain 帮你把模型接入和文档处理变简单LangGraph 帮你把复杂流程变可控Agent 帮你把应用从问答升级成交互式决策RAG 帮你把私有知识安全地带进生成链路。建议最开始先完成三件事用 LangChain 调用一个真实模型用 RAG 跑通一个带文档来源的问答接口用 LangGraph 把同一个流程改写成状态图。这三步做完你就已经把最核心的框架思路掌握了。接下来的扩展方向可以是把 RAG 升级成多路召回并加权限过滤把 Agent 接入更多企业工具并加人工审核把应用容器化并接入监控系统。方向不唯一但主线始终是工程化落地。