bRAG：从入门到高级的 RAG 构建指南

网上 RAG 教程很多，真正能从「切块、向量库、一条链」一路走到多查询、路由、RAPTOR、重排序的，并不多。bRAG-langchain 把这条路径收成五个 Jupyter Notebook，外加一份能直接改的聊天机器人样板。仓库大约 4100 星，代码还在更，官网是 bragai.dev。

下面按 README 的顺序：先把环境跑通，再按笔记本往上加能力。图和讲解受 Lance Martin 的 LangChain 教程启发，具体实现以仓库为准。

你拿到的是什么

这不是一个装完就能对外服务的产品，而是一套动手课。根目录的 full_basic_rag.ipynb 是最短路径：加载文档、切块、嵌入、检索、生成，拼成一个可改的 RAG 聊天机器人。notebooks/ 里五本再拆开讲为什么这么拼，以及单查询不够用时怎么补。

依赖写在 requirements.txt 里，核心是 LangChain 全家桶（langchain、langchain-openai、langchain-pinecone、langchain-cohere）、Chroma、Pinecone、Cohere、pypdf、tiktoken。Notebook 4 还会用到 ragatouille 做 ColBERT。

作者推荐 Python 3.11.11。更高版本（比如 3.13）装向量库和 Jupyter 内核时经常踩坑，按 README 用 3.11 建虚拟环境更省事。

本机装起来

git clone https://github.com/bragai/bRAG-langchain.git
cd bRAG-langchain
python3.11 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

把 .env.example 复制成 .env。至少要填 OpenAI 的 key，后面嵌入和生成都走它。可选几项按你做到哪一步再补：

本机先试 Chroma 可以不填 Pinecone。LangSmith 不是必须的，但打开之后能看见每次检索喂了哪些 chunk，排错比看 print 快。

Jupyter 里选刚才那个 venv 的内核，别用系统 Python。

最短路径：先跑通一份基础 RAG

打开根目录的 full_basic_rag.ipynb。它把索引和查询拆开：索引只做一次（读文件、切块、写向量库），查询每次走检索再交给 LLM。链用 LCEL 拼起来，改 retriever、prompt、模型时不用重写控制流。

一份能跑的基线通常是：

1. 用文档加载器读 PDF 或网页（仓库依赖里有 pypdf、beautifulsoup4）。
2. 按 token 切块，留一点 overlap，避免一句话被从中间切开。
3. OpenAI embeddings 写入 Chroma（或 Pinecone）。
4. 检索 top-k，塞进 prompt，再生成回答。

这一步的目标不是效果最好，而是确认 key、向量库、Jupyter 都能说话。后面所有高级手段，都是在这条基线上换零件。

五本笔记本按什么顺序看

README 要求从 1 看到 5，不要跳。每一本都假定你已经跑过上一本。

1. 架构和基线：[1]_rag_setup_overview.ipynb

装库、加载文档、生成嵌入、Chroma / Pinecone、一条最简单的检索生成链。看完你应该能自己换一份 PDF，问两三个问题，知道答错是检索没召回，还是模型胡写。

2. 多查询：[2]_rag_with_multi_query.ipynb

用户只问一句时，向量检索对措辞很敏感。同一件事换个说法，召回集合会差一截。这本让 LLM 先从原问题扩出若干变体，并行检索，再合并去重。对比单查询，通常能看出漏召回变少，噪音也会变多，所以后面才会有 rerank。

3. 路由和查询构造：[3]_rag_routing_and_query_construction.ipynb

知识不只存在一个向量库里。这本做两件事：

• 逻辑路由：用函数把问题分到不同数据源（示例按编程语言分类）。
• 语义路由：问题和预置 prompt（比如数学 vs 物理）算余弦，挑最接近的那条再生成。

另外会把自然语言收成带 metadata 的结构化查询（示例是 YouTube 教程：播放量、发布日期这类过滤）。有过滤条件时，别把一切都丢给相似度。

4. 索引和细粒度检索：[4]_rag_indexing_and_advanced_retrieval.ipynb

切块本身仓库只给了外链，重点在「同一份文档多种表示」：

• Multi-representation / MultiVectorRetriever：摘要走向量检索，命中后再把父文档拿回来生成，避免用整篇去嵌。
• RAPTOR：自底向上做层次摘要，适合问「整份材料在讲什么」这类跨越很多 chunk 的问题。
• ColBERT（经 RAGatouille）：token 级交互，比整句向量更细。笔记本里用维基百科查宫崎骏做演示。

5. 融合和重排序：[5]_rag_retrieval_and_reranking.ipynb

前面扩查询、多路召回之后，要把列表合成一条。这里会看到：

• RAG-Fusion：多查询 + Reciprocal Rank Fusion（RRF）合并排序。
• Cohere Rerank：用交叉编码器把粗召回压成更准的 top-k。
• CRAG / Self-RAG：检索结果靠不靠谱时，再决定要不要重搜、要不要改写问题。笔记本给的是思路和链接，不是完整生产实现。

看到这里，你手里已经有一条「扩查询 → 多路召回 → 融合 / rerank → 生成」的骨架，可以换成自己的语料。

动手时几个容易卡住的地方

Python 版本。 README 写得很死：venv 里 python --version 必须是 3.11。如果激活后变成 3.13，按文档用 ln -sf $(which python3.11) $(dirname $(which python))/python 把命令指回去，再重装依赖。

Key 按本子补，不要一次开齐。 跑 1、2 本，OpenAI 就够。Pinecone 只在你不想把向量放本机时才需要。Cohere 放到第 5 本再开。LangSmith 建议尽早开，用来对照「模型胡说」和「根本没检索到」。

费用。 多查询、RAPTOR 建树、ColBERT 建索引都会把 embedding / LLM 调用打出好几倍。先用十几页 PDF 验证流程，再上全量语料。

这是课，不是服务。 没有现成的 Docker 入口，也没有鉴权。要对外提供问答，得自己把 notebook 里的链抽成 API，向量库用持久化目录或 Pinecone，别指望 Jupyter 进程一直挂着。

依赖比较旧。 LangChain 拆包很快，langchainhub、个别 import 路径可能和你本机最新文档对不上。报错时先看 notebook 单元格上方的 import，再去改自己的代码，不要按 2026 年最新 LangChain 文档硬套。

建议的学习节奏

1. 克隆，3.11 虚拟环境，只填 OPENAI_API_KEY。
2. 跑 full_basic_rag.ipynb，换成你自己的一份文档，记下答错的问题。
3. 按 1→5 过 notebook。每本只改一处：多查询、路由、多向量、RRF / Cohere。
4. 把答错的那几题再跑一遍，看召回列表变了没有。变了再谈换模型。

仓库：https://github.com/bragai/bRAG-langchain