用Jupyter Notebook快速跑通RAG全流程：原理、指标与工程实践

最近如果你在接触知识库问答、私有文档问答或者大模型应用落地，大概绕不开 RAG。但一个常见的尴尬是：文章看了不少，术语记住了几个，比如“向量化”“召回”“重排”，真要动手跑通一条完整链路，却发现文档加载、切分、向量化、检索、提示词拼接，任何一个环节都能卡上大半天。

RAG Refresher Notebook 这个方向的名字其实已经说明了意图——它不是让你从零啃完一整门理论课，而是用 Jupyter Notebook 这种适合探索和演示的形式，把 RAG 的核心环节快速重跑一遍，在文档加载、分块、向量化、检索、生成、评估这条链路上找回手感。对正在做技术选型、需要评估 RAG 效果，或者想给团队一个可运行演示的开发者来说，这种“刷新式”复盘比刷文章有效率得多。

这篇文章会从一个偏工程实践的视角拆解 RAG：先讲清楚核心原理，再说明知识库常见指标怎么看，接着给出一个基于 Jupyter Notebook 的最小可运行示例，最后补上常见问题、排查思路和最佳实践。读完你不仅能跑通一个 RAG 例子，还能知道怎么判断它到底好不好用。

1. 这篇文章真正要解决的问题

1.1 为什么需要一次“RAG 刷新”

RAG 这个概念在最近一两年里快速膨胀：GraphRAG、Agentic RAG、多模态 RAG、RAG 评测体系，几乎每隔一段时间就冒出新的变体。新概念越多，反而让“老老实实把基础链路跑通”这件事显得更有价值。因为不管 RAG 演化成什么形态，文档解析、分块、向量化、召回、重排、生成、评测这些基础操作并没有消失，只是组合方式越来越复杂。

很多人的问题并不是不了解 RAG 的定义，而是没有一个能稳定复现的“最小实验台”。比如有人以为 RAG 的核心就是把 PDF 丢进向量库，真正调一轮之后会发现，检索质量往往决定了整个 RAG 的效果上限。切分参数调得不好，检索结果里就会混进大量无关片段；检索结果质量差，后面生成再强也救不回来。因此，用 Notebook 把整条链路重新走一遍，不只是学习，更是一次知识校准和工程能力复盘。

1.2 哪些读者适合读这篇文章

如果你属于下面某类情况，这篇文章会比较贴合你的需求：

• 准备在项目里引入 RAG 做知识库问答，但还没有跑通最小流程；
• 已经跑通过一个简单 RAG 示例，但不知道如何量化评估检索和生成质量；
• 平时习惯用 Jupyter Notebook 做算法实验，想把 RAG 实验也纳入同一套工作流；
• 需要给团队做一次 RAG 分享，希望有一个完整且带代码的演示框架。

如果你已经是专门做检索优化的资深工程师，这篇文章在概念层面的帮助有限，但其中关于评估指标和工程实践的整理，也可以当作一次快速回顾。

2. RAG 是什么：不只是“查资料让模型回答”

2.1 通俗解释与技术定义

RAG 全称 Retrieval-Augmented Generation，中文可以叫检索增强生成。通俗地说，就是让大模型在回答之前，先从外部知识库里检索相关资料，再把“资料 + 问题”一起交给模型，让模型基于这些资料生成答案。

从技术链路看，RAG 通常由三部分组成：

• 索引（Indexing）：把文档加载进来，切分成合适的片段，做向量化，写入向量数据库或其他检索源。
• 检索（Retrieval）：根据用户问题，从索引中找到最相关的文档片段。
• 生成（Generation）：把检索到的片段作为上下文，与用户问题一起交给大模型，生成最终回复。

传统大模型只能依赖训练时习得的参数知识，问题很明显：知识有截止时间、可能记错、也可能根本没有。RAG 通过实时检索把回答建立在“最新、最相关的外部资料”之上，一方面缓解模型幻觉，另一方面让回答可以追溯到具体来源，这对企业级知识库问答几乎是一种刚需。

2.2 RAG 与微调的区别

不少项目在确定技术方案时都会纠结一个问题：到底是做 RAG，还是做微调。这两种方式并不互斥，适用场景不同。

在实际项目中，更常见的做法是先用 RAG 解决知识来源问题，再针对业务场景微调模型或专用 embedding 模型，让两者配合而不是互斥。

2.3 RAG 的演进方向

在基础 RAG 之上，近一年出现了不少变体：

• Agentic RAG：把检索过程交给智能体，由模型自主决定是否检索、检索几次、是否需要重写查询。
• GraphRAG：把文档解析成实体和关系图，除了向量检索之外，还能做多跳推理。
• 多模态 RAG：不仅检索文本，还能检索图片、表格、扫描件等。

这些方向看似新鲜，但底层依然是“建立索引、召回候选、重排、生成”这套框架。理解了基础链路，再往这些方向扩展会顺利很多。

3. RAG 知识库的核心指标：怎么看、怎么用

3.1 检索侧指标

RAG 质量的第一步是检索质量。如果检索返回的片段与问题无关，后面的生成环节做得再精细也没有意义。常用指标有以下几种。

Recall@K

表示从全部相关文档中，Top-K 结果到底召回了多少个相关文档。公式可以简单理解为：

Recall@K = Top-K 中相关文档数 / 全部相关文档数

这个指标关心的是“相关文档有没有被找回来”。在知识库问题里，通常你会先构建一个带标准答案的测试集，然后跑检索，统计 Recall@K。

Hit Rate

看 Top-K 结果中是否出现了包含正确答案的片段，命中记为 1，未命中记为 0，然后对多条测试问题求平均。相比 Recall，Hit Rate 更直观：用户问一个问题，系统有没有把可能答对的素材找出来。

MRR（Mean Reciprocal Rank）

MRR 更关注“第一个正确结果出现的位置”。假设测试了 3 个问题，第一个问题的正确答案出现在第 1 位，第二个出现在第 3 位，第三个没有出现在 top-10 中，那么 MRR 大约为（1 + 1/3 + 0）/ 3 = 0.44。MRR 越高，说明系统越能尽快把最相关的片段排到前面。

NDCG（Normalized Discounted Cumulative Gain）

NDCG 在召回的基础上多考虑了排序质量。它会根据相关文档所在的位置做位置折损：相关的文档排得越靠前，得分越高，并且会做归一化，方便不同查询之间比较。这个指标适合评估“重排之后的效果是否真的变好了”。

Precision@K

表示 Top-K 结果中真正相关的文档占比。Precision 高意味着检索结果里噪声少，但有可能漏掉了一些相关文档。在问答场景里，Precision 和 Recall 往往需要权衡。

用一个例子来说明。假设你问“RAG 的索引流程是什么”，知识库里共有 5 篇相关文档。系统返回 10 个片段，其中 3 篇相关且排在前 3 位。那么：

• Recall@10 = 3 / 5 = 0.6
• Precision@10 = 3 / 10 = 0.3
• MRR = 1 / 3 ≈ 0.33

如果系统把 3 篇相关文档都排在最前面，MRR 就会是 1。这也是为什么在检索调试阶段，不要只看 Recall，还要看排序质量。

3.2 生成侧指标

检索质量之外，还需要关注生成质量。RAG 的生成侧指标通常围绕“回答是否忠于检索内容”展开。

Faithfulness（忠实度）

判断模型生成的回答是否完全基于检索到的上下文，有没有把上下文之外的信息当成事实输出。如果模型把输入上下文没有提到的细节补充进去，很可能就是幻觉。

Answer Relevance（答案相关性）

衡量用户问题与模型答案之间的相关程度。即使答案正确，如果答非所问，这个指标分数也会偏低。

Context Relevance（上下文相关性）

衡量检索到的上下文与用户问题的相关程度。注意，这个指标本质上还是在检验检索阶段，只是由评判模型来打分。

生成侧指标通常需要另一个大模型来打分，这也是 RAGAS 这类评测框架流行的原因。如果你不想引入额外框架，也可以在自己维护的评测集上，让评判模型给每个回答打一个 1 到 5 分，并附上理由，然后人工抽检。

3.3 业务与工程指标

除了质量和排序，工程上还必须关注延迟和成本。

在实际优化时，我建议先关注检索侧指标，比如 Hit Rate 和 Recall@K。只有当检索效果基本稳定后，再投入精力做生成提示词调优和 Token 成本优化，否则很容易出现“检索结果一团糟，却还在反复改提示词”的低效循环。

4. 为什么 Notebook 适合 RAG 实践

4.1 Notebook 与脚本的差异

RAG 开发本质上是一个探索性过程：切分参数需要反复试，检索结果需要随时看，提示词模板需要不断调整。如果用传统脚本做这件事，每次修改都要重新跑整条链路，中间过程很难保留。Jupyter Notebook 支持分单元格执行、保留中间变量、可视化打印结果，这让调试体验变得非常直接。

举个例子：你修改了一个chunk_size参数，希望在重新切分前先看一下上一轮的切分效果。Notebook 里可以在一个单元格里打印出前几个片段，确认切分粒度之后再继续执行下一步。脚本里当然也能打印，但它没有“停留在某个中间状态继续交互”的天然优势。

4.2 JupyterLab 与经典 Notebook 怎么选

不少新手会在 JupyterLab 和经典 Jupyter Notebook 之间犹豫。如果把 RAG 实验纳入日常开发，JupyterLab 通常更合适。

如果你用经典 Notebook，想在侧边栏显示标题总览，通常需要安装jupyter_contrib_nbextensions，然后在扩展中启用 Table of Contents。JupyterLab 则直接使用左侧的 Table of Contents 面板，不需要额外配置。

5. 环境准备与前置条件

5.1 创建 Python 虚拟环境

建议使用 Python 3.10 或 3.11。版本需要以安装的依赖库要求为准，不要盲目使用最新版，也不要停留在过旧版本。这里以 conda 为例。

conda create -n rag-notebook python=3.10 -y conda activate rag-notebook

也可以使用 venv，本质区别不大，关键是隔离环境，避免污染全局 Python。

5.2 安装 JupyterLab 与 RAG 依赖

pip install jupyterlab pip install langchain langchain-community langchain-openai langchain-text-splitters pip install chromadb sentence-transformers

说明几点：

• 如果你暂时不打算调用 OpenAI 接口，langchain-openai可以先不装，但后面的生成示例需要根据自身情况调整。
• 不同 LangChain 版本的导入路径存在差异，如果你用的是较老版本，代码里的langchain_community可能需要改成langchain下的对应模块。
• sentence-transformers首次使用时会下载 embedding 模型权重。如果下载缓慢，可以检查网络连通性或换成可用的镜像源，这属于环境问题而不是代码问题。

5.3 推荐的项目目录结构

一个可复用的 RAG 实验台，建议按下面的方式组织：

rag-refresher-notebook/ ├── data/ │ └── sample_doc.md ├── notebooks/ │ ├── 01-document-loading.ipynb │ ├── 02-rag-pipeline.ipynb │ └── 03-evaluation.ipynb └── requirements.txt

把数据、实验笔记本、依赖清单分开，好处是每个部分都可以独立替换。后续如果要换一批文档做测试，只需要替换data目录下的内容，不需要重写 Notebook。

6. 用 Notebook 跑通 RAG：完整示例

下面用一个最小的中文示例，把 RAG 全流程走一遍。示例中会用到：

• TextLoader：加载本地文本文件；
• RecursiveCharacterTextSplitter：切分文档；
• HuggingFaceEmbeddings：本地向量化，不需要外部 API；
• Chroma：本地向量库；
• ChatOpenAI：生成模型，需要配置 API Key，如果没有也可以先只看检索部分。

6.1 准备一份示例文档

在data/sample_doc.md中放入一段关于 RAG 的介绍文本，比如：

# RAG 简介 RAG，全称 Retrieval-Augmented Generation，检索增强生成。 它的核心思想是在大模型回答之前，先从外部知识库检索相关资料， 再把资料与用户问题一起交给模型生成回答。 RAG 主要由索引、检索、生成三部分组成。 索引阶段负责将文档切分、向量化并写入向量数据库； 检索阶段根据用户问题召回相关片段； 生成阶段利用检索到的上下文和用户问题生成最终答案。 RAG 的优点是知识更新快、答案可追溯、幻觉相对可控。 它的挑战在于检索质量直接影响生成效果，因此切分策略、 向量模型选择和重排策略都很重要。

这段内容不长，但足以演示完整流程。

6.2 文档加载与切分

在 Notebook 中新建一个单元格，执行以下代码：

# 文件路径：notebooks/01-document-loading.ipynb from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter loader = TextLoader("../data/sample_doc.md", encoding="utf-8") documents = loader.load() splitter = RecursiveCharacterTextSplitter( chunk_size=100, chunk_overlap=20, separators=["\n\n", "\n", "。", "！", "？", " ", ""], ) chunks = splitter.split_documents(documents) print(f"原始文档数: {len(documents)}") print(f"切分后片段数: {len(chunks)}")

这段代码里，chunk_size=100表示每个片段尽量控制在 100 个字符左右，chunk_overlap=20表示相邻片段之间保留 20 个字符的重叠，目的是减少切分导致的信息断层。

这里真正容易踩坑的地方是分隔符。中文文本不像英文那样天然按空格分单词，如果分隔符只写\n\n，长段落会被硬切出一个很长的Text对象，效果可能很糟糕。所以示例中加入了中文标点作为分隔符，实际项目中建议根据文档结构来调整分隔符顺序。

6.3 向量化并写入向量库

继续新建单元格，执行：

# 文件路径：notebooks/02-rag-pipeline.ipynb from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 中文场景可以换成 BAAI/bge-small-zh-v1.5 embeddings = HuggingFaceEmbeddings( model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" ) vectorstore = Chroma.from_documents( chunks, embeddings, persist_directory="../chroma_db", ) retriever = vectorstore.as_retriever(search_kwargs={"k": 3}) print("向量库构建完成")

这里比较关键的是 embedding 模型的选择。如果语料以中文为主，建议优先试试BAAI/bge-small-zh-v1.5这类中文优化过的模型，检索效果通常比通用的多语言模型更好。不过模型体积和推理速度也需要考虑。

Chroma会默认在本地持久化数据，指定persist_directory后，后续重启 Notebook 可以直接加载已有向量库，不必每次重新嵌入，节省大量时间。

6.4 检索测试

先不接生成链路，直接测试检索效果：

# 文件路径：notebooks/02-rag-pipeline.ipynb query = "RAG 主要由哪些部分组成？" docs = retriever.invoke(query) for i, doc in enumerate(docs): print(f"[{i + 1}] {doc.page_content}") print("---")

在这一步，你应该能看到与查询相关的片段被召回。如果返回结果明显不相关，优先检查切分参数和 embedding 模型，而不是继续改生成提示词。

6.5 接入生成链路

生成部分以 OpenAI 兼容接口为例。如果你没有 API Key，可以先用上面检索到的片段人工判断效果，或者使用本地可用的生成模型。

# 文件路径：notebooks/02-rag-pipeline.ipynb import os from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough # 建议通过环境变量设置，不要硬编码密钥 os.environ["OPENAI_API_KEY"] = "your-api-key" llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2) prompt = ChatPromptTemplate.from_template( """你是一个严谨的问答助手。请只依据下面的上下文回答问题。 如果上下文中没有足够信息，请直接回答“我不知道”，不要编造。 上下文： {context} 问题： {question} """ ) def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs) rag_chain = ( {"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() ) answer = rag_chain.invoke("RAG 主要由哪些部分组成？") print(answer)

这段代码做了几件事：

• 用系统提示强制模型只能依据上下文回答，降低幻觉风险；
• 通过format_docs将多个检索片段拼接成一段上下文；
• 用RunnablePassthrough把用户问题原样传递给后续链路；
• 最终得到模型生成的回答。

提示词里的约束不是银弹。即使提示词写得再严格，一旦检索片段不相关，模型生成内容依然不可靠。所以前面反复强调：先确保检索质量，再考虑生成优化。

6.6 把流程串成可复用实验台

上面的代码完成之后，你可以把“加载、切分、向量化、检索、生成”整体封装进一个函数，方便后续换文档、换问题做测试。一个简单的做法是在同一个 Notebook 中定义：

# 文件路径：notebooks/02-rag-pipeline.ipynb def ask_rag(question: str, top_k: int = 3): docs = retriever.invoke(question, search_kwargs={"k": top_k}) context = format_docs(docs) answer = (prompt | llm | StrOutputParser()).invoke( {"context": context, "question": question} ) return answer, [d.page_content for d in docs] question = "RAG 有哪些优点？" answer, retrieved = ask_rag(question) print("回答：", answer) print("\n检索到的片段：") for i, content in enumerate(retrieved): print(f"[{i + 1}] {content[:80]}")

这样，后续每次测试只需要调用ask_rag，并且能把“检索到的片段”和“最终回答”放在一起看，快速定位问题是出在检索还是生成。

7. 运行结果与效果验证

7.1 期望输出

运行切分代码后，预期看到类似这样的输出：

原始文档数: 1 切分后片段数: 5

运行检索代码后，预期看到与问题相关的多个片段。运行生成链路后，期望输出一个基于上下文的回答，例如：

RAG 主要由索引、检索和生成三部分组成。

具体内容取决于示例文档和模型，但判断标准是：回答内容确实来自你提供的文档，而不是 GPT 模型自己“想到”的扩展内容。

7.2 如何判断是否成功

成功与否可以从三个层面判断：

1. 流程层：没有报错，能输出检索片段和最终回答；
2. 相关层：检索到的片段与用户问题明显相关；
3. 忠实层：生成回答只使用了检索上下文中的信息，没有新增文档之外的事实。

这三个层面不是并列关系，而是递进关系。只要流程通了，但其实检索结果不相关，那说明流程只是“跑通了”，还没到“可用”的程度。

7.3 失败时先看哪里

如果运行失败，不要急着搜完整报错信息，先按顺序排查：

• 查看是否是导入路径错误，不同 LangChain 版本对langchain_community和langchain_openai的兼容性不同；
• 确认是否缺少依赖包，比如sentence-transformers没有安装成功；
• 确认 embedding 模型是否成功下载，模型文件不完整会报加载错误；
• 如果使用了 OpenAI 接口，确认 API Key 是否有效、网络能否正常访问对应服务。

8. 常见问题与排查思路

下面整理了一些 Notebook + RAG 实践中比较常见的问题。

9. 最佳实践与工程建议

9.1 从可控的小文档开始

第一次做 RAG，不要直接拿几千页的 PDF 测试。建议先用几篇结构化良好的 Markdown 文档跑通流程，确认切分和检索效果，再逐步扩大文档规模。小文档排错容易，能更快建立对 RAG 的直觉。

9.2 分块策略是检索质量的基础

分块没有绝对的最优参数，需要根据文档结构、语义密度和实际检索效果调整。可以尝试的方法包括：

• 先按文档已有的标题、章节、段落切分，再考虑固定字符长度切分；
• 适当增加chunk_overlap，减少跨段信息被切断的概率；
• 对代码、表格、扫描件等特殊内容，选择不同的解析方式。

如果一个切分策略导致检索结果不稳定，不要急着调生成提示词，先回头检查切分结果。

9.3 embedding 模型选择要结合语言和场景

中文场景建议优先尝试中文优化过的模型，例如BAAI/bge-small-zh-v1.5这类。英文场景则有多种通用模型可选。也可以把多个 embedding 模型在同一个小测试集上做 recall 对比，用数据决定选型，而不是凭感觉。

9.4 检索优化可以分阶段做

当文档规模变大或检索结果不够精准时，可以按下面顺序迭代：

• 增加召回数量，比如top_k从 3 调到 10；
• 引入重排模型，对召回结果做二次排序；
• 尝试多路召回，比如“关键词检索 + 向量检索”融合；
• 对用户问题做改写，让检索语句更接近文档表述。

9.5 安全与权限不能省

把企业文档接入 RAG 之前，必须确认文档可以合法、合规地被用于该场景。涉及权限的内容要做好访问控制，避免向量库成为新的数据泄露点。API Key 等敏感信息不要直接写在 Notebook 里，尽量通过环境变量或密钥管理服务注入。

9.6 实验环境与生产环境分离

Notebook 适合做实验、验证想法和演示，但不适合直接当作生产服务。生产环境一般需要把向量检索和生成模块服务化，做接口封装、日志采集、并发控制和监控告警。Notebook 里调通的流程，可以作为生产模块的设计原型，而不是生产实现本身。

10. 总结与后续学习方向

这篇文章从 RAG 的基础原理出发，讲清楚了它和微调的区别，介绍了知识库检索和生成的关键指标，并给出了一个基于 Jupyter Notebook 的最小可运行示例。整条链路下来，你应该已经能理解：RAG 不只是一个“给模型加检索”的简单概念，它的效果受切分、向量化、检索、重排、提示词等多个环节共同影响，其中检索质量是最容易成为瓶颈、也最值得优先优化的部分。

下一步值得继续深入的方向包括：用 RAGAS 等评测框架搭建体系化评估基线；尝试在召回结果上加入重排模型；研究 Faster RAG 的工程优化手段；如果你的场景是多跳推理或复杂关系问答，可以关注 GraphRAG 与 Agentic RAG 的适用边界。多模态 RAG 也是一个值得留意的方向，尤其是文档里包含图片、表格和扫描件时，只做纯文本检索往往不够。

实践上，建议把刚才这个 Notebook 打造成一个可复用的实验台：换文档、换 embedding 模型、换切分参数，都在这套流程上做对比。先跑通，再量化，最后再上生产，这条路对于绝大多数 RAG 项目来说，比直接追求复杂架构要稳妥得多。