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 的部署时间参考环境项操作预计耗时连接 Colab 运行时选择 T4 GPU1-2 分钟安装依赖pip 安装相关库3-5 分钟下载嵌入模型从 HuggingFace 拉取3-8 分钟下载开源 LLM4bit 量化模型5-15 分钟构建向量索引1000 段文本左右1-3 分钟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_steps5): 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 的一个工具调用动作。如果你想做一个“能够自主决定何时查知识库、何时调搜索”的知识问答 AgentLlamaIndex 的 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: 300chunk_overlap: 50embedding: BAAI/bge-small-zh-v1.5from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceBgeEmbeddings text_splitter RecursiveCharacterTextSplitter( chunk_size300, chunk_overlap50, separators[\n\n, \n, 。, , , ., !, ?, , ;] ) chunks text_splitter.split_text(resume_text) embedding_model HuggingFaceBgeEmbeddings( model_nameBAAI/bge-small-zh-v1.5, encode_kwargs{normalize_embeddings: True} )这个配置下一份 2000 字左右的简历大概产生 8-15 个文档块。向量化之后存入 Chromaimport chromadb from chromadb.utils.embedding_functions import HuggingFaceEmbeddingFunction client chromadb.PersistentClient(path./resume_db) collection client.get_or_create_collection( nameresume, embedding_functionHuggingFaceEmbeddingFunction( model_nameBAAI/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_results3) return \n---\n.join(docs[documents][0]) tools [ Tool( nameResumeSearch, funcretrieve_resume, description检索简历内容。当被问到工作经历、项目经验、技能时使用。 ) ] agent initialize_agent( toolstools, llmllm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue ) result agent.run(这位候选人做过哪些跟 AI 相关的项目)这里 Tool 的 description 别敷衍了事。Agent 选择工具靠的主要是模型对 description 的理解写得模糊会让 Agent 在不需要检索时也调工具或者在需要时不用。实测经验是描述里写清楚“什么时候用”比写“能做什么”更重要核心要传达的是“当用户问题涉及 XX 信息时使用该工具”。5.3 效果测评怎么做的经验之谈跑通了不代表做完了。很多人的 RAG 项目止步于“能回答几个问题”但对于真正想把技术吃透的你来说下一层是关键建立一套简单的评测方案。学习阶段不用搞得特别复杂——准备 5-10 个覆盖不同场景的测试问题从这几个维度做人工评估维度评分标准典型问题示例回答正确性是否与简历事实一致候选人工作了几年回答完整性是否覆盖简历中所有相关点项目经历有哪些检索相关性召回片段是否命中关键信息问“AI 项目”时是否召回包含“AI”的段落拒答能力材料中没有的信息是否如实拒绝问简历外的事情时是否明确说不知道我拿自己的简历做测试时发现最典型的失败案例是模型会“合理地胡编”。明明是简历上没有的内容它因为在你的 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 系统从“查询-响应”模式升级为“规划-执行-归纳”模式。学习进阶路径我建议这样走基础 RAG 跑通向量检索 生成 对应评估引入查询改写和重排序针对一个明确的场景把检索质量完全调优构建一个含 2-3 个工具的 Agent工具之一就是 RAG 检索器尝试把检索链路改成 Graph RAG最后再研究 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”的路线图整理成下面这份可直接执行的清单你按顺序推进就好。阶段学习内容预期耗时产出物第一阶段Python 基础机器学习原理2-3 周能用 Python 处理文本数据第二阶段LLM API 调用与 Prompt 工程1-2 周学会设计结构化 Prompt第三阶段向量化与向量数据库1 周跑通一个最小 RAG Demo第四阶段RAG 进阶检索调优 评测2 周用 10 个测试问题建立评测基线第五阶段Agent 基础ReAct 工具调用2 周手写一个 ReAct 循环第六阶段Agent 框架实战2 周用 LangChain 做一个带工具的 Agent第七阶段进阶方向Graph RAG / Agentic3-4 周完成一个综合性项目学习 Agent 最忌讳的是“贪多求快”。我见过不少人第一周就问“LangGraph 和 LangChain 哪个好”第二周又问“知识图谱和向量检索怎么结合”……说实话这些问题的答案在初始阶段对你并不重要——重要的是在跑通一个又一个最小项目之后你对问题的理解深度自然就提升了。有一个我反复验证过有效的做法每学一个新概念就用你自己的话写一段简短的总结并且配上刚刚跑通过的代码片段。这种“概念 代码”的联结方式比反复看文档有效得多。等你攒够了 20 个这样的总结片段回看你会惊讶地发现自己已经从“跟着别人代码走”进化到“能独立改代码实现想法”了。另外一个值得现在就开始的习惯每次实验后顺手记录三个东西——动机我想验证什么、配置参数和模型版本、结论效果如何、为什么。这份实验日志在几天后、几周后都会有效帮你定位问题也会在面试或汇报时成为扎实的素材积累。做 Agent 开发这条路上没有“学完”的终点。你今天搭好的简历问答 Agent往后可以扩展成能帮你整理邮件、管理日程、搜索论文的私人助手。技术栈和框架演进迭代极快但底层的系统思维和解决实际问题的能力是通用的。希望这份经验总结能让你少走一些弯路把精力真正花在理解技术和解决问题上。