检索增强生成 (RAG) 项目

🔜 请访问 bragai.dev（即将上线）

---

此仓库包含对检索增强生成 (RAG) 在各种应用场景中的全面探索。每个笔记本都提供了从入门级到高级实现的详细、实践性指南，涵盖多查询和自定义 RAG 构建等内容。

项目结构

如果你想直接上手，请查看文件 full_basic_rag.ipynb —— 这个文件将为你提供一个完全可定制的 RAG 聊天机器人模板代码。

请确保在虚拟环境中运行你的文件（参见“开始使用”部分）。

以下笔记本位于 notebooks/ 目录下。

[1]_rag_setup_overview.ipynb

这个入门笔记本概述了 RAG 架构及其基础设置。笔记本内容包括：

• 环境设置：配置环境、安装必要的库以及 API 设置。
• 初始数据加载：基本的文档加载器和数据预处理方法。
• 嵌入生成：使用多种模型生成嵌入，包括 OpenAI 的嵌入。
• 向量存储：设置向量存储（ChromaDB/Pinecone），用于高效的相似性搜索。
• 基础 RAG 流程：创建一个简单的检索与生成流程，作为基准。

[2]_rag_with_multi_query.ipynb

在此基础上，本笔记本引入了 RAG 流程中的多查询技术，探讨：

• 多查询设置：配置多个查询以丰富检索结果。
• 高级嵌入技术：利用多种嵌入模型来优化检索效果。
• 多查询处理流程：实现多查询处理，以提高响应的相关性。
• 比较与分析：将多查询流程的结果与单查询流程进行对比，并分析性能提升。

[3]_rag_routing_and_query_construction.ipynb

本笔记本更深入地探讨了自定义 RAG 流程。内容包括：

• 逻辑路由：基于函数实现路由，根据编程语言将用户查询分类到相应数据源。
• 语义路由：利用嵌入和余弦相似度，将问题导向数学或物理提示，从而优化响应准确性。
• 元数据过滤的查询构建：为 YouTube 教程元数据定义结构化搜索模式，支持高级筛选（如按观看次数、发布日期等）。
• 结构化搜索提示：借助 LLM 提示生成数据库查询，以根据用户输入检索相关内容。
• 与向量存储集成：将结构化查询与向量存储连接，实现高效的数据检索。

[4]_rag_indexing_and_advanced_retrieval.ipynb

延续之前的自定义工作，本笔记本进一步探索：

• 文档分块简介：提供外部资源链接，介绍文档分块技术。
• 多表示索引：设置多向量索引结构，以处理具有不同嵌入和表示形式的文档。
• 摘要的内存存储：使用 InMemoryByteStore 存储文档摘要及父文档，便于高效检索。
• MultiVectorRetriever 设置：整合多种向量表示，根据用户查询检索相关文档。
• RAPTOR 实现：探索 RAPTOR 这一先进的索引与检索模型，并提供深度学习资源链接。
• ColBERT 集成：演示基于 ColBERT 的标记级向量索引与检索，能够捕捉细粒度的上下文语义。
• ColBERT 示例：宫崎骏：使用 ColBERT 检索模型演示如何获取关于宫崎骏的信息。

[5]_rag_retrieval_and_reranking.ipynb

最后这个笔记本将 RAG 系统的各个组件整合在一起，重点在于可扩展性和优化：

• 文档加载与分割：加载并分块文档以便索引，为向量存储做准备。
• 基于 RAG-Fusion 的多查询生成：采用提示驱动的方式，从单个输入问题生成多个搜索查询。
• 倒数排名融合 (RRF)：实现 RRF 对多个检索列表进行重新排序，合并结果以提高相关性。
• 检索器与 RAG 链设置：构建用于回答查询的检索链，利用融合排名和 RAG 链提取上下文相关信息。
• Cohere 重排序：演示使用 Cohere 模型进行额外的上下文压缩与优化。
• CRAG 和 Self-RAG 检索：探索 CRAG 和 Self-RAG 等高级检索方法，并提供示例链接。
• 长上下文影响的探讨：提供资源链接，解释长上下文检索对 RAG 模型的影响。

开始使用

前置条件

请确保系统中已安装 Python 3.11.11（推荐版本）。如果尚未安装，请按照以下平台特定说明进行安装。

macOS

1. 如果尚未安装 Homebrew，请先安装：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. 安装 Python 3.11.11：

   brew install python@3.11
   

3. 验证安装：

   python3.11 --version
   

Linux

1. 更新包管理器：

   sudo apt update
   

2. 安装 Python 3.11.11：

   sudo apt install python3.11 python3.11-venv
   

3. 验证安装：

   python3.11 --version
   

Windows

1. 从 Python.org 下载 Python 3.11.11 安装程序。
2. 运行安装程序，并确保勾选 “将 Python 添加到 PATH” 选项。
3. 验证安装：

   python --version
   

---

安装说明

1. 克隆仓库

git clone https://github.com/bRAGAI/bRAG-langchain.git
cd bRAG-langchain

2. 创建虚拟环境

使用 Python 3.11.11 创建虚拟环境：

python3.11 -m venv venv

激活虚拟环境：

• macOS/Linux：

  source venv/bin/activate
  

• Windows：

  venv\Scripts\activate
  

3. 验证并修复 Python 版本

如果虚拟环境中默认使用的是其他版本的 Python（例如 Python 3.13）：

1. 验证当前虚拟环境中的 Python 版本：

   python --version
   

2. 在虚拟环境中显式使用 Python 3.11：

   python3.11
   

3. 确保 python 命令指向 Python 3.11，可通过创建符号链接实现：

   ln -sf $(which python3.11) $(dirname $(which python))/python
   

4. 再次验证修复是否成功：

   python --version
   

4. 安装依赖

安装所需的软件包：

pip install -r requirements.txt

---

其他步骤

5. 运行笔记本

从 [1]_rag_setup_overview.ipynb 开始，熟悉整个设置流程。然后按顺序依次运行其他笔记本：

• [1]_rag_setup_overview.ipynb
• [2]_rag_with_multi_query.ipynb
• [3]_rag_routing_and_query_construction.ipynb
• [4]_rag_indexing_and_advanced_retrieval.ipynb
• [5]_rag_retrieval_and_reranking.ipynb

6. 设置环境变量

1. 复制根目录下的 .env.example 文件，并将其重命名为 .env。

2. 添加以下键值对（请替换为您的实际值）：

   # LLM 模型 - 从 https://platform.openai.com/api-keys 获取密钥
   OPENAI_API_KEY="your-api-key"
   
   # LangSmith - 从 https://smith.langchain.com 获取密钥
   LANGCHAIN_TRACING_V2=true
   LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
   LANGCHAIN_API_KEY="your-api-key"
   LANGCHAIN_PROJECT="your-project-name"
   
   # Pinecone 向量数据库 - 从 https://app.pinecone.io 获取密钥
   PINECONE_INDEX_NAME="your-project-index"
   PINECONE_API_HOST="your-host-url"
   PINECONE_API_KEY="your-api-key"
   
   # Cohere - 从 https://dashboard.cohere.com/api-keys 获取密钥
   COHERE_API_KEY=your-api-key
   

---

现在您已经准备好使用该项目了！

使用方法

完成环境设置并按顺序运行所有笔记本后，您可以：

1. 尝试检索增强生成： 使用 [1]_rag_setup_overview.ipynb 中的基础设置，了解 RAG 的基本原理。

2. 实现多查询技术： 在 [2]_rag_with_multi_query.ipynb 中学习如何通过引入多查询技术来提升响应的相关性。

星级历史

联系方式

如果您有任何问题或希望合作，请提交一个 issue，或发送邮件至 Taha Ababou：taha@bragai.dev。

如果这个项目对您有所帮助，请考虑请我喝杯咖啡 ☕。您的支持将帮助我继续为开源社区做出贡献！

本项目的笔记本和可视化图表灵感来源于 Lance Martin 的 LangChain 教程。

bRAG-langchain 快速上手指南

本指南旨在帮助开发者快速搭建基于 LangChain 的检索增强生成（RAG）实验环境，涵盖从基础架构到高级检索策略的全流程。

环境准备

系统要求

• Python 版本：推荐 Python 3.11.11（项目强依赖此版本，其他版本可能导致兼容性问题）。
• 操作系统：macOS, Linux, 或 Windows。

前置依赖安装

请根据操作系统选择对应命令安装 Python 3.11.11：

macOS

# 安装 Homebrew (若未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Python 3.11
brew install python@3.11
# 验证版本
python3.11 --version

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3.11 python3.11-venv
python3.11 --version

Windows

1. 访问 Python.org 下载 Python 3.11.11 安装包。
2. 运行安装程序，务必勾选 "Add Python to PATH"。
3. 在命令行验证：

   python --version
   

安装步骤

1. 克隆项目

git clone https://github.com/bRAGAI/bRAG-langchain.git
cd bRAG-langchain

2. 创建并激活虚拟环境

建议使用 python3.11 明确指定版本创建环境：

python3.11 -m venv venv

激活环境：

• macOS/Linux:

  source venv/bin/activate
  

• Windows:

  venv\Scripts\activate
  

注意：若激活后 python --version 仍显示非 3.11 版本，请在虚拟环境中执行以下命令修复符号链接：

ln -sf $(which python3.11) $(dirname $(which python))/python

3. 安装依赖

pip install -r requirements.txt

(注：国内用户若下载缓慢，可添加清华源加速：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)

4. 配置环境变量

复制示例配置文件并填入你的 API Key：

cp .env.example .env

编辑 .env 文件，填入以下关键信息：

# OpenAI API Key (用于 LLM 和 Embedding)
OPENAI_API_KEY="sk-..."

# LangSmith (可选，用于追踪调试)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
LANGCHAIN_API_KEY="your-langsmith-key"
LANGCHAIN_PROJECT="your-project-name"

# Pinecone (向量数据库，若使用 ChromaDB 本地运行可不填此项)
PINECONE_INDEX_NAME="your-index"
PINECONE_API_HOST="your-host"
PINECONE_API_KEY="your-key"

# Cohere (用于重排序 Rerank，可选)
COHERE_API_KEY="your-cohere-key"

基本使用

本项目通过一系列 Jupyter Notebook 循序渐进地展示 RAG 的实现。请按顺序执行 notebooks/ 目录下的文件。

第一步：运行基础 RAG 示例

这是最简单的入门方式，将构建一个可定制的 RAG 聊天机器人基线。

1. 启动 Jupyter Lab/Notebook：

   jupyter lab
   

2. 打开并运行 notebooks/[1]_rag_setup_overview.ipynb。
   • 该笔记将引导你完成：环境配置、文档加载、Embedding 生成、向量存储（ChromaDB/Pinecone）设置以及基础 RAG 管道构建。

第二步：进阶实验

熟悉基础后，可依次运行后续笔记以探索高级功能：

• 多查询策略：运行 [2]_rag_with_multi_query.ipynb 学习如何通过多查询提升检索相关性。
• 路由与查询构造：运行 [3]_rag_routing_and_query_construction.ipynb 实现基于语义或逻辑的路由分发。
• 高级索引与检索：运行 [4]_rag_indexing_and_advanced_retrieval.ipynb 探索 MultiVector、RAPTOR 及 ColBERT 等技术。
• 重排序优化：运行 [5]_rag_retrieval_and_reranking.ipynb 学习 RAG-Fusion 和 Cohere Re-Ranking。

快速启动模板

若只想获取一个完整的 RAG 聊天机器人代码模板，可直接查看根目录下的：

• full_basic_rag.ipynb

现在你可以开始探索 Retrieval-Augmented Generation 的各种应用场景了！