基于Notebook的RAG实战指南：从零搭建检索增强生成知识库

有不少读者问我：想看一个能把 RAG 从零跑通的 Notebook 项目，而不是只看概念图。RAG 刚火的时候，大家关注的是“它是什么”，现在更多人关注的是“我的文档放进去，怎么才能真的搜得准、答得对”。

这篇文章就围绕一个RAG Refresher Notebook来展开。我会先讲清楚 RAG 的核心链路，再带你用一个 Jupyter Notebook 把整套流程完整跑一遍，包括文档加载、文本切分、向量化、检索、重排、生成回答。最后还会补充知识库指标的理解方式、常见报错排查，以及让 RAG 更精准的工程经验。

不管你是刚接触 RAG 的新手，还是已经搭过 demo 但效果不理想的开发者，这份笔记都值得收藏对照实践。

1. 为什么要用 Notebook 复现 RAG

1.1 RAG 是什么，解决什么问题

RAG 全称是 Retrieval-Augmented Generation，也就是“检索增强生成”。

通俗地说，大语言模型本身的知识有截止时间，也不知道你私有的业务文档。RAG 的思路是：在模型回答之前，先从你的知识库里把相关片段检索出来，再把这些片段和用户问题一起交给大模型，让模型基于检索到的内容组织答案。

典型流程如下：

用户问题 -> 文本向量化 -> 向量库检索 -> 召回相关片段 -> 拼接提示词 -> 大模型生成回答

RAG 解决的核心问题是：

• 模型不知道你公司的制度、产品手册、私有 PDF 内容。
• 模型知识有截止日期，无法回答最新信息。
• 模型容易“一本正经地胡说八道”，RAG 用检索结果约束答案来源。
• 相比重新训练模型，RAG 更新知识成本低得多，换一个文档就能更新知识。

1.2 为什么 Notebook 是复现 RAG 的好工具

Jupyter Notebook 最大的特点是“按单元格运行、结果留在页面里”。这对 RAG 学习非常有帮助。

举例来说：

• 加载完文档后，你可以立刻打印前 500 个字，确认文档读对了。
• 切分完文本后，可以打印几个 chunk，看切得是否合理。
• 检索之后，可以把命中的文本打出来，人工判断“召回结果到底准不准”。
• 最后再调用大模型生成回答，整个过程是透明的，每一步都能看到中间结果。

这种“逐步可视化”的调试方式，比直接写一个.py脚本跑完要好理解得多。所以我一直建议，做 RAG 原型验证阶段，优先用 Notebook，跑通了再工程化封装成服务。

1.3 这份 Notebook 会带你完成什么

这份RAG Refresher Notebook的目标不是做一个生产级系统，而是帮你把 RAG 的完整链路亲手实现一遍。

完成之后，你将掌握：

• 文档加载与解析的常见方式。
• 文本切分的原理和参数含义。
• 使用开源 Embedding 模型做向量化。
• 使用 Chroma 作为本地向量库。
• 实现向量检索与简单的重排逻辑。
• 调用大模型生成最终回答。
• 理解 RAG 知识库评估指标。

2. 环境准备与工具链

2.1 Anaconda、Jupyter Notebook 和 Lab 怎么选

做 Python 数据类开发，Anaconda 是目前最省心的发行版。安装 Anaconda 后，自带的conda可以方便地创建虚拟环境。

很多新手会问：Jupyter Notebook 和 JupyterLab 到底有什么区别？

简单来说：

• Jupyter Notebook 是经典的单文档交互界面，适合逐格运行代码。
• JupyterLab 是新一代 IDE 风格界面，支持多标签、拖拽文件、终端、文件管理，功能更全面。
• 两者底层内核一样，代码、.ipynb文件互相兼容。

如果你只是打开一个.ipynb快速运行，Notebook 够了。如果你要同时看文档、调代码、开终端，更推荐 JupyterLab。

在 Anaconda Prompt 中启动命令如下：

# 启动 Jupyter Notebook jupyter notebook # 启动 JupyterLab jupyter lab

2.2 创建虚拟环境并安装依赖

建议为 RAG 项目单独创建一个虚拟环境，避免依赖冲突。

conda create -n rag_notebook python=3.10 -y conda activate rag_notebook

然后安装依赖。这里需要注意版本，本示例以常见稳定版本为例，不同版本 API 可能有差异，请以你安装后的实际版本为准。

pip install jupyter pip install langchain langchain-community langchain-text-splitters langchain-huggingface pip install chromadb sentence-transformers pip install python-docx pypdf unstructured pip install openai

如果你的网络较慢，建议使用国内镜像源安装，例如：

pip install langchain chromadb sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3 Notebook 侧边栏标题总览

长 Notebook 写完后，右侧的“目录 / 大纲”视图非常有用。JupyterLab 默认有“Table of Contents”插件，可以点击左侧目录图标查看所有 Markdown 标题。

如果你使用的是 Jupyter Notebook 7，打开 Notebook 后，在视图菜单中开启“Show Table of Contents”即可。这样你可以像看文章目录一样，快速跳转到不同章节。

3. RAG 核心链路拆解

在写代码之前，先把 RAG 的每个环节拆开讲清楚。理解了每个环节的作用，后面看代码才不会晕。

3.1 文档加载与解析

RAG 的第一步是读取文档。文档可能是 PDF、Word、Markdown、HTML 或纯文本，不同格式需要不同的解析器。

常见文档加载器如下：

这里最常见的坑是：PDF 解析出来的文本可能丢失结构。比如一份带标题层级、表格、多栏排版的 PDF，用 PyPDF 直接抽取，结果可能是混乱的。

如果你的文档是合同、技术规范等强结构文档，建议优先使用保留了标题结构的信息源。例如先把 PDF 转成 Markdown，或者使用 Unstructured 这类保留更多结构的工具。

3.2 文本切分

切分是为了让模型只关注相关片段。如果整篇文档都塞给模型，会超出上下文限制，也会引入大量噪声。

最常用的是递归字符切分器RecursiveCharacterTextSplitter。它的策略是：先用一个大的分隔符切，如果切出来的块还是太长，就换更小的分隔符继续切。

核心参数：

• chunk_size：每个块的最大字符数。
• chunk_overlap：相邻块之间的重叠字符数，避免关键信息正好被切在边界上。

举个例子：

from langchain_text_splitters import RecursiveCharacterTextSplitter text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", "！", "？", " ", ""] )

需要注意的是：中文的切分和英文不太一样。英文可以按空格切，中文更适合按句号、感叹号、问号等句子边界切。上面把中文标点加进了 separators，就是为了减少句子被硬切的风险。

3.3 向量化与向量库

向量化的作用是让文本变成计算机能计算相似度的数字数组。

你可以把 Embedding 模型理解为“翻译官”：它把一段文本映射成一个高维向量，语义相近的文本，向量距离也近。

常用的本地 Embedding 模型：

• BAAI/bge-small-zh-v1.5
• BAAI/bge-m3
• shibing624/text2vec-base-chinese

使用开源模型的好处是数据不出内网，适合企业私有化场景。缺点是中文效果需要测试，不同模型差距很大。

在 Notebook 中加载 HuggingFace Embedding 模型：

from langchain_huggingface import HuggingFaceEmbeddings embeddings = HuggingFaceEmbeddings( model_name="BAAI/bge-small-zh-v1.5", encode_kwargs={"normalize_embeddings": True} )

normalize_embeddings=True表示对向量做归一化。归一化之后，用内积计算相似度等价于余弦相似度，这在用 Chroma 检索时更稳定。

向量库的作用是存储向量并提供相似度检索。Chroma 是一个非常适合做原型验证的轻量级向量库，支持本地持久化，不需要额外启动服务。

3.4 检索与重排

检索阶段，系统把用户问题也转成向量，然后在向量库中找到最相似的 Top K 个片段。

但向量检索不一定完美。可能出现两种问题：

• 召回结果语义相关，但关键信息缺失。
• 召回结果顺序不合理，真正有用的片段排在了后面。

这时候就需要重排（Rerank）。重排模型会结合“用户问题 + 候选文档”做更精细的匹配打分，把最相关的片段提到前面。

常见的重排模型有BAAI/bge-reranker-base、bge-reranker-v2-m3等。

3.5 生成回答

最后一步是把检索到的文档片段和用户问题拼接成 Prompt，交给大模型。

一个简洁的 Prompt 模板如下：

你是一个知识库问答助手。请仅根据以下资料回答问题。 如果资料里没有相关内容，请直接回答“知识库中未找到相关信息”。 资料： {context} 问题：{question}

这里要注意：不要给模型太多自由发挥的空间。RAG 的核心价值是“有依据地回答”，如果 Prompt 中没有强调“仅根据资料回答”，模型很可能又用训练知识自由发挥，导致回答“看起来对但没依据”。

4. 完整实战：用 Notebook 搭建一个最小 RAG

下面我们会走进一个完整的 Notebook。建议你在本地按顺序创建新单元格运行，而不是一次性粘贴全部代码。

4.1 项目结构与准备数据

建议的项目目录如下：

rag_refresher_notebook/ ├── data/ │ └── rag_intro.txt ├── rag_refresher.ipynb └── requirements.txt

先手动创建一个data/rag_intro.txt，内容可以用你自己关心的文档，也可以先用下面的示例文本。我这里用一段非常短的 RAG 介绍举例，实际使用时换成你自己的业务文档即可。

RAG 全称是 Retrieval-Augmented Generation，即检索增强生成。 它的核心思想是在大语言模型生成回答之前，先从外部知识库中检索相关文本片段。 检索到的片段会和用户问题一起拼接到提示词中，用于约束模型回答的内容和范围。 RAG 适合解决私有知识问答、企业制度问答、产品手册问答等场景。 与重新训练模型相比，RAG 的优势是更新成本低、可解释性强、支持快速接入新知识。 传统 RAG 流程包括文档加载、文本切分、向量化、检索、重排和生成回答。 近年来，RAG 还发展出了 Agentic RAG、Graph RAG、多模态 RAG 等进阶形态。

4.2 初始化依赖与全局参数

在 Notebook 的第一个单元格中导入依赖，并设置全局参数。

import os from pathlib import Path from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_huggingface import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma # 路径配置 BASE_DIR = Path(".") DATA_PATH = BASE_DIR / "data" / "rag_intro.txt" CHROMA_PATH = BASE_DIR / "chroma_db" # 切分参数 CHUNK_SIZE = 200 CHUNK_OVERLAP = 30 # 检索参数 TOP_K = 3 # Embedding 模型 EMBED_MODEL = "BAAI/bge-small-zh-v1.5" print("初始化完成")

需要注意的是，langchain_community在较新的langchain版本中已经被拆分出去，所以这里单独安装。如果你使用的是旧版 LangChain，导入路径可能是langchain.document_loaders，请根据你的版本调整。

4.3 文档加载与切分

# 1. 加载文档 loader = TextLoader(str(DATA_PATH), encoding="utf-8") documents = loader.load() print(f"加载到 {len(documents)} 个文档对象") print(documents[0].page_content[:200])

预期输出是文档前 200 个字。

接着做切分：

# 2. 切分文本 text_splitter = RecursiveCharacterTextSplitter( chunk_size=CHUNK_SIZE, chunk_overlap=CHUNK_OVERLAP, separators=["\n\n", "\n", "。", "！", "？", " ", ""] ) chunks = text_splitter.split_documents(documents) print(f"切分出 {len(chunks)} 个文本块") print("示例块：") print(chunks[0].page_content) print("---") print(chunks[1].page_content)

这里每个 chunk 都是一个Document对象，里面除了page_content，还有metadata。我们可以给每个 chunk 加上序号，方便后面追踪来源。

4.4 构建向量库

# 3. 初始化 Embedding 模型 embeddings = HuggingFaceEmbeddings( model_name=EMBED_MODEL, encode_kwargs={"normalize_embeddings": True} ) # 4. 生成向量库并持久化 vector_store = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory=str(CHROMA_PATH) ) print(f"向量库已创建，位置：{CHROMA_PATH}")

第一次运行需要下载 Embedding 模型，时间取决于网络状况。下载完成后，模型会缓存到本地，后续运行不需要重复下载。

如果你要重新构建向量库，建议先删除已有的chroma_db目录，避免旧数据和新增数据混在一起。

4.5 检索召回与答案生成

先做向量检索，看看检索结果是否合理。

query = "什么叫检索增强生成？" retriever = vector_store.as_retriever(search_kwargs={"k": TOP_K}) retrieved_docs = retriever.invoke(query) print(f"为问题检索到 {len(retrieved_docs)} 个相关块：\n") for i, doc in enumerate(retrieved_docs): print(f"--- 第 {i + 1} 个结果 ---") print(doc.page_content) print()

运行后，你应该能看到和问题语义相关的几个片段。

然后接入生成模型。这里以 OpenAI 兼容接口为例。如果你使用 OpenAI，直接配置官方 Key；如果你使用国内大模型服务，通常也提供 OpenAI 兼容的 HTTP 接口。

from langchain_openai import ChatOpenAI # 这里配置你的 API Key 和 Base URL # base_url 根据你的服务商调整 llm = ChatOpenAI( model="gpt-4o-mini", temperature=0.2, openai_api_key=os.getenv("OPENAI_API_KEY") ) def build_prompt(question: str, docs) -> str: context = "\n\n".join([doc.page_content for doc in docs]) prompt = f"""你是一个知识库问答助手。请仅根据以下资料回答问题。 如果资料中没有相关内容，请直接回答“知识库中未找到相关信息”。 资料： {context} 问题：{question} """ return prompt prompt = build_prompt(query, retrieved_docs) answer = llm.invoke(prompt) print("模型回答：") print(answer.content)

如果你的机器上没有大模型 API，也可以先跳过生成环节，只保留检索结果做人工判断。这一步不影响理解 RAG 前半段的工作。

4.6 运行效果与结果说明

整个 Notebook 运行完成后，你的输出流程大致如下：

加载到 1 个文档对象 切分出 7 个文本块 向量库已创建，位置：chroma_db 为问题检索到 3 个相关块： --- 第 1 个结果 --- RAG 全称是 Retrieval-Augmented Generation，即检索增强生成。 它的核心思想是在大语言模型生成回答之前，先从外部知识库中检索相关文本片段。 ... 模型回答： 检索增强生成（RAG）是一种在生成回答前先从外部知识库检索相关文本片段的技术。

到这里，一个最小的 RAG 链路就完全跑通了。

5. RAG 知识库的指标与评估

很多读者搭建完 RAG 后，觉得“效果时好时坏”，但说不清楚哪里差。这通常是因为缺少一套评估指标。

5.1 检索层指标

检索层关注的是“该搜出来的有没有搜出来”。

常用指标如下：

这里最关键的是 Recall 和 MRR。Recall 低说明知识库内容被切碎或索引错了，MRR 低说明排序有问题，需要通过重排改善。

5.2 生成层指标

检索准不等于答案好。生成层主要看三个指标：

• 忠实度（Faithfulness）：生成内容是否严格依据检索到的资料，没有编造。
• 答案相关性（Answer Relevance）：回答是否针对用户提出的问题。
• 上下文相关性（Context Relevance）：检索到的上下文是否足够支撑回答。

这组指标可以从“主观感受”变成可量化的打分，通常做法是让一个更强的模型作为裁判，给生成结果逐项打分。

5.3 如何理解这些指标

在实际项目中，不要只看一个指标。我建议按以下顺序排查：

1. 先看 Hit Rate 和 Recall：如果召回结果里压根没有正确答案，生成再强也没用。
2. 再看 MRR 或 NDCG：如果答案在召回结果里，但排得很靠后，会导致上下文过长、噪声过多。
3. 最后看忠实度：如果检索没问题但答案还是编造，问题出在 Prompt 或者说生成模型。

你可以用这种思路给自己的知识库做一次“体检”。

6. 如何让 RAG 更精准

很多人问“如何创建精准的 RAG”。答案不是某一个技巧，而是下面这几个环节的综合优化。

6.1 从源头控制文档质量

输入垃圾，输出垃圾。RAG 也一样。

• 去掉页眉页脚、水印、导航栏等无关文本。
• 保留标题层级，尽量使用 Markdown 或结构化数据。
• 对 PDF 要人工抽样检查解析结果，尤其是表格。
• 对协议类文档，比如 3GPP 规范或合同条款，要按条款编号保留结构，不要按固定字符数硬切。

如果你发现某个文档检索效果总是差，先检查原始解析结果，大概率是解析阶段就丢了信息。

6.2 混合检索与查询改写

纯向量检索对关键词不敏感。比如用户搜“怎么请假”，文档里写的是“休假流程”，向量相似度可能不够高。

改进思路有两种：

• 混合检索：向量检索 + 关键词 BM25 检索，再把结果合并排序。
• 查询改写：先让大模型把用户问题改写成更利于检索的形式，例如补全同义词、扩展专业术语。

例如用户问“工资什么时候发”，可以改写成“公司工资发放日期、工资发放规则、发薪日”。

6.3 Rerank 重排

重排是提升 RAG 效果性价比最高的手段之一。

先用向量库快速召回 20 条候选，再用重排模型精排，取前 3 条给大模型。这样可以兼顾召回率与精度。

Rerank 的伪代码如下：

# 假设候选文档已经在 candidates 中 # reranker 是重排模型 scores = reranker.score(question, candidates) top_results = sort_by_score(candidates, scores)[:3]

在 Notebook 中，你可以先打印重排前后的对比，直观感受重排模型的作用。

6.4 Agentic RAG 与 Ontology RAG

如果问题链比较复杂，比如“对比这两个产品的售后政策”，一次检索往往不够。

这时可以引入 Agentic RAG：让大模型像 agent 一样，根据问题拆解检索计划，多次检索，直到信息足够。常见实现是 LangGraph 中的多步检索节点。

另外还有 Ontology RAG，它提前定义好概念之间的关系，检索时不只找字面片段，还会顺着知识图谱关系找到相关内容。适合做企业知识体系比较复杂、实体关系密集的场景。

6.5 多模态 RAG 拓展

如果你的知识库里有大量图片、表格、流程图，纯文本 RAG 会丢失信息。

多模态 RAG 的思路是：

• 使用多模态 Embedding 模型，将图片和文本统一向量化。
• 或者先用视觉模型把图片内容转录为文字，再进入普通 RAG 流程。

第二种方案实现成本更低，目前也是很多项目的首选。

7. 常见问题与排查思路

在实际跑 RAG Notebook 时，有几个高频问题经常被问到。

7.1 Notebook 环境类问题

检查 Kernel 环境是最关键的一步。很多人明明pip list能看到包，但 Notebook 里导入失败，几乎都是 Kernel 环境没切换对。

7.2 中文切分与编码问题

中文切分目前没有一个万能方案。我的建议是：先按分隔符递归切，再人工打印前 20 个 chunk 检查。如果发现大量句子被截断，就应该调整chunk_overlap或分隔符。

7.3 检索效果差

这里要特别提醒：每次修改切分参数或文档后，记得清空向量库目录再重建。Chroma 持久化通常只会新增，不会自动删除旧的分块，容易造成“老的脏数据还在影响结果”的问题。

8. 最佳实践与工程建议

8.1 用模块化方式组织 Notebook

一个 RAG Notebook 不要把所有代码堆在一个单元格里。建议按以下结构组织：

01 环境检查与依赖安装 02 文档加载与预览 03 文本清洗与切分 04 向量库构建 05 检索测试 06 重排测试 07 生成问答 08 效果评估

这样当你调试时，只需要重跑某个阶段的单元格，不用从头再来。

8.2 给 chunk 打上完整元数据

在构建向量库时，强烈建议保留每一条 chunk 的来源信息。

示例代码：

for i, chunk in enumerate(chunks): chunk.metadata["chunk_id"] = i chunk.metadata["source"] = str(DATA_PATH)

因为生产环境中，用户最终需要知道“这个答案出自哪份文档的哪个部分”。如果元数据里只有文本内容，后续审计和纠错都会很困难。

8.3 从原型到生产环境的注意事项

Notebook 跑通只是第一步。生产环境需要考虑更多内容：

• 权限控制：不同角色只允许检索自己有权限的文档，通常通过元数据过滤实现。银行、医疗等敏感行业尤其重要。
• 文档更新机制：新文档上线时，只删除并重建对应文档的向量，不要全库重建。
• 监控与日志：记录每个问题的命中文档、Rerank 分数、模型回答，方便回溯分析。
• 内容安全：对检索内容和生成结果做合规过滤，涉及敏感信息时要有脱敏和审计能力。
• 评估闭环：建立一套评估集，每次修改切分策略、模型参数后，都跑一遍评估，用指标验证效果，而不是凭感觉。

8.4 合理选择 Embedding 模型与底座

不要迷信“最大最贵的模型”。对中文知识库场景，建议先在你的测试集上对比几个开源模型，选效果好、推理速度快的。

我见过不少项目，问题不在模型，而在文档解析。原始文档质量差，换再大的模型也救不回来。

9. 总结与下一步学习方向

到这里，这份RAG Refresher Notebook已经把 RAG 从文档加载到最终生成的完整链路走了一遍。你不仅看到了每个环节的代码，还理解了为什么要切分、为什么要向量化、为什么要加重排、如何用指标评估效果。

如果你想把 RAG 从“能跑”提升到“好用”，下一步可以重点研究这几块：

• 混合检索与查询改写，解决长尾问题。
• Rerank 模型引入，提升排序质量。
• LangGraph 实现 Agentic RAG，处理多步复杂问题。
• Graph RAG 或 Ontology RAG，处理强关系型知识。
• 评估数据集建设，让每一项优化都可以量化。

希望这份笔记本能在你搭建 RAG 知识库时少走一些弯路。如果中途遇到报错，优先对照“常见问题与排查思路”一节，大部分环境类问题都出在依赖版本和 Kernel 环境上。