AI Agent开发实战：从RAG到LangGraph的完整学习路线

AI Agent开发看起来像是一个既要懂模型、又要懂工程、还得能部署的高门槛方向。实际跑过一遍之后，我的看法是：它更像是一条把 LangGraph、RAG、私有化部署、调优、对齐这条链路走通，再把每个环节做到可验证的学习路线。尤其是双非背景的开发者，与其纠结学历和简历标题，不如先把一条真实项目链路完整跑出来。这篇指南不打算按“7天从小白到大神”的速成逻辑写，而是按普通机器、开源技术栈、可落地顺序拆解：先懂概念，再跑RAG，然后接入LangGraph，最后私有化部署和调优。7天其实足够把第一个可运行Agent做完，但你要清楚每个阶段在解决什么问题。

1. 先把AI Agent学习目标拆成四个能验证的阶段

1.1 第一阶段：先搞清楚Agent到底是什么，不急着写代码

很多人一上来就找Agent框架，下载模型，然后跑一个聊天窗口，最后发现跑出来的东西和普通对话机器人没什么区别。问题出在概念没有对齐。

Agent 不是一个聊天框，它是一个能根据用户任务，自主决定调用哪些工具、解析工具返回结果、并根据中间结果继续执行下一步的系统。它和普通RAG问答的差别在于：RAG是“检索一次，生成一次”，Agent则有决策循环。

举个例子。用户问“查一下昨天订单超时率是多少”。如果只是RAG问答，即使知识库里塞满文档，模型没有日志数据也回答不了。如果是Agent，它可以识别出这个请求需要查日志接口，于是调用一个ES Rest API，把查询条件拼好，拿回数据，再根据结果生成结论。整个过程中，“调哪个接口”“怎么拼接参数”“结果是否需要再查一次”都由Agent自己决定。

学习第一阶段的目标，不是写代码，而是建立这个判断框架。你要能说清楚：

• 大模型在Agent里负责什么；
• 工具调用负责什么；
• 记忆、规划、路由这些概念分别解决什么问题；
• 什么样的任务适合用Agent，什么样的任务用普通RAG就够了。

如果这些概念还没理清，先不要急着装LangChain或LangGraph。

1.2 第二阶段：用RAG工程任务建立第一个可运行系统

RAG是目前最容易验证的学习切入点。原因很直接：它的输入输出都清晰，问题进来，检索文档，拼成上下文，模型回答，再附上引用来源。哪个环节出问题，一眼就能看到。

这一阶段不要追求复杂架构，先做最小可用系统。准备几份PDF或Markdown文档，把它们切块、向量化、存到向量数据库，然后实现一个问答接口。跑通之后，要记录三件事：

• 文档加载后是否正确，而不是加载了就完事；
• 检索出来的chunk能不能支撑回答；
• 最终回答是否带引用，用户能不能回溯到原文。

我在实际测试时，一般会先拿3到5个问题去验证。不是问“今天天气怎么样”这种问题，而是问“这份文档里的退款政策是什么”“第四章提到哪些异常码”，这类问题必须依赖文档内容才能回答。如果这3到5个问题都不能稳定答对，后面再调LangGraph也没意义。

1.3 第三阶段：用LangGraph把流程串成Agent

RAG跑通之后，下一步是把它从固定流程改成有分支、有循环、有状态的Agent。这里LangGraph是绕不开的。

LangGraph的核心概念不复杂：把任务拆成多个节点，每个节点是一个函数，节点之间有边相连。数据在节点之间流动，由一个共享的State保存。与普通链式调用不同的是，图结构支持条件路由，也就是根据前面节点的输出，决定下一步走哪个分支。

我在跑通第一个LangGraph示例时，做的流程是“意图判断 -> 调用工具 -> 生成回答”。先让模型判断用户是否需要一个外部工具，如果要，就进入工具节点；如果不要，就直接回答。这个示例虽然简单，但已经包含了Agent最核心的循环能力。

这一阶段要关注的不是跑通官方Demo，而是能自己改路由条件。例如新增一个意图，让任务进入另一个子流程。只有能改条件路由，才算真正理解了LangGraph。

1.4 第四阶段：私有化部署、调优与对齐

最后才是部署调优，不能反过来。很多人第一天就想着把大模型私有化部署，结果被显存、接口、并发问题卡了三天，反而把Agent逻辑复杂度忽略了。

私有化部署解决的问题是：数据不出内网、调用可控、不依赖外部API。但部署不等于启动一个模型服务。你还要考虑API入口、向量数据库、日志监控、重启恢复、权限控制这些工程问题。

调优则要围绕指标展开：单次任务耗时、首字返回速度、成功率、失败重试率、资源占用。对齐则是让模型输出符合业务规则，不编造来源、不越权操作、不偏离任务目标。

完成这四个阶段之后，一个双非背景的开发者，已经不只是在“学概念”，而是有了一条完整的本地项目经历。下面按顺序拆每个阶段的实操要点。

2. 技术选型：LangChain、LangGraph、RAG框架到底怎么选

2.1 LangGraph和LangChain的区别

很多新手会把这个关系搞反，以为LangGraph是LangChain的升级版，或者两者选一个就可以。

LangChain更像一个组件库。它封装了大量模型调用、提示词模板、文档加载器、工具接口，方便你快速把“模型 + 检索 + 工具”拼成一个固定流程。它的优点是上手快，缺点是流程固定，一旦要支持复杂分支，代码会变得绕。

LangGraph则是面向状态图的编排框架。它允许你用图的方式定义节点和边，支持条件分支、循环、子图、并行节点。更适合需要决策、多次工具调用、多轮状态维护的Agent。

我的建议是：先别纠结选哪个。先用LangChain或直接用LangChain里的RAG组件，把文档问答跑通。然后换到LangGraph，把同一个问答流程重构成图结构。这样对比一次，比看十篇教程都有效。

也有人在问LangGraph有没有Rust版本。学习阶段不用在这个问题上纠结，Python生态的资料和示例最多，调试也方便。跑通核心逻辑之后再考虑性能优化，不要一开始就换语言。

2.2 RAG框架和向量数据库选择

RAG项目里，除了模型，还要选框架和向量数据库。

框架层面常见的有LangChain、LlamaIndex、Dify、MaxKB、FastGPT，以及Java技术栈下的Spring AI。它们定位不太一样。Dify、MaxKB这类工具更偏“开箱即用”，适合快速搭知识库后台；LangChain、LlamaIndex偏“代码可控”，适合深入定制。

MaxKB这类工具能不能调优？可以，但你要理解它内部的文档解析、切块、向量化和检索逻辑，而不是只改界面参数。否则知识库效果不好时，你根本不知道问题出在哪个环节。

向量数据库方面，常见的有Qdrant、Milvus、pgvector、Elasticsearch。选型要看数据量和场景：

• 小规模知识库，Qdrant或pgvector足够；
• 日志分析、已有ES集群的场景，直接用ES可以减少组件；
• 需要高并发、大规模向量检索，再考虑Milvus。

如果你本身是Java技术栈，用Spring AI 2.0搭配Qdrant做一个RAG知识库，完全可行。关键是先跑通，再考虑扩展。

2.3 没有GPU时先跑哪些项目，避免卡死

很多双非同学手头没有GPU，这并不影响学习。核心策略是：选小模型、选量化模型、把模型服务和RAG流程解耦。

没有GPU时，可以先跑7B以下参数的量化模型，例如qwen2系列的小尺寸版本。CPU推理可以跑，速度会慢一些，但用来验证RAG流程和Agent逻辑没有问题。真要跑大模型，可以先用云端API做开发调试，本地环境只保留embedding模型和小模型。

还有一点要注意：embedding模型不需要像LLM那样大。用轻量级embedding模型把文档向量化，LLM负责生成最终回答。这样大部分任务在普通配置上都能跑起来。

部署和调优的时候，先看资源占用，再决定模型规模。不要一上来就部署一个14B模型，等内存吃满再后悔。

3. RAG落地时最容易出问题的六个环节

3.1 文档加载与解析：不能只装一个loader

RAG最开始的一步，也是最容易翻车的一步，是文档加载。

很多PDF看起来正常，实际上是图片扫描件，没有文本层。如果你直接加载，得到的可能是空白内容或乱码。还有一些复杂表格，拆开后语义就断了；代码文档如果丢掉了缩进，后面的模型很难理解。

我一般会用一个笨办法验证：加载完文档后，随机打印前10个chunk，直接看内容是否可读。不要相信loader的成功提示，要看实际文本。

文档场景如果涉及扫描件，需要先做OCR识别。早期阶段尽量用带文本层的PDF或Markdown，减少预处理成本。

3.2 切块策略：切得太碎和切得太整都不行

切块是RAG里的经典问题。

切得太碎，检索结果的语义不完整，模型拿到一段没头没尾的文本，很难生成正确回答。切得太整，每个chunk太长，提示词空间被浪费，检索也可能带回大量无关内容。

通用做法是先按文档结构切。比如先按标题、段落切，再对超长段落做二次切分，并保留overlap。代码文档最好按函数或类切，而不是按固定字符硬切。

切块参数不要照搬网上教程。我会准备一组固定问题，分别用不同chunk size测，看哪个参数下检索结果和最终回答更稳定。这个验证成本不高，但能避免后面反复改。

3.3 向量化与检索：相似度分数高不代表答得对

向量检索不是万能的。它擅长语义相似，但不擅长精确匹配。比如查一个订单号、邮箱、错误码，向量检索可能不如关键词检索准确。

所以生产环境通常会用混合检索：向量检索 + 关键词检索，再做一次融合排序。如果资源允许，可以再加一个rerank模型，对候选chunk重新排序。这一步对最终回答质量提升很明显，但前期不一定要引入，先用向量检索跑通即可。

另外，不要把向量相似度分数当作可信度。在很多场景下，top-1返回的chunk未必正确。要判断检索是否成功，需要看答案能不能引用到原文。

如果文档里领域术语多、实体关系复杂，可以考虑了解ontology RAG，也就是引入本体或知识图谱。但这是进阶方向，第一步做成关键词 + 向量就够了。

3.4 引用溯源与groundedness：回答必须能回到原文

RAG最容易被忽略的是引用溯源。

一个没有引用来源的回答，在知识库场景里基本不可用。用户问“这个制度是哪个版本规定的”，如果系统回答说“根据文档规定”，却拿不出出处，那和普通模型幻觉没有区别。

要在实现上做到两点。第一，每个chunk要保留文档ID、章节号、页码或来源路径，生成时让模型带上引用标识。第二，要检查回答的groundedness，也就是回答有没有足够依据。简单做法是把生成回答和检索chunk一起送给模型，让模型判断“该回答是否完全由chunk支撑”。如果判断结果为否，可以选择拒答或补充说明。

这一步不能省。很多RAG项目看起来能回答，一检查引用就露馅。

3.5 企业级RAG的常见痛点

企业级RAG和本地Demo的差别，主要体现在权限隔离、增量更新、知识冲突和监控。

权限隔离是第一个门槛。不同角色只能看到对应权限的文档，如果不做隔离，检索就会泄露非授权内容。增量更新也一样，知识库不能总靠全量重建，要能单独更新某份文档，并保证旧数据不被重复查询。

知识冲突更容易被忽视。两份文档对同一个问题说法不一致，检索系统可能随机返回其中一个，答案不稳定。这时候需要给文档加版本和优先级，或者把冲突规则单独处理。

日志分析场景里，ES是常见底座。一个合适的做法是：Agent通过ES Rest API查询日志，先得到结构化数据，再结合RAG知识库生成分析结论。这样既保留原始查询链路，又让回答有数据支撑。

3.6 本地RAG实例：llama.cpp + qwen2-7b + FastAPI

如果要在本地搭一个RAG知识库问答系统，一个常见组合是 llama.cpp + qwen2-7b + FastAPI。

架构可以拆成三个服务：

• 模型服务：用llama.cpp启动兼容接口，负责文本生成；
• embedding服务：负责把问题和文档切成向量；
• FastAPI应用：负责编排RAG流程，接收请求、检索、拼接提示词、调用模型、返回结果。

以下是一个示例启动命令，路径和模型名以你实际下载的文件为准：

# 示例：用 llama.cpp 启动模型接口 llama-server -m ./models/qwen2-7b-instruct-q4_k_m.gguf --host 0.0.0.0 --port 8080

然后再写一个FastAPI接口，接收用户问题，去向量库检索前几个chunk，拼进提示词，调用本地的模型接口，最后把答案和引用一起返回。

这个方案的好处是，模型和业务代码分开，后面替换模型、调整参数都比较方便。缺点是CPU推理速度不够快，不适合高并发。所以它更适合学习、原型验证和低并发私有化场景。

4. LangGraph实战：从链式调用到条件路由和子图

4.1 先用最简流程跑通一个Agent

LangGraph里最重要的三个概念是：State、Node、Edge。

State是贯穿整个图的数据对象，保存用户输入、中间结果、模型输出。Node是处理函数，接收State，处理后返回更新后的State。Edge定义节点之间的执行顺序。条件边则会根据State内容，决定跳到哪个节点。

一个最简Agent可以这样设计：

1. 模型判断当前问题是否需要调用工具；
2. 如果需要，进入工具节点；
3. 工具节点把结果写回State；
4. 模型根据工具结果生成最终回答；
5. 如果不需要工具，直接生成回答。

伪代码如下，实际API以你安装的LangGraph版本为准：

graph = StateGraph(AgentState) graph.add_node("route", route_agent) graph.add_node("search", search_tool) graph.add_node("respond", respond) graph.add_conditional_edges( "route", should_search, {"yes": "search", "no": "respond"} ) graph.add_edge("search", "respond")

跑通这个流程后，你的目标不是打印出“Hello Agent”，而是能够在一段详细日志里，看到每一步走了哪个节点、State里新增了什么、最终答案是否用了工具结果。

4.2 条件路由与分支控制，别忘记循环检测

条件路由是LangGraph里最实用的能力，但也是新手容易写崩的地方。

我做过一个日志分析Agent，路由逻辑是：先判断用户问题里是否包含时间范围、服务名、错误码。如果信息不全，先进入“追问”节点；如果信息完整，进入“查询日志”节点；如果查询结果为空，再进入“调整查询条件”节点。

这个场景用普通链式代码写会很乱，但用条件边就很清楚。每个分支对应一个节点，State里维护查询条件，节点之间互不干扰。

要注意的是循环次数。Agent一旦允许循环，就可能出现死循环：模型反复判断需要查询，却一直查不到结果。因此一定要在State中加上最大步数，或者记录当前循环次数，超过阈值后强制跳转到回答节点。

不要觉得自己的Agent业务简单就不会死循环。只要有条件路由，就必须考虑终止条件。

4.3 子图、并行分支与长期记忆

当一个Agent节点里的函数越来越长时，就要开始拆子图了。

子图可以理解为把一段完整流程封装成一个节点。比如“知识库问答子图”内部可能包含文档检索、rerank、生成三个步骤，但对于上层Agent来说，它只是一个可调用的节点。这样整个逻辑会清晰很多。

并行分支适合多个独立工具同时调用的场景。比如Agent需要同时查订单列表、库存、运费规则，三个查询互不依赖，就可以做成并行节点。但要注意，并行节点都往同一个State里写数据时，要约定好字段，不要互相覆盖。

长期记忆是一个值得做的扩展，但不适合刚开始就做。先把状态保存在当次会话里，跑通之后再考虑把对话摘要、用户偏好写到外部存储，让Agent在多轮对话之后仍然记得之前的信息。LangGraph有持久化相关能力，但真正落地时，你还需要设计存储结构和读取时机。

4.4 可视化与调试：不能只靠 print

调试LangGraph时，只看print输出会很累。比较好的方式是观察State变化和节点执行顺序。

LangGraph本身有状态流的概念，可以打印出每一步节点名、输入输出摘要。你可以把这些信息写到日志文件里，方便定位“到底是在哪个节点出了问题”。

也有同学问，能不能用ECharts画LangGraph的节点可视化。可以用来展示流程图给非技术人员看，但调试时不能只依赖一张静态图。静态图解决的是理解问题，不是运行问题。你真正要看的，是每次运行里State的真实值、条件判断的结果、以及某个节点是否被重复执行。

5. 私有化部署：普通配置下能跑起来的方案选择

5.1 私有化部署不是下载模型就完事

很多人理解的部署，是下载一个模型权重，启动一个端口，然后拿Postman调用一下，就宣布完成。

真实的私有化部署要考虑完整链路：模型文件、推理服务、API网关、向量数据库、外部工具连接、日志监控、重启恢复、权限控制。每个环节都会影响系统能不能长期稳定跑。

我会用这样一个清单检查：

• 如果模型服务崩溃，能不能自动重启；
• 如果某个请求超时，接口返回什么错误；
• 批量任务跑到一半失败，有没有重试机制；
• 模型更新后，之前的RAG结果和缓存是否失效；
• 日志记录是否包含请求ID、节点状态、耗时和错误原因；
• 用户输入是否经过权限校验，尤其是RAG文档权限。

这些问题没有处理好，私有化部署只是把问题从云端搬到了本地，稳定性和可用性一点没提升。

5.2 模型选择与显存估算，先测再说

模型选择不能只看参数量。同一个7B模型，FP16、8bit、4bit量化版本占用的资源和速度完全不同。上下文长度、并发数、输入token长度也会影响显存和内存占用。

我一个比较稳妥的做法是：先选一个小模型，搭好接口，打印服务端的显存、内存和响应时间。然后逐步增加上下文长度和并发数，观察系统在什么时候出现明显降速或OOM。

不要在网上找一张“显存需求表”直接套用，因为你的模型文件、量化方式、并发数都不一样。先测单个请求，再测多个请求，才能得出当前机器适合跑什么模型。

如果没有GPU，那CPU推理也不是不能用。qwen2-7b这类模型用CPU跑，做单条问答是可接受的，但并发上百就不太现实。学习阶段用CPU跑通，展示时说明硬件边界，反而更有说服力。

5.3 常见部署方案对比

私有化部署并没有唯一正确答案，关键看你的场景。

我建议双非背景的同学先走前面两行的路线。把模型服务和业务代码分开，模型服务只管推理，FastAPI只管编排。后续如果换更大的模型，业务代码不用大改，只需要替换模型服务地址。

6. 调优与对齐：让系统不只是“能跑”

6.1 调优必看的指标和工具

调优的第一步是定义基线，不是直接在界面上改参数。

固定一个10到20条问题的测试集，把问题、输入参数、预期输出、是否成功、耗时、引用来源都记录下来。之后每次改动，都用同一套测试集跑一遍，对比前后差异。

我关注的指标主要有这些：

• 单轮总耗时：从请求进入到最后返回的时间；
• 首字延迟：用户能否快速看到第一个字；
• 答案成功率：回答是否与预期一致；
• 引用完整率：回答是否附带正确来源；
• 失败重试率：哪些请求需要重试才能成功；
• 资源占用：模型服务和向量库的内存、CPU、显存。

没有这些指标，调优就是在碰运气。你觉得改了切块参数后“好像变好了”，但如果没有记录，过两天就忘了改了什么。

6.2 批量调优的思路，不要一条条肉眼比较

当测试集比较大时，肉眼比较很不现实。这时候要批量跑、批量记录、批量对比。

流程可以这样设计：

1. 把测试问题放进一个JSON文件，每个问题带ID和预期方向；
2. 批量请求Agent或RAG接口，把输出、耗时、引用写到另一个JSON文件；
3. 写一个小脚本做对比，自动统计成功率、平均耗时、失败列表；
4. 每次只改一个变量，比如chunk大小、top-K、温度、提示词模板；
5. 保留基线结果，不要同时改多个参数。

批量调优的坑在于，不能只看“跑得快了”或者“答得顺了”。速度提升但成功率明显下降，这个改动就不能上线。对于A/B对比，可以先跑两批，分别记录，再做判断。

6.3 对齐问题，先从提示词工程开始

对齐这个词听起来很深，但在实际项目里，往往是从提示词、输出校验和权限控制开始的。

一个RAG知识库Agent，至少要避免三种输出：编造文档里不存在的内容、给出没有引用来源的结论、或执行超出权限范围的操作。

先在系统提示词里明确规则。例如：

• 只能使用检索到的内容回答；
• 如果检索内容不足以支撑回答，直接说明；
• 给每个结论附带来源标识；
• 涉及删除、修改、转账等敏感操作，必须有用户确认。

然后做输出校验。程序检查回答中是否包含来源标记，或者用另一个模型判断回答是否由检索内容支撑。如果校验不通过，就拒答或重新生成。

不要一上来就做模型微调。先把提示词和输出校验做扎实，再看还有哪些问题必须通过训练解决。

6.4 判断一个Agent系统能不能上生产

“能跑”和“能上线”是两件事。我判断一个Agent能否进入生产，主要看以下几点：

• 有没有完整日志，出了问题能不能定位；
• 请求失败时，用户得到的是明确错误还是空白；
• 批量任务有没有队列和重试，不会因为一条数据挂掉整个流程；
• RAG回答是否带引用，能否追溯到具体文档；
• 模型接口超时或并发升高时，系统会不会拖垮其他服务；
• 知识库更新后，旧缓存和旧结果是否会被清理。

如果以上检查有一项没有做到，就先不要对外提供服务。学习项目可以粗糙，生产项目必须把失败路径补齐。

7. 给双非背景学习者的路线建议和简历项目思路

7.1 7天学习路线怎么安排

我不建议7天做成“从小白到大神”，但7天足够完成一个带RAG、带LangGraph、带本地部署的Agent项目。时间可以这样分配：

这个路线不追求广度，追求的是把一条链路走通。中间遇到问题很正常，卡住了就回到对应环节排查，不要急着换方案。

7.2 做哪些项目更能体现工程能力

面试或写简历时，最怕的不是项目简单，而是说不清自己做了什么。

相比一个“聊天机器人”，下面几类项目更容易体现工程能力：

• 内部知识库问答系统：带文档管理、切块、向量检索、引用溯源；
• 日志智能分析Agent：通过ES Rest API查询日志，再生成分析结论；
• 文档批量处理工作流：定时任务 + RAG + 结果输出；
• 私有化离线问答服务：模型和内网数据都在本地，接口给业务方调用。

写项目时不要只写“用了LangGraph、RAG”，要写清楚输入输出、并发条件、资源占用、测试集大小、效果如何、失败时怎么处理。这些细节才是经验感的来源。

7.3 常见误区与应对

学习这一路，我见过最多的误区是：

• 只追新框架，不跑真实任务；
• 下载了模型就以为完成了部署；
• 直接把教程参数搬过来，不做验证；
• 只写链式调用，没有考虑分支和循环；
• 回答没有引用，却说RAG效果好；
• 批量任务一跑就失败，却没有失败重试和日志。

遇到这些问题，不要急着换工具。先看输入输出是否符合预期，再看日志和资源占用，最后才回去翻参数和依赖版本。很多报错不是Agent能力问题，而是路径不对、版本不匹配、输入格式没处理干净。

最后留几个我自己排查时会优先看的点：输入文本是否正确，依赖版本是否冲突，向量库里是否有脏数据，模型服务是否真的在运行，输出目录是否有写入权限。先把这些基础问题排除，再谈调优。

如果你把单条任务跑稳了，再考虑批量和接口，这套链路就能真正变成你自己的项目经验。