[ English | 中文]

🔥 Rankify: 一个全面的 Python 工具包，专为检索、重排序和检索增强生成（RAG）设计 🔥

📢 特别感谢 Xiumao 对 Rankify 的大力支持与推广！
以下是他撰写的两篇精彩中文解析文章，为用户更好理解 Rankify 提供了重要帮助：

• 📘 Rankify 入门解析：如何构建统一检索与重排序框架
• 📘 再探 Rankify：理解不同重排序模型的原理与应用

---

如果你喜欢我们的框架，请不要犹豫，⭐ 给这个仓库加星 ⭐。这将帮助我们使 Rankify 变得更强大，并扩展到更多模型和方法 🤗。

---

一个模块化且高效的检索、重排序和 RAG 框架，专为最新的检索、排序和 RAG 任务模型设计。

Rankify 是一个 Python 工具包，专为统一的检索、重排序和检索增强生成（RAG）研究而构建。该工具包集成了 40 个预检索的基准数据集，支持 7 种检索技术，包含 24 种最先进的重排序模型，并支持多种 RAG 方法。Rankify 提供一个模块化且可扩展的框架，使研究人员和实践者能够轻松进行实验和基准测试，涵盖完整的检索流程。详细的文档、开源实现和预构建的评估工具，使 Rankify 成为该领域研究者和工程师的强大工具。

---

🚀 演示

要在本地运行演示，请执行以下操作：

# 确保已安装 Rankify
pip install streamlit

# 然后运行演示
streamlit run demo.py

https://github.com/user-attachments/assets/13184943-55db-4f0c-b509-fde920b809bc

---

:sparkles: 特性

• 全面的检索与重排序框架：Rankify 将检索、重排序和检索增强生成（RAG）整合为一个模块化的 Python 工具包，支持无缝实验和基准测试。

• 广泛的数据集支持：包含 40 个基准数据集，提供 预检索文档，涵盖 问答、对话、实体链接和事实验证等多个领域。

• 多样化的检索器集成：支持 7 种检索技术，包括 BM25、DPR、ANCE、BPR、ColBERT、BGE 和 Contriever，提供灵活的检索策略选择。

• 先进的重排序模型：实现 24 种主流重排序模型 和 41 种子方法，涵盖 点对、对对（pairwise）、列表级（listwise） 重排序方法，以提升排名性能。

• 预构建检索索引：提供 预计算的 Wikipedia 和 MS MARCO 语料库，适用于多种检索模型，减少索引开销，加速实验进程。

• 无缝 RAG 集成：连接检索与生成模型（如 GPT、LLAMA、T5），支持 零样本（zero-shot）、解码器融合（Fusion-in-Decoder，FiD） 和 上下文学习（in-context learning） 等 RAG 生成策略。

• 模块化 & 可扩展设计：通过 Rankify 结构化的 Python API，轻松集成自定义数据集、检索器、重排序模型和生成模型。

• 全面的评估套件：提供 自动化性能评估，涵盖 检索、排序和 RAG 评测指标，确保可复现的基准测试。

• 用户友好的文档支持：提供详细的 📖 在线文档、示例笔记本和教程，便于快速上手。

🔍 发展路线图

Rankify 仍在积极开发中，目前已发布首个版本（v0.1.0）。尽管当前已支持多种检索、重排序和 RAG 技术，我们仍在不断增强其功能，计划增加更多的检索器、排序器、数据集和特性。

🚀 计划改进

• 检索器（Retrievers）
• [x] 支持 BM25、DPR、ANCE、BPR、ColBERT、BGE 和 Contriever
• [ ] 添加缺失的检索器：Spar、MSS、MSS-DPR

• [ ] 支持 自定义索引加载，允许用户定义检索语料库

• 重排序器（Re-Rankers）

• [x] 24 种主流重排序模型，包含 41 种子方法

• [ ] 扩展支持，添加 更先进的排序模型

• 数据集（Datasets）

• [x] 提供 40 个用于检索、排序和 RAG 的基准数据集
• [ ] 增加 更多数据集

• [ ] 支持 自定义数据集集成

• 检索增强生成（RAG）

• [x] 已集成 GPT、LLAMA 和 T5

• [ ] 扩展支持 更多生成模型

• 评估与可用性（Evaluation & Usability）

• [x] 提供标准的检索与排序评估指标（Top-K、EM、Recall...）

• [ ] 增加 更高级的评估指标（如 NDCG、MAP 用于检索器评估）

• 流程集成（Pipeline Integration）

• [ ] 新增流水线模块，简化检索、重排序和 RAG 工作流

🔧 安装指南

设置虚拟环境

首先，使用 Python 3.10 创建并激活 conda 环境：

conda create -n rankify python=3.10
conda activate rankify

安装 PyTorch 2.5.1

我们推荐使用 PyTorch 2.5.1 来安装 Rankify。请参考 PyTorch installation page 获取特定平台的安装命令。

如果你可以使用 GPU，我们建议安装支持 CUDA 12.4 或 12.6 版本的 PyTorch，因为许多评估指标已针对 GPU 进行了优化。

安装 PyTorch 2.5.1，可使用以下命令：

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

基本安装

要安装 Rankify，只需使用 pip（要求 Python 3.10 及以上版本）：

pip install rankify

此命令将安装 Rankify 的基本功能，包括检索、重排序和检索增强生成（RAG）。

推荐安装方式

为了获得完整功能，推荐安装 Rankify 及所有依赖项：

pip install "rankify[all]"

这将确保所有必要的模块，包括检索、重排序和 RAG 支持，均已安装。

可选依赖项

如果你只想安装特定组件，可使用以下命令：

# 仅安装检索相关依赖（支持 BM25、DPR、ANCE 等）
pip install "rankify[retriever]"

# 安装基础重排序组件，包括 vLLM 支持的 `FirstModelReranker`、`LiT5ScoreReranker`、`LiT5DistillReranker`、`VicunaReranker` 和 `ZephyrReranker`
pip install "rankify[reranking]"

从 GitHub 安装最新开发版本 如果希望获取最新的开发版本，可从 GitHub 进行安装：

git clone https://github.com/DataScienceUIBK/rankify.git
cd rankify
pip install -e .
# 安装所有依赖项（推荐）
pip install -e ".[all]"
# 仅安装检索相关依赖
pip install -e ".[retriever]"
# 仅安装重排序相关依赖
pip install -e ".[reranking]"

使用 ColBERT 检索器

如果你想使用 ColBERT 检索器，请按照以下步骤进行额外设置：

# 安装 GCC 和必要的库
conda install -c conda-forge gcc=9.4.0 gxx=9.4.0
conda install -c conda-forge libstdcxx-ng

# 导出必要的环境变量
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH
export CC=gcc
export CXX=g++
export PATH=$CONDA_PREFIX/bin:$PATH

# 清除缓存的 Torch 扩展
rm -rf ~/.cache/torch_extensions/*

---

:rocket: 快速开始

1️⃣ 预检索数据集

我们提供 每个数据集 1,000 条预检索文档，你可以从以下链接下载：

🔗 Hugging Face 数据集仓库

数据集格式

预检索的文档结构如下：

[
    {
        "question": "...",
        "answers": ["...", "...", ...],
        "ctxs": [
            {
                "id": "...",         // 数据库 TSV 文件中的段落 ID
                "score": "...",      // 检索器分数
                "has_answer": true|false  // 该段落是否包含正确答案
            }
        ]
    }
]

在 Rankify 中访问数据集

你可以通过 Rankify 轻松下载和使用预检索数据集。

列出可用数据集

要查看所有可用的数据集，请运行以下代码：

from rankify.dataset.dataset import Dataset 

# 显示可用数据集
Dataset.avaiable_dataset()

BM25 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-test 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="archivialqa-test", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 chroniclingamericaqa-test 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="chroniclingamericaqa-test", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 chroniclingamericaqa-dev 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="chroniclingamericaqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 entityquestions-test 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="entityquestions-test", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 ambig_qa-dev 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="ambig_qa-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 ambig_qa-train 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="ambig_qa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 arc-test 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="arc-test", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 arc-dev 数据集的 BM25 检索文档
dataset = Dataset(retriever="bm25", dataset_name="arc-dev", n_docs=100)
documents = dataset.download(force_download=False)

BGE 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 BGE 检索文档
dataset = Dataset(retriever="bge", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 BGE 检索文档
dataset = Dataset(retriever="bge", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 BGE 检索文档
dataset = Dataset(retriever="bge", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

ColBERT 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 ColBERT 检索文档
dataset = Dataset(retriever="colbert", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 ColBERT 检索文档
dataset = Dataset(retriever="colbert", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 ColBERT 检索文档
dataset = Dataset(retriever="colbert", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

MSS-DPR 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 MSS-DPR 检索文档
dataset = Dataset(retriever="mss-dpr", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 MSS-DPR 检索文档
dataset = Dataset(retriever="mss-dpr", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 MSS-DPR 检索文档
dataset = Dataset(retriever="mss-dpr", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

MSS 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 MSS 检索文档
dataset = Dataset(retriever="mss", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 MSS 检索文档
dataset = Dataset(retriever="mss", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 MSS 检索文档
dataset = Dataset(retriever="mss", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

Contriever 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 Contriever 检索文档
dataset = Dataset(retriever="contriever", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 Contriever 检索文档
dataset = Dataset(retriever="contriever", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 Contriever 检索文档
dataset = Dataset(retriever="contriever", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

ANCE 检索器数据集

from rankify.dataset.dataset import Dataset

# 下载 nq-dev 数据集的 ANCE 检索文档
dataset = Dataset(retriever="ance", dataset_name="nq-dev", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 2wikimultihopqa-train 数据集的 ANCE 检索文档
dataset = Dataset(retriever="ance", dataset_name="2wikimultihopqa-train", n_docs=100)
documents = dataset.download(force_download=False)

# 下载 archivialqa-dev 数据集的 ANCE 检索文档
dataset = Dataset(retriever="ance", dataset_name="archivialqa-dev", n_docs=100)
documents = dataset.download(force_download=False)

从文件加载预检索数据集

如果你已经下载了数据集，可以直接加载它：

from rankify.dataset.dataset import Dataset

# 加载已下载的 WebQuestions 数据集（BM25 检索结果）
documents = Dataset.load_dataset('./tests/out-datasets/bm25/web_questions/test.json', 100)

现在，你可以将 检索文档 与 重排序 和 RAG 工作流集成！🚀

预检索数据集的特性比较

下表概述了每个数据集在不同检索方法（BM25、DPR、ColBERT、ANCE、BGE、Contriever）的可用性。

✅ 已完成
🕒 待处理

数据集	BM25	DPR	ColBERT	ANCE	BGE	Contriever
2WikimultihopQA	✅	🕒	🕒	🕒	🕒	🕒
ArchivialQA	✅	🕒	🕒	🕒	🕒	🕒
ChroniclingAmericaQA	✅	🕒	🕒	🕒	🕒	🕒
EntityQuestions	✅	🕒	🕒	🕒	🕒	🕒
AmbigQA	✅	🕒	🕒	🕒	🕒	🕒
ARC	✅