RAG和Agent这两个词这两年都快被说烂了。但真到了自己动手做项目的时候很多人还是卡在同一个地方——看了无数教程概念讲得头头是道一打开代码编辑器就不知道从哪下手。我见过不少朋友收藏夹里躺着几十个保姆级教程真让他做一个本地知识库问答或者让AI自动调用工具完成一个任务直接就懵了。这次整理的这套资源核心就干一件事把RAG和Agent从理论概念变成你手上能跑起来的东西。不是那种丢一堆论文链接让你自己看的资料包而是从环境搭建、代码实现到部署调试的完整路径。这套内容适合真正想动手写代码的人不管你是刚接触大模型开发的新手还是已经写过几个demo想系统提升的开发者都能从中找到自己需要的部分。下面我按自己实际开发的经验把这套资源里涉及的核心内容拆开揉碎讲清楚每个环节的原理、做法和容易踩的坑。1. RAG与Agent先搞清楚它们到底解决什么问题1.1 大模型的两个天生短板直接用裸模型做应用很快会撞上两堵墙。第一堵墙是知识时效性和专业性问题。大模型训练数据有截止日期之后发生的事情它不知道。你问它某个内部系统的最新接口文档它只能胡编。即便你喂给它一些专业资料它也会一本正经地胡说八道——这就是所谓的幻觉问题。本质上是因为模型在生成时没有可靠的信息来源约束它。第二堵墙是只能动嘴不能动手。模型再聪明也就是一个文本生成器。你让它帮你查一下明天的天气然后定个闹钟它做不到因为它没有手不能调用天气API也不能操作你手机上的闹钟应用。RAG检索增强生成和Agent智能体就是针对这两块短板发展出来的技术方案。RAG给模型装上了搜索引擎让它从外部知识库中检索相关内容再基于这些内容作答。Agent则给模型装上了手和脚让它能够调用工具、执行动作完成更复杂的任务流程。1.2 两者不是二选一而是互补关系很多人容易混淆RAG和Agent觉得它们是两种独立的架构。实际上在真实的工业级应用里它们经常是组合在一起的。RAG解决的是知识从哪来的问题。它像给模型配了一个专属图书馆回答问题时先去图书馆查资料再组织语言。典型场景比如企业知识库问答、客服机器人、文档分析助手。Agent解决的是任务怎么做的问题。它像给模型配了一个工作团队可以自己规划步骤、调用工具、检查结果。典型场景比如自动化办公助手、数据分析Agent、能自己写代码并执行调试的编程助手。一个复杂的应用往往是Agent负责整体流程调度遇到需要专业知识的地方内嵌RAG去查询资料。比如一个市场分析Agent先拆解任务然后用RAG查询公司内部历史报告再调用数据分析工具生成图表最后汇总结论。这就是为什么把这套资源放在一起讲——它们是配套的。1.3 什么时候用RAG什么时候上Agent从实际项目出发我给一个判断标准。如果你的核心需求是基于特定资料回答问题比如做一个法律文书问答、产品说明书助手那用RAG就够了别把架构搞复杂。如果你需要的是让AI自主完成多步骤任务比如自动收集信息并生成周报、根据用户描述自动编排工作流那才需要引入Agent。如果两者都有——比如既要查企业资料又要根据查到的资料自动执行后续操作——那就别纠结RAG和Agent一起上。至于怎么组合我在后面实操环节细讲。2. 开发前的技术栈与环境准备2.1 核心技术选型这套资源里涉及的技术栈我建议按下面的标准来选都是目前社区最活跃、踩坑资料最多的方案。大模型底座方面本地部署可以用一些开源模型占资源少、上手快。如果追求效果建议直接调用云服务商的API。刚开始做学习项目用API最省心不用折腾显卡驱动和显存优化。向量数据库是整个RAG链路的关键。初学阶段用轻量级的本地向量库数据量不大配置极其简单适合跑通流程。如果数据量上了百万级再考虑上重型的专业向量数据库。框架选择上现在主流的是LangChain和LlamaIndex。简单区分一下LangChain更偏Agent和工具调用编排生态丰富LlamaIndex更专精于文档索引和检索。不过现在两者都在往对方领域扩展选哪个都能做出完整项目关键是别混着用选定一个深入学。2.2 环境搭建的几个细节环境搭建本身不难但有几个细节容易让新手卡住。Python版本不要太新也不要太旧3.10到3.11之间最稳妥。某些依赖库对Python 3.12以上的支持还不完美装包的时候容易报编译错误。建议直接用Anaconda创建独立环境别把依赖装进系统全局环境里不然项目多了以后依赖冲突会让你怀疑人生。装依赖包的时候注意看版本兼容性。很多报错根本不是代码问题是版本不匹配。比如新版的框架改了底层API你照着老教程写代码就会各种报错。我的习惯是装包时用pip freeze锁定版本复现的时候直接按这个版本来。API Key的管理也要养成好习惯。别把密钥硬编码在代码里更别提交到代码仓库。用环境变量或者独立的配置文件管理生产环境可以用密钥管理服务。这不是小题大做——我在实战中见过有人把API Key提交到公开仓库几分钟就被别人拿去刷了几千块钱的额度。2.3 一个最小可用的目录结构按这套资源里的项目模式建议一开始就养成良好的目录组织习惯project/ ├── config/ # 配置文件、环境变量管理 ├── data/ # 原始文档、知识库文件 ├── src/ │ ├── rag/ # RAG相关代码 │ ├── agent/ # Agent相关代码 │ └── utils/ # 公共工具函数 ├── tests/ # 单元测试 ├── requirements.txt # 依赖清单 └── README.md别小看这个步骤项目一旦复杂起来一个清晰的目录结构能省掉大量找代码的时间。3. 手写一个RAG系统的核心链路3.1 索引构建文档切分有讲究RAG的第一步是把知识库文档处理成模型能用的形式。这个阶段最重要的操作就是文档切分——把长篇文档切成一个个块Chunk然后对每个块做向量化存入向量数据库。切分策略直接影响检索效果。切得太碎比如一句话一块语义信息不完整检索时容易匹配到残缺内容切得太大比如整章一块向量化时语义被稀释检索精度下降。实际项目中我常用的是一个动态切分策略——优先按文档本身的语义结构切比如按标题和段落边界再配合固定窗口大小兜底。切分时还有一个细节重叠区域。相邻两个块之间保留一部分重叠内容避免检索时正好把一句话从中间断开。这个细节在刚开发时不觉得有用等实际用起来会发现它能显著提升检索命中的完整性。向量化模型的选择也要上心。市面上有一些优秀的开源嵌入模型处理中文效果都还行。一个关键建议检索所用的嵌入模型和后续生成时用的模型不需要是同一个它们负责的任务不同。3.2 检索与重排序不要让垃圾进上下文很多初学者的RAG效果差问题不在生成环节而在检索环节。检索返回的内容质量不过关就算生成模型再强也白搭。基础的检索方式是向量相似度检索把用户问题向量化然后从向量库里找最相近的块返回。这种方式实现简单但精度有限。实际开发中我强烈建议加上重排序Rerank环节。思路是先用向量检索快速召回一批候选内容比如Top 20再用一个精排模型对这批候选逐条打分选出最相关的Top 3到5条送给模型。加入Rerank之后的效果提升非常明显。我在一个具体项目中测试过只加了Rerank不调整任何其他参数答案的准确率提升了将近30%——因为向量检索选出的内容和真正最相关的内容往往存在偏差只有精排才能消掉这个偏差。还有一个容易被忽视的细节元数据过滤。实际知识库里往往包含大量文档比如不同来源、不同日期、不同类型的资料。在检索时如果能够先根据需求过滤掉不相关的类别只在匹配的子集内检索效果会精准得多。3.3 增强生成提示词模板远比想象中重要检索完成之后把检出来的内容和用户问题一起交给大模型让它生成最终答案。这一环节听着简单但提示词的写法对结果影响极大。我在代码里用一个Prompt模板来组织发送给模型的内容你是一个专业助手。请根据下面提供的参考资料回答用户问题。 如果参考资料中没有相关信息请明确回答资料中未找到相关内容不要编造。 参考资料 {context} 用户问题 {question} 请基于以上资料回答问题这段模板的作用是把大模型钉在检索结果上不允许它超出范围发挥。不加这段约束的话模型一遇到检索内容不完整的情况就会自动启用训练时学到的知识来脑补幻觉又回来了。这边也顺便说一下上下文管理。大模型有上下文窗口限制如果检索结果太多超出窗口限制就得做截断或摘要处理。更合理的做法是做好检索质量控制宁缺毋滥——只把真正相关的内容喂给模型比什么都往里塞效果好得多。3.4 一次完整的RAG请求经历了几层处理把整个链路串起来看一次典型的RAG问答请求是这样流转的用户输入问题系统对问题进行改写——有时候用户的提问口语化严重直接拿去检索效果差需要用LLM把问题规范化或者拆解成多个子查询向量化用户问题检索向量库召回候选内容Rerank精排筛选出最相关的几个块组装Prompt连同上下文一起发给LLMLLM生成答案返回给用户很多成熟的RAG系统还有一个反馈收集环节让用户对答案点赞/点踩把质量不好的案例收集起来定期分析是检索错误还是生成错误逐步优化。4. Agent开发的核心机制与落地实践4.1 Agent架构的四个关键机制如果说RAG是給模型补知识Agent就是给模型补行为能力。一个成熟的Agent架构通常包含四个关键机制。**规划Planning**是Agent的大脑。模型接到一个复杂任务后不能直接一口气完成需要把它拆解成多个子任务排好执行顺序。例如让Agent分析这份销售数据并生成月度报告它需要先规划读取数据 → 清洗数据 → 做统计分析 → 生成图表 → 撰写报告。规划能力决定了Agent处理复杂任务的上限。**记忆Memory**是Agent的笔记本。短期记忆负责在同一任务中记录中间状态比如已经做完了哪一步、下一步该做什么。长期记忆则负责跨会话保留重要信息比如用户的偏好设置、历史交互信息。没有记忆机制的Agent每次交互都是失忆状态没法做多轮任务。**工具调用Tool Use**是Agent的手。模型本身没有执行能力但可以通过调用外部工具来完成具体动作——查询数据库、调用API、执行代码、操作文件等。这里的核心是给模型提供准确的工具描述让它知道什么情况下该用哪个工具、参数怎么填。**反思Reflection**是Agent的质检员。Agent执行完一步后需要自我检查结果是否正确如果发现问题就调整策略重试。这个机制让Agent具备了纠错能力大幅提高复杂任务的完成率。4.2 从代码看Agent如何调用工具用代码展示一个简化的Agent工具调用过程比空谈概念直观得多。def search_weather(city: str) - dict: 查询指定城市的实时天气 # 这里实际调用天气API return {city: city, weather: 晴, temperature: 26} def calc_expression(expression: str) - float: 计算数学表达式的结果 return eval(expression) # Agent定义自己有哪些工具 tools [ {name: search_weather, description: 查询城市实时天气, parameters: {city: 城市名}}, {name: calc_expression, description: 计算数学表达式, parameters: {expression: 数学表达式字符串}}, ] # Agent循环思考 - 决定调用哪个工具 - 观察结果 - 继续思考 def agent_loop(user_input: str, tools: list, max_steps: int 5): messages [{role: user, content: user_input}] for step in range(max_steps): response llm_with_tools(messages, tools) messages.append(response) if response.has_finished(): return response.final_answer() # 模型决定调用工具 tool_call response.tool_call result execute_tool(tool_call) messages.append({role: tool, content: result})这个循环就是Agent的基本骨架。真实框架里有很多实现细节工具结果怎么格式化喂回给模型、多个工具调用怎么并行、调用出错怎么重试——这些都是实战中会反复碰到的问题。4.3 Agent工作流中的一个高频组合RAG as a Tool回到我在1.2节说的内容——RAG和Agent怎么组合。最常见的模式就是把RAG作为一个工具挂在Agent下面。比如做一个企业知识库数据分析双功能Agent可以定义两个工具search_knowledge_base(query)基于RAG检索企业知识库返回相关资料摘要run_sql_query(sql)执行SQL查询返回数据结果用户在对话中既可以问公司的年假政策是什么Agent自动调用RAG工具去查知识库也可以问上季度各产品线的销售情况Agent调用SQL工具去数据库里查。这个模式下Agent担任了调度员的角色RAG变成了它手中的一件工具。这种架构的优势是灵活——你想加新能力不用改Agent核心逻辑只需要注册一个新的工具。4.4 实践中Agent调试的痛点Agent开发跟传统后端开发有个显著不同结果不确定性高。传统接口调不通就是调不通Agent是有时候能做对有时候做错而且不知道错在哪。这给调试带来了很大麻烦。我在实际项目中总结的经验是Agent日志里一定要记录完整的思考链Chain-of-Thought也就是模型每一步的输入输出、工具调用参数和返回结果。出了问题顺着思考链排查很快能定位是规划错了、工具选择错了还是工具返回值格式解析错了。还有一个常见问题Agent陷入死循环反复调用同一个工具拿不到有用信息。解决方法是设置最大迭代次数并在Prompt中明确告诉模型如果尝试了X次还没成功就停止把这个情况告诉用户。这个设定虽然简单但能避免大量无效调用。5. 全套免费资源的正确打开方式5.1 资源清单都包含了什么这套资源里我认为最有价值的部分是几类内容。开源框架的官方文档和示例代码与其看二手教程不如直接读官方文档。尤其是几个主流框架的官方文档对概念的解释、示例代码质量都相当高而且持续更新基本不会过时。高质量的中文教程和实战项目源码这套资源里收集了一些经过筛选的项目源码从简单的文档问答到复杂的多工具Agent都有。建议不要只是浏览而是按我后面讲的方法一个项目一个项目亲自复现。公开的数据集和评测基准做RAG或Agent没有测试数据就没办法衡量效果好坏。资源里整理的公开数据集可以用来评估你的系统效果跟其他方案对比时也有据可依。学习路线图和知识图谱这套资源里的学习路线与我自己摸索的路径基本一致——从概念理解、到基础组件开发、再到系统整合优化。按这个顺序走能少走很多弯路。5.2 资源使用的正确姿势拿到免费资源后最容易犯的错误是收藏即学会。我的建议是每份教程必须配合至少一次完整实操。具体操作可以这样按照教程里的项目从零开始搭环境、写代码一步步跑通。卡住了先自己排查排查不了再去查别的资料。这个过程虽然慢但每一步踩的坑、读懂的错误信息才是真正长在自己身上的能力。看源码也有讲究。别从头到尾一行行读效率太低。我自己的习惯是先把项目跑起来然后从主入口文件开始跟代码执行流程走一遍——用户输入怎么流转、检索怎么触发、Prompt怎么组装、LLM怎么调用、结果怎么返回。跟着数据流读代码比逐行读效率高得多。5.3 建议的学习顺序按这套资源的内容我建议的学习路径如下第一步花三天时间弄清楚概念。RAG和Agent各自解决什么问题、核心组件是什么、有哪些主流框架。这个阶段只看不写在脑子里搭一个整体框架。第二步实现一个最简RAG。从文档加载、切分、向量化、存储、检索、Prompt组装到LLM生成每一步都自己写。这个过程能让你真正理解数据在整个RAG链路里是怎么流动的。第三步实现一个最简单的Agent。定义一个或两个工具让模型学会在需要时调用它们。熟悉思考-调用-观察这个循环。第四步把RAG和Agent组合起来做一个完整功能的项目。这时候可以选一个实际的业务场景比如做一个能查资料、能算数据、能生成报告的研究助理。第五步做效果优化。加上Rerank、做查询改写、优化Prompt、改进切分策略一步一步看数据指标的变化。6. 常见问题与排查技巧实录6.1 RAG效果差问题不在LLM这是我见过最多人犯的错误。RAG答得不准第一反应是换个更强的大模型。但绝大多数情况下换模型根本没有本质提升——问题出在检索环节。一个经典案例用户问XX产品的退款政策是什么系统答非所问。排查时先看检索返回了什么。如果返回的内容是某个产品介绍文档里的一句支持退款而不是退款政策详情那问题就在检索。这时候应该优化切分策略、调Rerank而不是换模型。把调试RAG的思路理一理按顺序排查几个环节用户问题是否被正确理解是否需要查询改写检索是否召回了好内容召回的排序是否正确送进Prompt的上下文是否足够且无噪声Prompt有没有明确约束模型的回答范围6.2 Agent失效多半是工具描述写得差Agent调用工具的准确率极大程度上取决于你对工具的描述。一段模糊的工具描述模型根本不知道什么时候该用它、参数该填什么。举例说明一个工具描述写数据分析工具模型很容易误用。如果写analyze_sales_data(month: str) - 分析指定月份如2024-03的销售数据返回月度总销售额、订单量、Top产品列表模型就知道什么时候该调用它、怎么填参数。工具描述里要包含这些要素工具的作用、参数的具体含义和取值示例、返回值结构、典型的适用场景。新手刚开始写Agent花在工具描述上的时间至少要和写代码的时间相当。6.3 上下文爆炸与超时问题Agent在多轮工具调用过程中消息列表会越来越长。如果每轮都把全部历史发给模型很快就超过上下文窗口限制。解决思路是压缩历史。可以截断到最近N轮对话也可以对前面轮次做摘要——用一个轻量模型把老对话浓缩成摘要替换掉完整历史这样既保留了关键信息又不占用太多上下文空间。还有一个实战细节调用外部模型接口时要考虑延迟和超时。Agent的多步执行天然比单次调用慢给用户反馈时要做好交互设计——至少告诉用户正在处理第X步避免被误会成系统卡死了。6.4 评测是提升效果的加速器实话说没有评测就谈优化都是瞎忙。你以为改了个Prompt效果更好了可能只是某几个测试案例上的巧合。建议在项目初期就准备一个评测集——几十个典型问题加标准答案就够了。每次改动跑一遍评测集用几个指标来衡量效果变化。如果一步的优化把指标提升了就保留没提升甚至下降了就回滚。做RAG评测时两组指标分开看一组是检索质量看正确内容是否被检索出来一组是生成质量看答案是否正确、是否忠于检索内容。绝大多数情况下生成质量不好的根因是检索质量问题——优先优化检索再调生成Prompt。7. 最后的一些实践感悟说了这么多技术细节最后分享一点我做这类项目的体会。第一别追求一步到位。别想着一开始就做一个完美的RAGAgent系统那是不可能的。先跑通最小闭环再从检索准确率、工具调用准确率、响应速度等维度一个个优化。每优化一个点都用数据验证是否真的有提升。第二案例沉淀特别重要。做过的项目、遇到的问题、解决的方案都记下来。这些东西在面试、项目汇报、写技术文章时都是宝贵的素材——比学历证书好使多了。第三多做笔记多总结多输出。现在信息差越来越少这套免费资源算是一个起点但真正的分水岭在于谁更愿意动手实操、更愿意把遇到的问题琢磨透。这套资源的链接和具体清单我放在文末了需要的直接拿去用就好。如果你在实操中卡住了可以把报错信息和代码发在评论区我看到会尽量帮忙看看。这个领域变化很快大家一起动手共同进步。