企业官网建设流程全解析

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问答请求是这样流转的：

1. 用户输入问题
2. 系统对问题进行改写——有时候用户的提问口语化严重，直接拿去检索效果差，需要用LLM把问题规范化，或者拆解成多个子查询
3. 向量化用户问题，检索向量库，召回候选内容
4. Rerank精排，筛选出最相关的几个块
5. 组装Prompt，连同上下文一起发给LLM
6. LLM生成答案，返回给用户

很多成熟的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. 最后的一些实践感悟

说了这么多技术细节，最后分享一点我做这类项目的体会。

第一，别追求一步到位。别想着一开始就做一个完美的RAG+Agent系统，那是不可能的。先跑通最小闭环，再从检索准确率、工具调用准确率、响应速度等维度一个个优化。每优化一个点，都用数据验证是否真的有提升。

第二，案例沉淀特别重要。做过的项目、遇到的问题、解决的方案，都记下来。这些东西在面试、项目汇报、写技术文章时都是宝贵的素材——比学历证书好使多了。

第三，多做笔记，多总结，多输出。现在信息差越来越少，这套免费资源算是一个起点，但真正的分水岭在于谁更愿意动手实操、更愿意把遇到的问题琢磨透。

这套资源的链接和具体清单我放在文末了，需要的直接拿去用就好。如果你在实操中卡住了，可以把报错信息和代码发在评论区，我看到会尽量帮忙看看。这个领域变化很快，大家一起动手，共同进步。