RAG From Zero
从零跑通 RAG 完整链路,跟着代码学,完整开源
A complete, runnable, Chinese RAG tutorial — built by hand, no LangChain magic.
🌐 在网站看完整教程 ·
💻 章节速览 ·
⚡ 5 分钟跑起来 ·
📱 关于作者 · ⭐ Star 一下支持
一套 RAG 系统的完整架构:离线建库 + 在线问答 双链路
这个项目是什么
我是 @MisterBooo，5 年前我做了 LeetCodeAnimation（用动画讲算法）。
2026 年，我把同样的「图解 + 实战」方法用在大模型上，做了这个 RAG 教程项目：10 章 + 附录，每章配可运行代码、图解和相关面试题，外加一个端到端教学项目。
真实性说明：仓库使用合成保险资料。文中的「核辐射条款」「推销 vs 销售」等是可复现的教学场景，不是作者、学员或客户的真实事故；仓库也不提供可直接写进简历的固定业务指标。
给谁看?
有编程基础（Python 会写、命令行能用）、但 RAG / Agent / 大模型应用零基础的工程师。
- ❌ 不适合：完全不会编程的初学者
- ❌ 不适合:已经做过 RAG 项目的资深工程师
- ✅ 适合:想转大模型岗、但被市面上「原理太抽象 / 代码太黑盒」的教程劝退的工程师
跟市面上其他 RAG 教程有啥不一样?
| 维度 | 市面常见 RAG 教程 | 这个项目 |
|---|
| 实现方式 | LangChain 封装,跑通了不知道为啥 | 全手写,自己实现切分 / 检索 / 重排 / Query 改写 |
| 配套代码 | demo 玩具,clone 下来跑不通 | 完整可运行,自带合成测试数据 |
| 内容深度 | 偏概念,缺失败验证 | 每章配可运行的失败演练(核辐射条款、推销 vs 销售…) |
| 面试帮助 | 学完不知道怎么讲 | 每章配相关面试题 + 事实填空式简历模板 |
| 目标读者 | 含糊不清 | 明确「半小白」:有编程基础 + RAG 零基础 |
⚡ 5 分钟跑起来
需要 Python 3.10+ 和 git。下面命令在 macOS / Linux 上用 python3 / pip3,
在 Windows 上用 python / pip(或 py -3)。
跑不通?跳到下面的 🐛 跑不通?常见问题,或看 TROUBLESHOOTING.md。
30 秒:先看一个切分失败演练(零配置,不用 key)
git clone https://github.com/MisterBooo/rag-from-zero.git
cd rag-from-zero/chapters/ch03-chunking
# 装依赖(macOS / Linux)
pip3 install -r requirements.txt
# Windows: pip install -r requirements.txt
# 跑失败演练(macOS / Linux)
python3 reproduce-disaster.py
# Windows: python reproduce-disaster.py
你会看到(这是使用合成条款构造的最小失败演练,输出是确定的):
=== 固定长度切分的失败演练 ===
Chunk 0: 本保险承保意外伤害导致的身故或残疾,但以下情况除外
Chunk 1: :(1)战争 (2)核辐射
=== 用户问:核辐射在保障范围内吗? ===
→ Chunk 0 只到'但以下情况除外'就断了,除外项全在 Chunk 1
→ 检索只命中 Chunk 0,模型看不到核辐射属于除外项
→ 模型可能回答'在保障范围内' → 残缺证据沿生成链路放大
这就是你将跟着分析的工程风险。它不是线上事故记录,而是用于验证「切分破坏语义」的教学场景。
完整版:跑通一个真正的 RAG 系统
rag_project/ 是一个真正能跑的端到端系统:DeepSeek + ChromaDB + bge-m3,核心代码全手写、没有 LangChain,每个模块对应教程一章。
cd rag-from-zero/rag_project
# 下面用 macOS / Linux 的 python3 / pip3;Windows 换成 python / pip(或 py -3)
# 先跑零依赖冒烟测试,确认逻辑没问题(不需要 key、不下模型)
python3 tests/smoke_test.py
# 完整链路:造数据 → 建向量库 → 提问(需 DeepSeek key + 本地 Embedding)
pip3 install -r requirements.txt
cp .env.example .env # 填入 DEEPSEEK_API_KEY
python3 scripts/generate_synthetic_data.py
python3 scripts/build_index.py
python3 scripts/ask.py "核辐射在保障范围内吗?"
ask.py 会打印「提问 → 答案 → 来源」,答案基于检索到的合成条款生成并标注出处。详细路径(含「30 秒免建库快速体验」)见 rag_project/README.md。
🐛 跑不通?常见问题
zsh: command not found: pip / python —— 你多半在 macOS 上,系统命令是 pip3 / python3(不是 pip / python)。直接用上面的 macOS / Linux 命令即可。
SSL: CERTIFICATE_VERIFY_FAILED —— 你装的是 python.org 官方安装包,默认没装 CA 证书。在终端跑一次(把 3.13 换成你的实际版本):
/Applications/Python\ 3.13/Install\ Certificates.command
装完再重新 pip3 install。
pypi 太慢 / 卡住 —— 换清华镜像:
pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
更全的排查(含 Windows / Linux)见 TROUBLESHOOTING.md。
📊 项目特色
🎯 目标读者锁死「半小白」
每章都用一套「铁律」控制质量,确保有编程基础、RAG 零基础的人能独立跟下来:
- 术语第一次出现,必有白话解释(「Embedding 就是把一段文字变成一串数字,意思相近的数字也相近」)
- 代码逐行注释,每段后写「你应该看到 XXX」
- 必有「🐛 跑不通?看这里」段,列常见报错
- 必有「🛠️ 动手实验」让你改一个参数、观察结果变化
- 每节结尾有「你掌握了什么」+「你做的 = 真实系统的哪一步」
📖 三段式结构,一章服务三种读者
每章约 8000–10000 字 + 多张原创图解,按 60 / 30 / 10 拆成三段:
| 段落 | 给谁看 | 占比 | 内容 |
|---|
| 🚀 Part 1 · 主线实战 | 零基础,想先跑起来 | ~60% | 概念白话 + 代码逐行注释 |
| 🎯 Part 2 · 面试深度 | 想讲透、备战面试 | ~30% | 硬伤剖析 + 选型 + 业内行话 |
| 🏆 Part 3 · 验收串题 | 检验学到位没 | ~10% | 关联面试题 + 自检清单 |
想先跑起来只看 Part 1;备面试直奔 Part 2。
💻 全手写,不用 LangChain
LangChain 把一切都封装好了,结果是你跑通了,却不知道里面发生了什么。这套代码全部手写:
- 自己实现 PDF 解析 + 结构感知切分(第 3 章)
- 自己实现 Embedding + 向量库封装(第 4 章)
- 自己手写 BM25 + 向量混合检索(第 5 章)
- 自己实现 Cross-Encoder 重排(第 6 章)
- 自己实现 Query 理解与改写(第 7 章)
学完是真懂 RAG,而不是只会调 LangChain 的几个 API —— 这恰恰是面试官想确认的。
🐛 工程失败演练合集
每章都有可复现的合成场景。它们用于理解故障机制,不能当作你的客户经历或项目故事:
- 第 1 章 · 没用 RAG 直接问大模型 → 观察无依据答案风险
- 第 3 章 · 固定长度切分 → 「核辐射条款」被切散,观察残缺证据怎样误导生成
- 第 3 章 · OCR 印章遮挡 → 用合成页面比较识别和人工复核方案
- 第 5 章 · 用户问「推销」→ 文档里写的是「销售」,关键词检索召回为 0
- 第 5 章 · 录播视频检索为 0 → 视频内容根本不在向量库里,只有文件名
在网站读完整失败演练 →
📚 章节速览
| # | 主题 | 你将学到 / 失败演练 | 代码 | 文章 |
|---|
| 1 | 为什么做 RAG | 「现金价值公式无依据」场景;20 行迷你 RAG 跑通核心机制 | → | → |
| 2 | RAG 整体架构 | 四大模块怎么联动;为什么大模型反而最省心 | → | → |
| 3 | 文档预处理与切分 | 「核辐射条款被切散」演练;用评估集比较三类方案 | → | → |
| 4 | Embedding 选型 | bge-m3 / OpenAI / 国产模型怎么选;何时该微调 | → | → |
| 5 | 检索召回 · 混合检索 | 「推销 vs 销售」漏召回演练;手写 BM25 + 向量融合 | → | → |
| 6 | 重排与检索优化 | Cross-Encoder 凭什么更准;精排慢了怎么提速 | → | → |
| 7 | Query 理解与改写 | HYDE「先让模型瞎答一个」为什么反而提升召回 | → | → |
| 8 | 多轮对话与记忆 | 把「那它过了还能退吗」里的「它」补全成可检索的问题 | → | → |
| 9 | 上下文问答与引用溯源 | 基于资料生成、没依据就拒答、每个结论标出处 | → | → |
| 10 | 系统评估与上线优化 | 「没有评估集的优化都是自嗨」;Recall@k / MRR | → | → |
| 附录 | 写进简历 & 面试应答 | 简历填空模板 + STAR 话术 | → | → |
🗂️ 项目结构
rag-from-zero/
├── README.md ← 你正在看的文件
├── LICENSE ← MIT
├── chapters/ ← 每章一个目录:可运行 demo + 章节说明
│ ├── ch01-why-rag/ # 第 1 章 · 为什么做 RAG
│ ├── ch02-architecture/ # 第 2 章 · RAG 整体架构
│ ├── ch03-chunking/ # 第 3 章 · 文档切分(含「核辐射」失败演练)
│ │ ├── chunk_demo.py # 跟着敲的切分 demo
│ │ ├── reproduce-disaster.py # 复现「核辐射条款被切散」
│ │ ├── requirements.txt
│ │ └── sample-data/ # 合成保险条款
│ ├── ch04-embedding/ … ch10-evaluation/
│ └── appendix-resume-interview/ ← 简历填空模板
└── rag_project/ ← 完整端到端项目(DeepSeek + ChromaDB,手写无 LangChain)
├── src/ ← 核心模块,各对应一章(loader / chunker / embedder /
│ vectorstore / retriever / reranker / query_processor /
│ generator / pipeline)
├── scripts/ ← 造数据 / 建库 / 问答(generate / build_index / ask / quickstart)
└── tests/ ← 零依赖冒烟测试 + 评估集
每章自包含 —— cd chapters/ch03-chunking && pip3 install -r requirements.txt && python3 chunk_demo.py 就能跑(Windows 用 pip / python)。
📈 学完能做什么
简历可以怎么写
只写你亲自完成且能提供证据的事实。公开附录给出的是填空框架,不是可直接复制的固定故事:
<你的项目名称>（<你的真实职责>）
- 处理
<有权使用的资料类型与规模>，负责 <你实际完成的模块>
- 基线为
<修改前方案>，主要失败样本是 <你的真实 bad case>
- 实现
<你实际完成的切分 / 检索 / 重排方案>
- 在
<样本量、标注规则、运行配置> 下，实测 <你自己的指标变化>
- 已知边界为
<仍未解决的问题>
合成保险场景不能改写成「主导某保险客户项目」，教程演示数字也不能写进简历。
面试可以怎么讲
每章末尾配相关面试题，按「为什么这么设计 / 怎样验证 / 有什么边界」的思路组织回答。
更多 → 大模型面试题库
关于作者
- 📚 LeetCodeAnimation —— 用动画讲算法
- 🌐 wushixiongai.com —— 大模型面试题库
- 📱 公众号 「吴师兄学大模型」 —— 给想进大厂大模型岗的工程师：每天一题 + 项目拆解
📜 项目来源
这个公开仓库提供文章、可运行代码、图解和配套面试题。仓库数据是明确标注的合成保险条款,不包含客户数据,也不以公开代码证明生产上线、商业成效或学员求职结果。
想了解训练营,可以关注公众号「吴师兄学大模型」。
Star History
License
MIT —— 自由使用,商用请保留署名。
⭐ 如果对你有帮助,给个 Star 就是对我最大的支持。
❓ 有问题?欢迎提 Issue 或在公众号留言。
ℹ️ 本仓库由主仓库自动同步生成(源目录 docs/v2-rag-project/github-repo/,push 到 production 时通过 rsync 同步)。请勿直接在本仓库修改,会被下次同步覆盖。
