为什么值得关注

项目提供了完整的离线流水线，从 Markdown 分块到证据卡，配合逐步 Notebook 和真实数据集，让学习者深入理解 RAG 内部机制。

适合谁使用

刚接触 RAG 的开发者
信息检索领域的学生
希望离线学习 RAG 管线的 AI 工程师
制作 RAG 教学材料的技术写作者或教育者

典型使用场景

学习 RAG 检索全流程（分块、索引、混合搜索、重排）
实验不同检索策略（BM25、向量嵌入、RRF、Cross-Encoder）
使用人工标注评测集评估检索质量
从搜索结果构建可追溯的证据卡

项目优势

完全离线运行，无需 API Key 或外部生成服务
以 7 节循序渐进的 Notebook 组织，并配有对应的讲解文章
包含真实 Markdown 源文档和人工标注的评测数据集
在同一管线中实现了多种检索方法（FTS5/BM25、向量嵌入、RRF、交叉编码器重排）

使用前须知

要求 Python 3.11 和 uv 包管理器
推荐至少 8 GB 内存；重排在 CPU 上较慢
首次运行需联网下载模型权重，且模型不包含在仓库中

README 快速开始

RAG Memory Lab

一个从零学习本地 RAG 检索核心的实战项目。它不调用外部生成服务、不需要 API Key；你可以逐节运行 Notebook，观察 Markdown 如何被切分、索引、召回、重排，并最终变成可追溯的证据卡。

配套阅读

两篇文章与本仓库的 01–07 课一一对应：文章负责串联思路与概念，Notebook 负责运行代码、观察真实数据和验证结果。

Markdown 文档
  → Chunk 切分
  → FTS5 / BM25 + 本地 Embedding
  → RRF 混合召回
  → Cross-Encoder 重排
  → Evidence Card（原文与来源）

你会学到什么

课程	Notebook	主题
01	`01_markdown_parser_and_sentence_splitter.ipynb`	Markdown 结构感知切分与长度兜底
02	`02_sqlite_fts5_and_bm25.ipynb`	SQLite FTS5、倒排索引与 BM25
03	`03_embeddings_numpy_milvus_and_fts_comparison.ipynb`	本地 Embedding、NumPy、Milvus Lite 与检索对比
04	`04_retrieval_evaluation.ipynb`	Recall、Precision、Hit Rate、MRR 与人工标注评测集
05	`05_hybrid_retrieval.ipynb`	RRF：融合 BM25 与向量召回
06	`06_reranking.ipynb`	Cross-Encoder 重排：从候选中精排
07	`07_evidence_cards.ipynb`	Evidence Card：来源、标题路径与检索轨迹

环境要求

macOS、Linux 或 Windows（建议使用 Python 3.11）
uv：Python 环境与依赖管理工具
首次运行可联网：会下载两个公开的本地模型权重；之后会复用本机缓存
推荐至少 8 GB 内存。CPU 可以运行；第 6 课的重排在 CPU 上会更慢

项目的原始资料已经随仓库提供，不需要另行下载。模型权重不会被提交到仓库，也不需要任何密钥。

从零启动

在项目根目录执行：

# 1. 安装锁定版本的依赖，并创建 .venv
make setup

# 2. 注册 Jupyter 内核（只需一次）
make kernel

# 3. 启动 JupyterLab
make lab

浏览器打开后，选择 RAG Memory Lab 内核，并按 notebooks/01_... 到 notebooks/07_... 的顺序逐节运行。

如果没有 make，把 Makefile 中对应命令的 uv run ... 部分直接复制到终端运行即可。

一键运行真实数据链路

下面的顺序很重要：后一步会读取前一步生成的本地文件。

# 1. 15 篇 Markdown → 210 个左右的 Chunk
make chunk-real

# 2. 构建 SQLite FTS5、Embedding、NumPy 文件与 Milvus Lite 索引
make vector-real

# 3. 评测单路召回
make eval-retrieval

# 4. 用 RRF 做混合召回并评测
make eval-hybrid

# 5. 用本地 Cross-Encoder 重排混合候选并评测
make eval-rerank

# 6. 生成包含原文、来源与排名轨迹的 Evidence Card
make build-evidence

常用的 Notebook 自动执行命令也已提供。例如：

make run-01
make run-03
make run-06

run-02 至 run-07 依赖已注册的 RAG Memory Lab 内核，因此请先执行一次 make kernel。

项目结构

rag-memory-lab/
├── knowledge-base/openai-cookbook/   # 公开 Markdown 原料、上游版本和许可
├── notebooks/                        # 01–07：可交互学习课
├── src/                              # 可复用的真实流水线代码
├── artifacts/
│   └── evaluation/retrieval-goldens.jsonl  # 人工标注的评测集（版本化）
├── assets/diagrams/                  # 课程与文章使

rag-memory-lab