RUC-NLPIR/FlashRAG · 上手攻略
- 仓库：RUC-NLPIR/FlashRAG
- 链接：https://github.com/RUC-NLPIR/FlashRAG
- 分类：rag / llm-research-toolkit
- 作者：Tom
- 更新：2026-08-10
是什么 / 解决什么问题
FlashRAG 是中国人民大学 NLPIR 实验室开源的 RAG（检索增强生成）研究 Python 工具包，已被 WWW 2025 Resource Track 接收。
核心理念：RAG 研究门槛高——需要分别找数据集、实现各算法、搭评估流程，碎片化严重。FlashRAG 提供一站式解决方案：36 个预处理基准数据集 + 23 个 SOTA RAG 算法（含 7 个推理增强方法），开箱即用，支持自定义流水线组装。
关键词：模块化 RAG 框架、推理增强管道、多模态 RAG、高效预处理、可视化 UI。
快速安装
pip 安装（推荐，最简方式）
pip install flashrag-dev --pre
# 可选：安装全部额外依赖（含 vLLM、sentence-transformers、pyserini）
pip install flashrag[full]
源码安装（需 Python 3.10+）
git clone https://github.com/RUC-NLPIR/FlashRAG.git
cd FlashRAG
pip install -e .
可选依赖（按需安装）
# vLLM 加速推理
pip install vllm>=0.4.1
# sentence-transformers（嵌入模型）
pip install sentence-transformers
# pyserini（BM25 检索）
pip install pyserini
# Faiss 向量索引（CPU）
conda install -c pytorch faiss-cpu=1.8.0
# Faiss GPU 版本（需 CUDA 11.4/12.1 + Linux x86_64）
conda install -c pytorch -c nvidia faiss-gpu=1.8.0
⚠️ Faiss 通过 pip 安装存在兼容性问题，官方推荐使用 conda 安装。
核心用法
1. 构建向量索引
将语料库转换为 jsonl 格式（每行一个文档）：
{"id": "0", "contents": "文档内容..."}
{"id": "1", "contents": "文档内容..."}
使用内置脚本构建索引：
python -m flashrag.retriever.index_builder \
--retrieval_method e5 \
--model_path /model/e5-base-v2/ \
--corpus_path indexes/sample_corpus.jsonl \
--save_dir indexes/ \
--use_fp16 \
--max_length 512 \
--batch_size 256 \
--pooling_method mean \
--faiss_type Flat
E5 和 BGE 模型会自动附加指令；其他嵌入模型需手动指定 --instruction。
2. 运行标准 RAG 流水线
from flashrag import FlashRAG
# 初始化 RAG pipeline
rag = FlashRAG(
retriever_type="e5",
generator_type="openai",
model_path="gpt-4o",
index_path="indexes/",
)
# 执行查询
result = rag.query("你的问题")
print(result)
3. 使用预置 SOTA 基线方法
官方提供 23 个预实现算法，包括： - 标准 RAG / RR（Corrective RAG） - REPLUG / SELF-RAG（检索增强解码） - HyDE（假设文档增强） - FLARE（主动检索） - Active RAG / Adaptive-RAG（自适应） - RQRAG（检索增强推理链） - IRCoT（链式推理检索） - Trace（知识图谱增强） - 推理增强管道：Search-o1、R1-Searcher、ReSearch
配置示例（使用 BM25 + vLLM）：
python -m flashrag.retriever.index_builder \
--retrieval_method bm25 \
--bm25_backend bm25s \
--corpus_path corpus.jsonl \
--save_dir indexes/
4. FlashRAG-UI 可视化界面
2025-01-12 新增功能，无需写代码即可配置和运行 RAG 方法：
# 启动 UI（需先完成 pip 安装）
python -m flashrag.ui.app
# 访问 http://localhost:7860
支持：选择 RAG 方法 → 选择数据集 → 配置参数 → 一键运行评估 → 可视化结果对比。
5. 多模态 RAG（2025-02-24 新增）
# 多模态生成器
generator = FlashRAG.load_generator(
model_type="multimodal",
model_path="llava-1.5-7b",
)
# 多模态检索器（Clip 架构）
retriever = FlashRAG.load_retriever(
retriever_type="clip",
model_path="clip-vit-base-patch32",
)
支持 Llava、Qwen、InternVL 等 MLLM，以及各类 Clip 架构多模态检索器。
典型适用场景
| 场景 | 适用原因 |
|---|---|
| 复现 RAG 论文算法 | 23 个 SOTA 方法直接配置跑，节省 80% 复现时间 |
| 新 RAG 算法开发 | 模块化组件（Retriever/Reranker/Generator/Compressor）可自由组合 |
| 多跳推理问答 | IRCoT + R1-Searcher 等推理增强管道支持复杂多跳 |
| 多模态 RAG 研究 | 内置 Llava/Qwen/InternVL + Clip 检索器 |
| RAG 基准评测 | 36 个预处理数据集 + FlashRAG-UI 一键评测对比 |
| 领域特定 RAG | DomainRAG 数据集（人民大学招生数据，7 类任务） |
| 中国硬件平台 | 官方支持 Paddle（PaddlePaddle）和 MindSpore 版本 |
坑与注意
-
Python 版本：要求 Python 3.10+，低于此版本会有兼容性问题。
-
Faiss 安装：pip 安装 Faiss 有兼容性问题，必须用 conda：
conda install -c pytorch faiss-cpu=1.8.0或faiss-gpu=1.8.0。Linux x86_64 独占 GPU 版本。 -
HuggingFace 数据集链接失效：2024-07-17 因 HF 问题原始链接失效，现已更新到新链接（https://huggingface.co/datasets/RUC-NLPIR/FlashRAG_datasets/），如遇 404 改用新链接。
-
BM25 后端：README 原文提到"基于 Pyserini 的检索器将在未来版本中被弃用"，现推荐使用更轻量的 bm25s 包（配置
bm25_backend: bm25s）。 -
多检索器聚合：支持多个 Retriever 组合（Multi-Retriever），需参考
docs/original_docs/multi_retriever_usage.md。 -
vLLM 版本：README 标注
vllm>=0.4.1，⚠️ 未验证当前（2026 年）vLLM 最新版本是否兼容，建议用pip show vllm确认实际安装版本号。 -
FlashRAG-UI 稳定性：UI 为 2025-01 新增功能，生产研究场景建议仍用 Python API，UI 适合快速探索。
-
Chunkie 分块：2025-01-07 集成了 Chunkie 库，支持 token/句子/语义等多种分块策略，文档见
docs/original_docs/chunk-doc-corpus.md。
与同类对比
| 维度 | FlashRAG | LangChain | LlamaIndex | RAGflow |
|---|---|---|---|---|
| 定位 | RAG 研究工具包 | LLM 应用框架 | LLM 数据框架 | RAG 产品 |
| 内置数据集 | 36 个 | ❌ | ❌ | ❌ |
| SOTA 算法 | 23 个 | 有限 | 有限 | ❌ |
| 推理增强管道 | ✅ 7 个 | 部分 | 部分 | ❌ |
| 多模态 RAG | ✅ | ✅ | ✅ | ✅ |
| 模块化 | Retriever/Reranker/Generator/Compressor | Chain 组件 | Node 组件 | Pipeline |
| 可视化 UI | ✅ FlashRAG-UI | ❌ | ❌ | ✅ |
| 研究导向 | ✅ Benchmark 评测 | ❌ | 部分 | ❌ |
| 中国硬件 | Paddle / MindSpore | ❌ | ❌ | ❌ |
核心差异：FlashRAG 是目前 RAG 研究领域覆盖算法和数据集最全的开源工具包；对比 LangChain/LlamaIndex 偏向应用开发，FlashRAG 专注研究复现与基准评测，是写 RAG 论文实验的利器。
一句话推荐结论
做 RAG 研究想快速复现 SOTA 算法、做多数据集基准评测——FlashRAG 是目前开源领域数据集最全、算法覆盖最广的研究级工具包，WWW 2025 背书，值得入手。
来源：GitHub README（https://github.com/RUC-NLPIR/FlashRAG）、README_zh.md、arXiv 论文（arXiv:2405.13576）、HuggingFace 数据集页、WWW 2025 论文 PDF、Web Search 补充