零成本跑通RAG与Agent开发：全链路Notebook实战指南

1. 项目概述与内容定位

先聊点实在的。AI Engineer Notebooks 这类资源，核心就一句话：让你在不花一分钱的前提下，把 RAG（检索增强生成）和 Agent 开发这两条技术路线，从概念到代码、从 demo 到评测，完完整整跑通一遍。

我见过太多人卡在同一个地方：收藏了几十个教程，看了无数篇“RAG 入门”“Agent 实战”的文章，结果真到自己动手时，连环境都搭不起来，更别说跑通一个像样的项目了。为什么？因为大部分教程要么只讲概念不给代码，要么给了一段孤立的代码却不说清楚它在一个完整系统里处于什么位置、前后的数据流是什么。

这个项目的价值恰好在这里。它给的是一整套 Notebook，从向量化、索引构建到检索链路，再到 Agent 的工具调用、任务编排，全链路都覆盖了。你不需要先买 GPU 服务器，也不需要订阅昂贵的 API，跟着 Notebook 一步步执行就能看到效果。这背后用的是免费的开源模型和开放数据集。

适合什么人看？两类人。第一类是刚入门的算法工程师、后端开发，你懂 Python、懂一些深度学习基础，但没做过完整的 RAG 或 Agent 项目，想快速建立“全链路认知”。第二类是已经在做 RAG 但效果一直不理想的人，你需要一个可以自由修改参数、快速做对照实验的环境，而不是一个封装得死死的框架。

我在实际跑这个 Notebook 的时候有个很明显的感觉：它不是在教你调包，而是在帮你建立“系统思维”。RAG 不是把文档塞进向量数据库就完事了，Agent 也不是单纯调一下大模型的接口。真正决定项目上限的，是你对每个环节的理解深度和对细节的把控能力。这个 Notebook 系列最大的贡献，就是把这些细节一个个摊开在你面前。

2. 环境准备：0 成本跑通的前置条件

既然目标是“0 成本跑通”，环境这块就得精打细算。我直接说结论：如果你有能跑得动 Chrome 的电脑，就够用了。下面把几种方案的使用体验和注意点逐一拆开讲，你在动手前先花十分钟把这条链路理清，比后面反复报错再回头排查要省事得多。

2.1 算力选型：白嫖云服务与本地运行怎么选

白嫖云服务这块，Google Colab 是首选，绝大多数 Notebook 在它上面的兼容性最好。免费版 T4 的 16G 显存，对本文涉及的主流开源模型完全够用。不过你得有应对限流的心理准备——Colab 免费版在高峰期会显示“You cannot currently connect to a GPU”，这种时候要么等半小时再连，要么换个时间段。有个小技巧：免费版断线机制是“长时间不操作才会断”，如果你在跑长任务，可以在 Cell 里挂一段循环播放提示音的代码，每隔一两分钟有个动静，避免被判定为闲置。

如果你只有 8G 显存的本地显卡，也能跑但要注意量化策略。4bit 量化下的 7B 模型大概占 5-6G 显存，加上向量化和推理的临时开销，8G 差不多是底线。要是显存不够，把嵌入模型换成更小的版本，或者干脆减少文档分块数量，都是立竿见影的办法。

Kaggle Notebook 是另一条免费路线，每周 30 小时 GPU 额度，对学习场景完全够用。它有个好处是数据集可以直接挂载，省去下载的等待时间。但 Kaggle 的网络访问比 Colab 差一些，下载 HuggingFace 模型经常会中断，建议提前把模型缓存好。我这里直接给出一份针对 Colab 的部署时间参考：

2.2 模型与 API 的免费替代方案

这可能是最影响你实际体验的环节。OpenAI 的 API 确实好用，但学习场景完全有免费的替代路径，而且效果对学习来说已经足够。

Embedding 模型直接用 HuggingFace 上的开源模型，别在这上面多花钱。BAAI/bge-small-zh-v1.5是我用的最多的，中文场景表现稳定，模型小加载快。如果你处理的文档是中英混合，可以考虑BAAI/bge-base-en-v1.5或者 multilingual 版本。关键是它的输入维度是 512 个 token，分块时别把块设太大——很多人的检索效果差，就是因为分块大小和嵌入模型的输入上限不匹配。

生成模型这一层，两个选择：一个是通过Groq或Together AI的免费额度调用开源模型 API，速度快、注册就能用；另一个是本地跑量化模型，推荐Qwen2.5-7B-Instruct或Llama-3.1-8B-Instruct的 4bit 量化版。说实话，在学习阶段，这两种方案的生成质量已经足够支撑你做验证了。

这里有个关键的心法跟你说清楚：RAG 的检索质量是天花板，生成模型决定地板。免费模型生成的文字可能偶尔有瑕疵，但只要你的检索链路构建得好，给模型喂进去的都是精准相关的上下文，输出质量就不至于跑偏。这也是为什么这个项目强调全链路跑通——任何一个环节出问题，最终效果都会大打折扣。

3. RAG 核心机制拆解：从“能跑”到“跑得聪明”

动手跑代码之前，先把 RAG 的内部机制弄明白。我看到太多人知其然不知其所以然：代码能跑、答案也能出，但一问到“为什么会这样设计”“换一种分块策略会怎样”，就答不上来了。这一节我用最直白的方式把这套机制讲透。

3.1 索引构建：向量化流程中的关键环节

RAG 的第一阶段是建立索引，通俗讲就是把你的文档库变成可供检索的形式。这个过程里，分块策略是最容易被低估的一环。文档切多大一块直接决定了检索的精度——块太大，每个块包含太多无关信息，召回的片段不聚焦；块太小，一个完整的信息可能被切得稀碎，语义完整性被破坏。我自己测试下来的经验阈值是：使用 bge 系列嵌入模型时，分块大小在 250-450 个 token 之间，重叠设置 50-80 个 token 比较稳妥。这并非拍脑袋定出来的数值，而是兼顾了嵌入模型的输入上限和段落语义完整性之后反复试出来的区间。

嵌入模型会把每一块文本转换成一个高维向量。技术上讲，bge-small 系列输出 512 维向量，bge-base 是 768 维。维度越高理论上表达能力越强，但计算和存储成本也会相应增加。对学习场景来说，512 维的 small 模型是个不错的性价比选择。维度这个东西你先不用深究，把它理解成“模型给每段文本打的一串语义指纹”就行。

向量化完成后，全部向量要放进向量数据库里。学习阶段用 GitHub 上的开源库Chroma或FAISS就够了。这俩的差别简单说：Chroma 更方便、适合交互式学习；FAISS 性能更强、适合需要自己管理索引的场景。实用建议是：Notebook 里用哪个就用哪个，别在这个阶段横向对比纠结工具选型，先把链路跑通才是关键。

3.2 检索链路：Dense Vector Search 与查询改写

检索阶段的核心不是“找到包含相同关键词的文本”，而是“找到语义最接近的文本”。Dense Vector Search 做的事可以类比成一个图书管理员——你描述一个模糊的想法，他不看标题，而是通过语义理解从书架上找出几本该相关的书。

具体实现上，用户查询和文档块都被编码成向量，然后通过余弦相似度计算距离，找到 Top-K 个最相近的文档块。这里的 K 值，直接推荐 3-5 个，给大模型 4 到 6 段上下文是最理想的。K 值太小，模型拿不到足够的信息；K 值太大，噪声增多，反而干扰生成质量。

查询改写是很多人忽视的一环。用户的问题往往是口语化的、模糊的，比如“怎么让检索效果更好”——这种问题直接做向量检索效果并不好。一个实用的做法是先用 LLM 把用户问题改写成一个更具体、更利于检索的查询，再做向量检索。别小看这一点，实测下来检索命中率能提升 10-15 个百分点，而且实现很简单——就是在 RAG 链路的最前面加一个几行代码的改写步骤。

3.3 生成增强：如何把检索结果正确地喂给大模型

检索到的文档块拿到之后，能不能把效果发挥出来，就看你的 Prompt 写得到不到位。RAG 的 Prompt 一般需要明确这几点：角色、任务、可用材料、禁止事项。

实际经验告诉我，Prompt 里这两句最重要：一是明确告诉模型“只能基于提供的材料回答，材料中没有的信息要明确说不知道”；二是要求引用来源——哪怕只是“根据文档第 3 节所述”这种粗粒度的引用，也能在很大程度上抑制模型胡编乱造。这两个约束直接决定了你的 RAG 系统是“可信工具”还是“高级鹦鹉”。

上下文窗口的利用也要讲究。你检索回来的片段可能很长，不可能全部塞进去。常见的做法是对片段做重排序，精挑细选之后再组装 Prompt。我见过太多人把 Top-K 的所有原文一股脑全塞进去，结果上下文爆炸不说，关键信息被淹没在大量无关文本里。更好的做法是：检索回来先粗筛，再用一个 reranker 模型做精排，最后只保留 2-3 个真正高质量的片段。这一步对效果提升非常明显，值得花时间做实验。

4. Agent 构建路线：三条技术路径的选型与实践

Agent 是当之无愧的热词，但“Agent”这个概念已经有点被用滥了。我先把概念收敛一下：在本文语境里，Agent 指的是能够根据用户目标自主规划步骤、调用外部工具、根据工具返回结果调整行动，最终完成复杂任务的 AI 程序。它和单纯的多轮对话不同，关键区别在于“有工具、有计划、有行动”。

4.1 手写 ReAct 循环：理解 Agent 原理的必经之路

想真正理解 Agent，我强烈建议你至少手写一次 ReAct 循环，哪怕之后你会用 LangChain 或 LlamaIndex 这类框架。ReAct 是 Reason + Act 的缩略写法，其思路描述起来并不复杂：给模型当前的任务描述和历史行动轨迹，让它输出下一步的思考，如果要调用工具就输出工具名和参数，然后在下一轮把工具返回的结果再接给它，如此反复直到完成任务。

我自己当初手写 ReAct 循环时，核心的模拟实现大致是这个感觉：

def run_agent(user_query, max_steps=5): messages = [{"role": "user", "content": user_query}] for step in range(max_steps): response = llm.chat(messages) action = parse_action(response) if action["type"] == "finish": return action["answer"] observation = execute_tool(action) messages.append({"role": "assistant", "content": response}) messages.append({"role": "tool", "content": str(observation)}) return "达到最大步数，任务未完成"

这里有个关键点：工具返回结果后，你把 assistant 的思考轨迹和 tool 的观测结果同时放进下一轮的上下文里。模型能据此推理——“我搜到的材料还不够具体，需要再搜一次”或“工具报错了，我换个参数试试”。当模型行程超过最大轮数仍未收敛时，你至少得给用户一个“任务中断”的明确交代，而不是静默失败。模型输出格式的稳定性是你最先会遇到并且必须解决的问题——模型偶尔会不按约定格式输出，你需要写解析逻辑时留好容错空间，或者直接提示模型“请严格输出 JSON”。

4.2 框架选型：LangChain、LlamaIndex 与代码辅助 Agent

手写 ReAct 跑通之后，你就能体会框架的价值了。当前主流的 Agent 框架主要有这几条路线：

LangChain仍然是生态最全的选择。它的 Agent 模块提供了一套完整的抽象——你有 Tool 基类、AgentExecutor、各种内置工具。用它的正确姿势不是去背文档，而是搭好一个最小 Agent 后，去阅读关键模块的源码，弄清楚它内部是怎么维护 MultiInput 的。很多人在 LangChain 里写自定义工具时报错，通常就是对这个内部机制理解不透。

LlamaIndex的优势在于 Agent + RAG 的融合。它的 Agent 可以直接挂载各种数据索引作为工具，这样“先检索再回答”就成了 Agent 的一个工具调用动作。如果你想做一个“能够自主决定何时查知识库、何时调搜索”的知识问答 Agent，LlamaIndex 的 Agent 工作流设计会让你觉得顺手许多。

代码辅助类 Agent也是眼下非常热门的细分方向，这类工具的核心能力是“理解代码库结构 + 检索定位相关代码 + 辅助生成修改建议”。具体实现上，它往往和 RAG 有天然的重合——把代码库切片、嵌入、索引，再结合 Agent 的逻辑来回答提问。你在编译或运行验证过程中若遇到环境层面的异常，优先排查虚拟环境的解释器路径和依赖版本，避免在错误的环境里反复浪费时间。

4.3 Skill、Tool 与 Agent 记忆

关于 Agent 开发，最常被问到的问题有两个：Skill 和 Tool 的区别是什么？Agent 的记忆到底怎么实现？

先说 Skill 和 Tool。Tool 是原子化能力——查天气、发邮件、跑一段代码，每个 Tool 就是一次工具调用；Skill 是完成某个领域任务的整套能力封装——比如“数据分析 Skill”内部可能包含数据加载、清洗、可视化、生成报告多个步骤，可能需要多次调用不同 Tool。更直白的类比：Tool 是你工具箱里的单个工具，Skill 是某个工种的完整工作流程。新手做 Agent 时容易犯的错是，把 Skill 当成 Tool 注册进去，粒度太粗，导致 Agent 无法灵活编排。

再说记忆。Agent 记忆分为短期和长期。短期记忆就是当前对话的上下文，这依赖模型的上下文窗口有限。长期记忆则是把重要信息存储到外部（比如向量数据库、KV 存储），在后续对话中检索召回。实现上不复杂——每轮对话结束后，把用户意图和关键信息压缩成“记忆条目”，用嵌入模型向量化后存库。下次对话时，先从记忆库召回相关条目放进上下文，Agent 就能像“记得你上次说过偏好”一样工作。记忆是一个讲起来简单做起来坑多的机制，你会遇到“记忆污染”（不相关信息干扰 Agent 判断）和“记忆冲突”（新旧记忆矛盾），这些都是后续可以深入研究的工程方向。

5. 端到端实战：跑通一个简历问答 RAG + Agent 项目

理论部分聊得够多了，我直接给一个完整可复现的实战案例。这个项目的目标是：基于一份简历文档，构建一个可以回答“候选人做过什么项目、掌握什么技能”的问答系统，并让 Agent 具备自主调用检索工具的能力。完全免费，全流程大概需要 40-60 分钟跑完。

5.1 数据准备与向量化流程

第一步：准备简历文档。我建议用自己的简历，因为你对内容足够了解，方便验证回答是否正确。把简历保存为 Markdown 或 TXT 格式，内容至少包含工作经历、项目经验、技能清单三个部分。文档不要太大，几千字就好。

第二步：分块与向量化。用 RecursiveCharacterTextSplitter 按层级切分——先按段落切，再按句子补全。关键参数如下：

• chunk_size: 300
• chunk_overlap: 50
• embedding: BAAI/bge-small-zh-v1.5

from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceBgeEmbeddings text_splitter = RecursiveCharacterTextSplitter( chunk_size=300, chunk_overlap=50, separators=["\n\n", "\n", "。", "！", "？", ".", "!", "?", "；", ";"] ) chunks = text_splitter.split_text(resume_text) embedding_model = HuggingFaceBgeEmbeddings( model_name="BAAI/bge-small-zh-v1.5", encode_kwargs={"normalize_embeddings": True} )

这个配置下，一份 2000 字左右的简历大概产生 8-15 个文档块。向量化之后存入 Chroma：

import chromadb from chromadb.utils.embedding_functions import HuggingFaceEmbeddingFunction client = chromadb.PersistentClient(path="./resume_db") collection = client.get_or_create_collection( name="resume", embedding_function=HuggingFaceEmbeddingFunction( model_name="BAAI/bge-small-zh-v1.5" ) ) for i, chunk in enumerate(chunks): collection.add(ids=[str(i)], documents=[chunk])

有一个容易踩的坑必须提醒：如果用了 HuggingFaceBgeEmbeddings 生成向量，又让 Chroma 自己嵌入文本，就可能出现“向量维度和索引维度不匹配”的错误。解决办法就是统一走一条路——要么全部用 LangChain 的 embedding 模型生成向量再入库，要么直接让 Chroma 内置的 embedding function 处理。

5.2 Agent 工具注册与自主检索

索引构建完成后，把“简历检索”封装成一个 Tool 注册给 Agent。这样你的系统就不再是“固定先检索再回答”，而是 Agent 自主判断是否检索、什么时候检索、检索几轮。完整流程示意：

from langchain.agents import Tool, initialize_agent, AgentType def retrieve_resume(query: str) -> str: docs = collection.query(query_texts=[query], n_results=3) return "\n---\n".join(docs["documents"][0]) tools = [ Tool( name="ResumeSearch", func=retrieve_resume, description="检索简历内容。当被问到工作经历、项目经验、技能时使用。" ) ] agent = initialize_agent( tools=tools, llm=llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True ) result = agent.run("这位候选人做过哪些跟 AI 相关的项目？")

这里 Tool 的 description 别敷衍了事。Agent 选择工具靠的主要是模型对 description 的理解，写得模糊会让 Agent 在不需要检索时也调工具，或者在需要时不用。实测经验是：描述里写清楚“什么时候用”比写“能做什么”更重要，核心要传达的是“当用户问题涉及 XX 信息时，使用该工具”。

5.3 效果测评怎么做的经验之谈

跑通了，不代表做完了。很多人的 RAG 项目止步于“能回答几个问题”，但对于真正想把技术吃透的你来说，下一层是关键：建立一套简单的评测方案。

学习阶段不用搞得特别复杂——准备 5-10 个覆盖不同场景的测试问题，从这几个维度做人工评估：

我拿自己的简历做测试时，发现最典型的失败案例是：模型会“合理地胡编”。明明是简历上没有的内容，它因为在你的 Prompt 里看到了“你是 AI 助手”就自动补全了回答。这种情况通过调 Prompt——强化“只基于给定材料回答、信息不足时明确承认”——就能解决大半。补充一点，测评不要只看一两次输出就下结论，同一个问题多跑几轮，因为模型生成有随机性，以多数表现为准。

6. 进阶方向：从基础 RAG 走向 Graph RAG 与 Ontology RAG

基础流程顺手之后，进阶方向已经在你面前展开了，跟当前社区里讨论最热的几个话题直接相关。

Graph RAG解决的是基础 RAG 的一个顽疾——文档块之间的关系。基础 RAG 把文档切成互相独立的块，块与块之间的关联信息丢了。Graph RAG 的做法是提前从文档中抽取实体和关系，构建知识图谱，再把图谱结构注入检索链路。比如“候选人 A 在 X 公司负责 Y 项目”——Graph RAG 不仅知道这三个实体，还知道它们之间的关系。查询时可以直接通过图结构做多跳检索。对文档之间存在大量交叉引用的场景，Graph RAG 的提升非常明显。

Ontology RAG比 Graph RAG 更进一层，它先构建领域本体——用什么概念、通过什么属性链接、节点类型怎么定义。构建本体需要更强的领域建模能力。我个人的建议是先从 Graph RAG 入手，用代码从文档里自动抽取实体关系，跑通之后再考虑 Ontology 的建模设计，不理解底层逻辑就硬上本体，基本都会做成噱头。

Agentic RAG在当下热度最高，其核心转变在于：从“一次检索 + 一次生成”的固定流程，变成 Agent 自行决定怎么检索、检索几次、要不要换个查询词再来一次。这能帮你解决一个问题：用户的复杂问题，拆成多个子问题逐一检索，最后汇总回答。Agentic 的引入，让 RAG 系统从“查询-响应”模式升级为“规划-执行-归纳”模式。

学习进阶路径我建议这样走：

1. 基础 RAG 跑通（向量检索 + 生成）+ 对应评估；
2. 引入查询改写和重排序，针对一个明确的场景把检索质量完全调优；
3. 构建一个含 2-3 个工具的 Agent，工具之一就是 RAG 检索器；
4. 尝试把检索链路改成 Graph RAG；
5. 最后再研究 Agentic RAG——把前面所有能力组合起来。

不建议一上来就凑齐全部酷炫组件：你连基础检索的坏例子都没亲手跑过，直接上 Agentic，遇到问题根本不知道是哪一环出的错。

7. 避坑清单与项目实践心得分享

最后这节纯干货，都是我自己跑过之后总结出来的经验教训。按重要程度排列。

第一，向量化维度统一问题。刚才提过，这里再强调一次，因为它导致的问题非常隐蔽。如果你用 bge 模型生成向量，又把原文本让 Chroma 自己嵌入，程序不会直接报错，但检索结果会非常诡异——相同内容的相似度打分都到不了 0.5。排查思路也简单：手动打印几条 embedding 的维度，无论来自哪个环节都必须一致。

第二，中文分词的坑和 PDF 解析的坑。简历文本里“自然语言处理”这个词，如果分词器拆成了“自然”+“语言”+“处理”，检索“NLP”时可能找不到相关片段。我的解决方案是：在分块时维护一份领域关键词表，匹配到关键词时强制把它们合并成不可分割的短语。更重要的提醒是：能用 Markdown/TXT 就不用 PDF。PDF 解析的格式错乱问题会严重污染嵌入质量——标题、表格、页眉页脚全部混在一起，检索到的片段可读性极差，衍生出大堆无谓的报错时间。

第三，评测优先，优化在后。我的工作习惯是：任何 RAG 项目的第一步不是调参，而是准备测试集。哪怕只有 10 个问题，也要先把“当前基线水平”测出来，再开始动任何一个参数。没有基线，你做的一切修改都无法归因。这是很多业余项目和专业项目之间最根本的分水岭。

第四，版本锁定。Notebook 学习环境最大的坑之一是依赖版本不兼容。我用过的组合里，langchain 0.1.x 与 langchain-community 0.0.x 搭配比较稳定。建议你在环境搭建完成后立刻执行一次离线缓存，把全部依赖打包保存。别小看这一步——哪天 Notebook 重新初始化后安装最新版本，老代码直接跑不起来，届时再逐个排查会很痛苦。锁版本时锁定的是核心依赖（langchain、langsmith、chromadb），其他库让 pip 自动解析依赖关系即可。

第五，别迷信框架，读源码。用 LangChain 搭建 Agent 时，如果只是调包，出了问题根本无从查起。我花了一个晚上通读了 AgentExecutor 的执行源码之后，很多报错一眼就能看出根因。学习阶段，“读源码”是性价比最高的投资，因为框架层为你屏蔽掉的细节，恰恰是你建立系统认知的关键材料。

8. 学习地图：一份可直接执行的 Agent 开发学习路线

顺着前面的思路，我把“零基础到独立开发 RAG/Agent”的路线图整理成下面这份可直接执行的清单，你按顺序推进就好。

学习 Agent 最忌讳的是“贪多求快”。我见过不少人第一周就问“LangGraph 和 LangChain 哪个好”，第二周又问“知识图谱和向量检索怎么结合”……说实话，这些问题的答案在初始阶段对你并不重要——重要的是在跑通一个又一个最小项目之后，你对问题的理解深度自然就提升了。

有一个我反复验证过有效的做法：每学一个新概念，就用你自己的话写一段简短的总结，并且配上刚刚跑通过的代码片段。这种“概念 + 代码”的联结方式，比反复看文档有效得多。等你攒够了 20 个这样的总结片段回看，你会惊讶地发现，自己已经从“跟着别人代码走”进化到“能独立改代码实现想法”了。

另外一个值得现在就开始的习惯：每次实验后顺手记录三个东西——动机（我想验证什么）、配置（参数和模型版本）、结论（效果如何、为什么）。这份实验日志在几天后、几周后都会有效帮你定位问题，也会在面试或汇报时成为扎实的素材积累。

做 Agent 开发，这条路上没有“学完”的终点。你今天搭好的简历问答 Agent，往后可以扩展成能帮你整理邮件、管理日程、搜索论文的私人助手。技术栈和框架演进迭代极快，但底层的系统思维和解决实际问题的能力是通用的。希望这份经验总结，能让你少走一些弯路，把精力真正花在理解技术和解决问题上。