检索增强生成(Retrieval-Augmented Generation) 从零实现 + 主流框架对比,多提供方抽象封装,13 章循序渐进。
本教程不是「调库速成」,而是带你先用手写 Python 理解 RAG 每个组件的原理,再用 LangChain / LlamaIndex 等框架重写对比——既知其然,又知其所以然。所有章节共享一套多提供方抽象层(OpenAI / Ollama / 智谱 GLM / DeepSeek 一键切换),换模型只改 .env,不改代码。
- 第 1 章 RAG 概述与环境搭建 — 是什么、为什么、整体架构、uv 环境、抽象层设计
- 第 2 章 文档加载与预处理 — PDF/Web/Markdown 加载、清洗规范化
- 第 3 章 文本分块策略 — 定长/递归/语义分块、chunk_size 取舍
- 第 4 章 Embedding 原理与实践 — 向量表示、相似度、模型选择
- 第 5 章 向量数据库 — numpy 手写 / FAISS / Chroma 对比
- 第 6 章 检索策略 — 语义检索 / BM25 / 混合检索 / MMR / 元数据过滤
- 第 7 章 重排序 Rerank — Cross-Encoder、为什么需要 rerank
- 第 8 章 查询改写与扩展 — HyDE / Multi-Query / Step-Back / 分解
- 第 9 章 Prompt 工程与上下文组装 — 上下文拼接、引用标注、流式生成
- 第 10 章 Graph RAG — 知识图谱抽取与图检索
- 第 11 章 Agentic RAG — 路由式 / 自纠正 / 工具调用
- 第 12 章 RAG 评估 — RAGAS 指标、自定义评估
- 第 13 章 生产部署与优化 — 缓存 / 异步 / FastAPI 服务 / 监控
- Python ≥ 3.11
- uv ≥ 0.4(本教程用它做环境与依赖管理)
- 一个 LLM / Embedding 提供方的访问凭据(见下)
git clone <your-repo-url>
cd RAG
uv sync # 安装核心依赖 + dev 组按章节安装可选依赖(各章独立,按需安装):
uv sync --group ch02 # 第 2 章所需:pypdf / bs4 / markdown
uv sync --group ch05 # 第 5 章所需:faiss-cpu / chromadb
uv sync --group ch11 # 第 11 章所需:langgraph ...复制环境变量模板并填入你的密钥:
cp .env.example .env编辑 .env,选择一个提供方。所有提供方都通过 OpenAI 兼容接口接入,只改 4 个变量即可切换:
| 提供方 | LLM_PROVIDER | LLM_MODEL | 说明 |
|---|---|---|---|
| OpenAI 官方 | openai |
gpt-4o-mini |
教程默认,生态最全 |
| Ollama 本地 | ollama |
qwen2.5:7b |
免费、离线,需先 ollama pull |
| 智谱 GLM | zhipu |
glm-4-flash |
国内可用 |
| DeepSeek | deepseek |
deepseek-chat |
性价比高 |
# 第 1 章:验证环境与抽象层
uv run python chapters/ch01_overview/demo_env.py
# 第 5 章:向量库对比
uv run python chapters/ch05_vector_db/chroma_demo.py每章目录下的 README.md 是该章正文(原理 + 代码讲解 + 练习),同名 .py 是可运行示例。
RAG/
├── pyproject.toml # uv 依赖管理(核心依赖 + 各章可选组)
├── .env.example # 环境变量模板(复制为 .env)
├── src/rag_tutorial/ # 共享抽象层(全教程复用)
│ ├── config.py # 配置读取
│ ├── llm.py # 多提供方 LLM 抽象
│ ├── embeddings.py # 多提供方 Embedding 抽象
│ └── utils.py # 相似度 / 来源格式化 / 语料加载
├── data/sample_docs/ # 全教程共享示例语料
├── chapters/ # 13 章正文 + 可运行代码
│ └── ch01_overview/
│ ├── README.md # 章节正文
│ └── *.py # 示例代码
└── tests/ # 烟雾测试
- 按顺序学:前 5 章是地基,跳着看会卡在后续章节。
- 先跑代码再读原理:每章先
uv run python xxx.py看输出,再回头读 README。 - 动手改:把示例语料换成你自己的文档,观察检索效果变化。
- 切换提供方:用 Ollama 跑通本地版本,再切到 OpenAI 对比效果与成本。
MIT