如果您喜欢我们的框架，请毫不犹豫地 ⭐ 星标这个仓库 ⭐。这有助于我们 让框架变得更好，并能扩展到不同的模型和方法 🤗。

一个模块化且高效的检索、重排序和RAG框架，专为与最先进的检索、排序和RAG任务模型配合使用而设计。

---

🚀 演示

要在本地运行演示：

# 确保已安装Rankify
pip install streamlit

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

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

---

:link: 导航

• 功能
• 路线图
• 安装
• 快速开始
  • Pipeline API
  • RankifyAgent
  • Rankify服务器
  • 集成
  • Web Playground
• 索引
• 检索器
• 重排序器
• 生成器
• 评估
• 文档
• 社区贡献
• 贡献
• 许可证
• 致谢
• 引用

🎉新闻

• [2026-02-16] 非常感谢@JamieHoldcroft集成了**15+**种新的密集检索器，包括SOTA基于LLM的双编码器（SFR、E5、GritLM）和推理增强模型（RaDeR、ReasonIR、ReasonEmbed、BGE-Reasoner）。

• [2025-10-14] 更新了安装选项，新增了可选组件：retriever、reranking、rag 和 all。

• [2025-10-14] 新的CLI (rankify-index) 语法及BM25、DPR、ANCE、Contriever、ColBERT、BGE 的示例。

• [2025-06-11] 非常感谢@tobias124实现了自定义数据集的【索引】功能（#cli-running-indexing-module）。

• [2025-06-01] 非常感谢@aherzinger实现了并重构了生成器和RAG模型。

• [2025-05-30] 非常感谢@baraayusry使用CrawAI和ReACT实现了在线检索器。

• [2025-02-10] 在Hugging Face上发布了【reranking-datasets】（https://huggingface.co/datasets/abdoelsayed/reranking-datasets）和【reranking-datasets-light】（https://huggingface.co/datasets/abdoelsayed/reranking-datasets-light）。

• [2025-02-04] 我们的【论文】（https://arxiv.org/abs/2502.02464）已在arXiv上发布。

🔧 安装

设置虚拟环境

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

conda create -n rankify python=3.10
conda activate rankify

安装 PyTorch 2.5.1

我们建议使用 PyTorch 2.5.1 安装 Rankify。请参考 PyTorch 安装页面 获取针对不同平台的安装命令。

如果您可以访问 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：

pip install "rankify[all]"

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

可选依赖项

如果您只想安装特定组件，可以从以下选项中选择：

# 检索栈（BM25、密集检索器、网络工具）
pip install "rankify[retriever]"

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

# RAG 端点（OpenAI、LiteLLM、vLLM 客户端）
pip install "rankify[rag]"

或者，要从 GitHub 安装最新开发版本：

git clone https://github.com/DataScienceUIBK/rankify.git
cd rankify
pip install -e .
# 为了获得完整功能，我们建议安装包含所有依赖项的 Rankify：
pip install -e ".[all]"
# 安装仅用于检索的依赖项（BM25、DPR、ANCE 等）
pip install -e ".[retriever]"
# 安装基础重排序，支持 vLLM 的 `FirstModelReranker`、`LiT5ScoreReranker`、`LiT5DistillReranker`、`VicunaReranker` 和 `ZephyrReranker`
pip install -e ".[reranking]"
# RAG 端点（OpenAI、LiteLLM、vLLM 客户端）
pip install -e ".[rag]"

使用 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: 快速开始

🚀 单行管道 API（推荐）

使用 Rankify 的最简单方式——HuggingFace 风格的单行接口：

from rankify import pipeline

# 创建带有智能默认值的 RAG 管道
rag = pipeline("rag")
answers = rag("什么是机器学习？", documents)

# 或者自定义您的配置
rag = pipeline(
    "rag",
    retriever="bge",           # 最先进的密集检索器
    reranker="flashrank",      # 超快速重排序器
    generator="basic-rag"
)

可用的管道类型：

• pipeline("search") - 仅文档检索
• pipeline("rerank") - 检索 + 重排序
• pipeline("rag") - 完整 RAG 管道（检索 + 重排序 + 生成）

📖 管道 API 文档

---

🤖 RankifyAgent - AI 驱动的模型选择

让 AI 帮助您为您的用例选择最佳模型：

from rankify.agent import RankifyAgent, recommend

# 快速推荐
result = recommend(task="qa", gpu=True)
print(f"最佳检索器: {result.retriever.name}")
print(f"最佳重排序器: {result.reranker.name}")

# 对话式代理
agent = RankifyAgent(backend="azure")  # 或 "openai", "litellm", "local"
response = agent.chat("我需要一个适用于生产环境的快速搜索系统")
print(response.message)
print(response.code_snippet)  # 可直接使用的代码

📖 RankifyAgent 文档

---

🌐 Rankify 服务器 - 作为 REST API 部署

通过一条命令启动一个可投入生产的服务器：

# CLI
rankify serve --port 8000 --retriever bge --reranker flashrank

# 或在 Python 中
from rankify.server import RankifyServer
server = RankifyServer(retriever="bge", reranker="flashrank")
server.start(port=8000)

API 端点：

• POST /retrieve - 文档检索
• POST /rerank - 文档重排序
• POST /rag - 完整 RAG 生成
• GET /health - 健康检查

# 示例 API 调用
curl -X POST http://localhost:8000/rag \
  -H "Content-Type: application/json" \
  -d '{"query": "什么是 AI？", "n_contexts": 5}'

📖 服务器文档

---

🔌 集成 - 与您的技术栈一起使用

无缝集成 LangChain、LlamaIndex 等：

# LangChain
from rankify.integrations import LangChainRetriever
from langchain.chains import RetrievalQA

retriever = LangChainRetriever(method="bge", reranker="flashrank")
chain = RetrievalQA.from_chain_type(llm=your_llm, retriever=retriever)

# LlamaIndex
from rankify.integrations import LlamaIndexRetriever
retriever = LlamaIndexRetriever(method="colbert", reranker="monot5")

📖 集成文档

---

🎨 Web 玩具箱 - 交互式 UI

启动一个交互式的 Gradio 界面：

from rankify.ui import launch_playground
launch_playground(port=7860)

尝试各种模型，比较结果，并导出代码——一切尽在您的浏览器中！

---

1️⃣ 传统工作流（面向高级用户）

预检索数据集

我们提供40 多个基准数据集，每个数据集包含1,000 个预检索文档：

🔗 Hugging Face 数据集仓库

数据集格式

[
    {
        "question": "...",
        "answers": ["...", "...", ...],
        "ctxs": [
            {
                "id": "...",         // 文段 ID
                "score": "...",      // 检索器得分
                "has_answer": true|false
            }
        ]
    }
]

列出可用数据集

from rankify.dataset.dataset import Dataset 
Dataset.available_dataset()  # 修正拼写错误：avaiable -> available

下载数据集

from rankify.dataset.dataset import Dataset

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

# 从文件加载
documents = Dataset.load_dataset('./path/to/dataset.json', n_docs=100)

🧱 通过 CLI 进行索引

CLI 入口点是 rankify-index，其子命令为 index。

常用标志

• corpus_path（位置参数）：JSONL 语料库的路径。
• --retriever {bm25,dpr,ance,contriever,colbert,bge}。
• --output PATH（默认值：rankify_indices）。
• --index_type {wiki,msmarco}（默认值：wiki）。
• --threads INT（默认值：32，用于稀疏及部分稠密预处理）。
• --device {cpu,cuda}（默认值：检索器专用，通常为 cuda）。
• --batch_size INT（稠密编码器 / Faiss 添加批次）。
• --encoder MODEL（仅适用于稠密编码器；省略时使用合理默认值）。

索引布局

• BM25 → <output>/<stem>/bm25_index
• DPR → <output>/<stem>/dpr_index_<index_type>
• ANCE → <output>/<stem>/ance_index_<index_type>
• BGE → <output>/<stem>/bge_index_<index_type>
• Contriever → <output>/<stem>/contriever_index_<index_type>
• ColBERT → <output>/<stem>/colbert_index_<index_type>

BM25

rankify-index index data/wikipedia_10k.jsonl \
  --retriever bm25 \
  --output ./indices

DPR（默认单编码器）

# 维基百科风格
rankify-index index data/wikipedia_100.jsonl \
  --retriever dpr \
  --encoder facebook/dpr-ctx_encoder-single-nq-base \
  --batch_size 16 --device cuda \
  --output ./indices

# MS MARCO
rankify-index index data/msmarco_100.jsonl \
  --retriever dpr --index_type msmarco \
  --encoder facebook/dpr-ctx_encoder-single-nq-base \
  --batch_size 16 --device cuda \
  --output ./indices

ANCE

rankify-index index data/wikipedia_100.jsonl \
  --retriever ance \
  --encoder castorini/ance-dpr-context-multi \
  --batch_size 16 --device cuda \
  --output ./indices

Contriever

rankify-index index data/wikipedia_100.jsonl \
  --retriever contriever \
  --encoder facebook/contriever-msmarco \
  --batch_size 16 --device cuda \
  --output ./indices

ColBERT

rankify-index index data/wikipedia_100.jsonl \
  --retriever colbert \
  --batch_size 32 --device cuda \
  --output ./indices

BGE

rankify-index index data/wikipedia_100.jsonl \
  --retriever bge \
  --encoder BAAI/bge-large-en-v1.5 \
  --batch_size 16 --device cuda \
  --output ./indices

---

2️⃣ 执行检索

要使用 Rankify 执行检索，您可以选择多种检索方法，例如 BM25、DPR、ANCE、Contriever、ColBERT、BGE、Sbert、Nomic、Instructor、DiverRetriever、SRF、E5、RaDeR、M2、GritLM、ReasonEmbed、ReasonIR 和 BGEReasoner。

第一步：设置示例查询

示例：在样本查询上执行检索

from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.retrievers.retriever import Retriever

# 示例文档
documents = [
    Document(question=Question("《虎胆龙威》的演员阵容？"), answers=Answer([
            "杰·考特尼",
            "塞巴斯蒂安·科赫",
            "拉迪沃耶·布克维奇",
            "尤莉娅·斯尼吉尔",
            "谢尔盖·科列斯尼科夫",
            "玛丽·伊丽莎白·温斯顿",
            "布鲁斯·威利斯"
        ]), contexts=[]),
    Document(question=Question("谁写了《哈姆雷特》？"), answers=Answer(["莎士比亚"]), contexts=[])
]

第二步：选择检索选项

选项 A： 使用 index_type（例如 "wiki"、"msmarco"）加载预先计算好的 FAISS 索引。

# 维基百科上的 BM25 检索
bm25_retriever_wiki = Retriever(method="bm25", n_docs=5, index_type="wiki")

# MS MARCO 上的 BM25 检索
bm25_retriever_msmarco = Retriever(method="bm25", n_docs=5, index_type="msmarco")


# 维基百科上的 DPR（多编码器）检索
dpr_retriever_wiki = Retriever(method="dpr", model="dpr-multi", n_docs=5, index_type="wiki")

# MS MARCO 上的 DPR（多编码器）检索
dpr_retriever_msmarco = Retriever(method="dpr", model="dpr-multi", n_docs=5, index_type="msmarco")


# 维基百科上的 DPR（单编码器）检索
dpr_retriever_wiki = Retriever(method="dpr", model="dpr-single", n_docs=5, index_type="wiki")

# MS MARCO 上的 DPR（单编码器）检索
dpr_retriever_msmarco = Retriever(method="dpr", model="dpr-single", n_docs=5, index_type="msmarco")


# 维基百科上的 ANCE 检索
ance_retriever_wiki = Retriever(method="ance", model="ance-multi", n_docs=5, index_type="wiki")

# MS MARCO 上的 ANCE 检索
ance_retriever_msmarco = Retriever(method="ance", model="ance-multi", n_docs=5, index_type="msmarco")


# 维基百科上的 Contriever 检索
contriever_retriever_wiki = Retriever(method="contriever", model="facebook/contriever-msmarco", n_docs=5, index_type="wiki")

# MS MARCO 上的 Contriever 检索
contriever_retriever_msmarco = Retriever(method="contriever", model="facebook/contriever-msmarco", n_docs=5, index_type="msmarco")


# 维基百科上的 ColBERT 检索
colbert_retriever_wiki = Retriever(method="colbert", model="colbert-ir/colbertv2.0", n_docs=5, index_type="wiki")

# MS MARCO 上的 ColBERT 检索
colbert_retriever_msmarco = Retriever(method="colbert", model="colbert-ir/colbertv2.0", n_docs=5, index_type="msmarco")


# 维基百科上的 BGE 检索
bge_retriever_wiki = Retriever(method="bge", model="BAAI/bge-large-en-v1.5", n_docs=5, index_type="wiki")

# MS MARCO 上的 BGE 检索
bge_retriever_msmarco = Retriever(method="bge", model="BAAI/bge-large-en-v1.5", n_docs=5, index_type="msmarco")


# 维基百科上的 Hyde 检索
hyde_retriever_wiki = Retriever(method="hyde", n_docs=5, index_type="wiki", api_key=OPENAI_API_KEY )

# MS MARCO 上的 Hyde 检索
hyde_retriever_msmarco = Retriever(method="hyde", n_docs=5, index_type="msmarco", api_key=OPENAI_API_KEY)

选项 B： 使用自定义数据集并自动缓存进行检索。

这些模型均基于最新 70 亿+ 参数模型，所有以下模型仅适用于自定义数据集。只需将 .jsonl 文件传递给 corpus_path，确保您的数据映射到所需的 id: 和 text: 字段，模型将在首次运行时嵌入并本地缓存数据。

# 在Diver框架中实现的双编码器（11种可配置模型，由model_id指定）
bge_large_retriever = Retriever(method="diver-dense", model_id="bge", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

sbert_retriever = Retriever(method="diver-dense", model_id="sbert", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

inst_l_retriever = Retriever(method="diver-dense", model_id="inst-l", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

inst_xl_retriever = Retriever(method="diver-dense", model_id="inst-xl", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

sfr_retriever = Retriever(method="diver-dense", model_id="sf", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

e5_retriever = Retriever(method="diver-dense", model_id="e5", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

contriever_retriever = Retriever(method="diver-dense", model_id="contriever", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

m2_retriever = Retriever(method="diver-dense", model_id="m2", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

grit_retriever = Retriever(method="diver-dense", model_id="grit", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

rader_retriever = Retriever(method="diver-dense", model_id="rader", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

nomic_retriever = Retriever(method="diver-dense", model_id="nomic", corpus_path="data/my_corpus.jsonl", encode_batch_size=4, n_docs=5)

diver_retriever = Retriever(method="diver-dense", model_id="diver", corpus_path="data/my_corpus.jsonl", encode_batch_size=4, n_docs=5)


# Reasonir检索
reasonir_retriever = Retriever(method="reasonir", corpus_path="data/my_corpus.jsonl", encode_batch_size=4, n_docs=5)


# ReasonEmbed检索（3种可配置模型，由model_id指定）
reasonembed_qwen8b_retriever = Retriever(method="reason-embed", model_id="qwen3-8b", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

reasonembed_llama8b_retriever = Retriever(method="reason-embed", model_id="qwen3-4b", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

reasonembed_qwen4b_retriever = Retriever(method="reason-embed", model_id="llama-8b", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)


# BgeReasonEmbed检索
bge_reasoner_retriever = Retriever(method="bge-reasoner-embed", corpus_path="data/my_corpus.jsonl", encode_batch_size=8, n_docs=5)

检索示例：在BRIGHT基准测试上使用ReasonIR（生物查询）

本示例演示了如何在推理密集型的BRIGHT基准测试上评估reasonir/ReasonIR-8B模型。

from datasets import load_dataset
from rankify.dataset.dataset import Document, Question, Answer
from rankify.retrievers.retriever import Retriever

corpus_path = "bright_biology_corpus.jsonl"       # 用于检索的.jsonl语料库

docs = load_dataset("xlangai/BRIGHT", "documents", split="biology")
docs.to_json(corpus_path, force_ascii=False)  

queries = load_dataset("xlangai/BRIGHT", "examples", split="biology")
    
documents = []
for item in queries:
    doc = Document(id=item["id"], 
                   question=Question(question=item["query"]), 
                   answers=Answer(answers=item.get("gold_ids", [])))
    documents.append(doc)
    
retriever = Retriever(
    method="reasonir",            # 使用ReasonIR检索器
    n_docs=3,                     # 每个查询检索前3个文档
    corpus_path=corpus_path,      # 刚刚创建的JSONL文件路径
    text_field="content",         # BRIGHT使用'content'而非'text'
    batch_size=4,
)

results = retriever.retrieve(documents)

第三步：执行并查看结果

运行检索

定义好检索器后，可以使用以下代码检索文档：

retrieved_documents = bm25_retriever_wiki.retrieve(documents)

for i, doc in enumerate(retrieved_documents):
    print(f"\n文档 {i+1}:")
    print(doc)

---

3️⃣ 运行重排序

Rankify支持多种重排序模型。以下是每种模型的使用示例。

示例：对文档进行重排序

from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.models.reranking import Reranking

# 示例文档设置
question = Question("托马斯·爱迪生是什么时候发明电灯泡的？")
answers = Answer(["1879"])
contexts = [
    Context(text="首尔大学发生雷击事件", id=1),
    Context(text="托马斯·爱迪生试图为汽车发明一种装置但失败了", id=2),
    Context(text="咖啡对减肥有好处", id=3),
    Context(text="托马斯·爱迪生于1879年发明了电灯泡", id=4),
    Context(text="托马斯·爱迪生从事电力相关工作", id=5),
]
document = Document(question=question, answers=answers, contexts=contexts)

# 初始化重排序器
reranker = Reranking(method="monot5", model_name="monot5-base-msmarco")

# 应用重排序
reranker.rank([document])

# 打印重新排序后的上下文
for context in document.reorder_contexts:
    print(f"  - {context.text}")

不同重排序模型的使用示例

# UPR
model = Reranking(method='upr', model_name='t5-base')

# 基于API的重排序器
model = Reranking(method='apiranker', model_name='voyage', api_key='your-api-key')
model = Reranking(method='apiranker', model_name='jina', api_key='your-api-key')
model = Reranking(method='apiranker', model_name='mixedbread.ai', api_key='your-api-key')

# Blender重排序器
model = Reranking(method='blender_reranker', model_name='PairRM')

# ColBERT重排序器
model = Reranking(method='colbert_ranker', model_name='Colbert')

# EchoRank
model = Reranking(method='echorank', model_name='flan-t5-large')

# First Ranker
model = Reranking(method='first_ranker', model_name='base')

# FlashRank
model = Reranking(method='flashrank', model_name='ms-marco-TinyBERT-L-2-v2')

# InContext重排序器
Reranking(method='incontext_reranker', model_name='llamav3.1-8b')

# InRanker
model = Reranking(method='inranker', model_name='inranker-small')

# ListT5
model = Reranking(method='listt5', model_name='listt5-base')

# LiT5 Distill
model = Reranking(method='lit5distill', model_name='LiT5-Distill-base')

# LiT5 Score
model = Reranking(method='lit5score', model_name='LiT5-Distill-base')

# LLM Layerwise Ranker
model = Reranking(method='llm_layerwise_ranker', model_name='bge-multilingual-gemma2')

# LLM2Vec
model = Reranking(method='llm2vec', model_name='Meta-Llama-31-8B')

# MonoBERT
model = Reranking(method='monobert', model_name='monobert-large')

# MonoT5
Reranking(method='monot5', model_name='monot5-base-msmarco')

# RankGPT
model = Reranking(method='rankgpt', model_name='llamav3.1-8b')

# RankGPT API
model = Reranking(method='rankgpt-api', model_name='gpt-3.5', api_key="gpt-api-key")
model = Reranking(method='rankgpt-api', model_name='gpt-4', api_key="gpt-api-key")
model = Reranking(method='rankgpt-api', model_name='llamav3.1-8b', api_key="together-api-key")
model = Reranking(method='rankgpt-api', model_name='claude-3-5', api_key="claude-api-key")

# RankT5
model = Reranking(method='rankt5', model_name='rankt5-base')

# Sentence Transformer Reranker
model = Reranking(method='sentence_transformer_reranker', model_name='all-MiniLM-L6-v2')
model = Reranking(method='sentence_transformer_reranker', model_name='gtr-t5-base')
model = Reranking(method='sentence_transformer_reranker', model_name='sentence-t5-base')
model = Reranking(method='sentence_transformer_reranker', model_name='distilbert-multilingual-nli-stsb-quora-ranking')
model = Reranking(method='sentence_transformer_reranker', model_name='msmarco-bert-co-condensor')

# SPLADE
model = Reranking(method='splade', model_name='splade-cocondenser')

# Transformer Ranker
model = Reranking(method='transformer_ranker', model_name='mxbai-rerank-xsmall')
model = Reranking(method='transformer_ranker', model_name='bge-reranker-base')
model = Reranking(method='transformer_ranker', model_name='bce-reranker-base')
model = Reranking(method='transformer_ranker', model_name='jina-reranker-tiny')
model = Reranking(method='transformer_ranker', model_name='gte-multilingual-reranker-base')
model = Reranking(method='transformer_ranker', model_name='nli-deberta-v3-large')
model = Reranking(method='transformer_ranker', model_name='ms-marco-TinyBERT-L-6')
model = Reranking(method='transformer_ranker', model_name='msmarco-MiniLM-L12-en-de-v1')

# TwoLAR
model = Reranking(method='twolar', model_name='twolar-xl')

# Vicuna Reranker
model = Reranking(method='vicuna_reranker', model_name='rank_vicuna_7b_v1')

# Zephyr Reranker
model = Reranking(method='zephyr_reranker', model_name='rank_zephyr_7b_v1_full')

---

4️⃣ 使用生成器模块

Rankify 提供了生成器模块，用于检索增强生成（RAG），可将检索到的文档与 OpenAI、LiteLLM、vLLM 和 Hugging Face 等生成模型集成。其模块化设计允许轻松添加新的 RAG 方法 和 端点，从而无缝尝试零样本 RAG、思维链 RAG 和基于 FiD 的 RAG 等方法。以下是一些使用不同 RAG 方法以及如何引入不同 LLM 端点的示例。

请注意，要使用基于 API 的端点（OpenAI、LiteLLM），您需要指定 api-key。请参阅下面的示例了解如何操作。

使用不同 RAG 方法和后端的示例

# 零样本与 Huggingface 端点
generator = Generator(method="zero-shot", model_name='meta-llama/Meta-Llama-3.1-8B-Instruct', backend="huggingface")

# 基本 RAG 与 LiteLLM 端点
generator = Generator(method="basic-rag", model_name='ollama/mistral', backend="litellm", api_key=api_key)

# 思维链 RAG 与 vLLM 端点
generator = Generator(method="chain-of-thought-rag", model_name='mistralai/Mistral-7B-v0.1', backend="vllm")

# 上下文内 RALM 与 OpenAI 端点
generator = Generator(method="in-context-ralm", model_name='gpt-3.5-turbo', backend="openai", api_keys=[api_key])

无需 API 推理的使用示例

from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.generator.generator import Generator

# 定义问题和答案
question = Question("奥地利的首都是什么？")
answers = Answer("")
contexts = [
    Context(id=1, title="法国", text="法国的首都巴黎。", score=0.9),
    Context(id=2, title="德国", text="柏林是德国的首都。", score=0.5)
]

# 构建文档
doc = Document(question=question, answers=answers, contexts=contexts)

# 初始化生成器（例如 Meta Llama）
generator = Generator(method="basic-rag", model_name='meta-llama/Meta-Llama-3.1-8B-Instruct', backend="huggingface")

# 生成答案
generated_answers = generator.generate([doc])
print(generated_answers)  # 输出: ["巴黎"]

带 API 推理的使用示例

将您的 API 密钥保存在 .env.local 文件中，您可以通过以下列出的方法访问它们：

# 在 .env.local 中：
OPENAI_API_KEY=your-api-key
LITELLM_API_KEY=your-api-key

使用

# 加载 LiteLLM api-key
api_key = get_litellm_api_key()
# 加载 OpenAI api-key
api_key = get_openai_api_key()

使用 LiteLLM 的完整示例：

from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.generator.generator import Generator
from rankify.utils.models.rank_llm.rerank.api_keys import get_litellm_api_key

# 定义问题和答案
question = Question("法国的首都是什么？")
answers = Answer([""])
contexts = [
    Context(id=1, title="法国", text="法国的首都巴黎。", score=0.9),
    Context(id=2, title="德国", text="柏林是德国的首都。", score=0.5)
]

# 构建文档
doc = Document(question=question, answers=answers, contexts=contexts)

# 加载 api-key
api_key = get_litellm_api_key()

# 初始化生成器（例如 Meta Llama）
generator = Generator(method="basic-rag", model_name='ollama/mistral', backend="litellm", api_key=api_key)

# 生成答案
generated_answers = generator.generate([doc])
print(generated_answers)  # 输出: ["巴黎"]

---

5️⃣ 使用指标评估

Rankify 提供了内置的评估指标，用于检索、重排序和检索增强生成（RAG）。这些指标有助于评估检索到的文档质量、排序模型的有效性以及生成答案的准确性。

评估生成的答案

您可以比较生成的答案与真实答案，以评估检索增强生成（RAG）结果的质量。

from rankify.metrics.metrics import Metrics
from rankify.dataset.dataset import Dataset

# 加载数据集
dataset = Dataset('bm25', 'nq-test', 100)
documents = dataset.download(force_download=False)

# 初始化生成器
generator = Generator(method="in-context-ralm", model_name='meta-llama/Llama-3.1-8B')

# 生成答案
generated_answers = generator.generate(documents)

# 评估生成的答案
metrics = Metrics(documents)
print(metrics.calculate_generation_metrics(generated_answers))

评估检索性能

# 计算重排序前的检索指标
metrics = Metrics(documents)
before_ranking_metrics = metrics.calculate_retrieval_metrics(ks=[1, 5, 10, 20, 50, 100], use_reordered=False)

print(before_ranking_metrics)

评估重排序后的结果

# 计算重排序后的检索指标
after_ranking_metrics = metrics.calculate_retrieval_metrics(ks=[1, 5, 10, 20, 50, 100], use_reordered=True)
print(after_ranking_metrics)

🧪 BEIR & TREC DL19/DL20 与 BM25

Rankify 提供便捷的钩子，可在 BEIR 任务和 TREC DL'19/20 上运行 BM25 基线，并使用 TREC 风格指标（nDCG、MAP、MRR）进行评估。

快速入门（单个数据集）

from rankify.dataset.dataset import Dataset
from rankify.metrics.metrics import Metrics

# 下载预检索的 BM25 结果（每个查询的 top-k）
docs = Dataset('bm25', 'dl19', n_docs=1000).download(force_download=False)

# 使用 TREC 指标进行评估（此处默认显示 nDCG@10/100）
metrics = Metrics(docs)
print(metrics.calculate_trec_metrics(ndcg_cuts=[10, 100], use_reordered=False))

注意

• 支持的名称包括 dl19、dl20，以及以 beir- 前缀命名的 BEIR 任务，例如： beir-arguana、beir-covid、beir-dbpedia、beir-fever、beir-fiqa、beir-news、 beir-nfc、beir-quora、beir-robust04、beir-scidocs、beir-scifact、beir-signal、beir-touche。
• 如果需要明确选择 qrel 文件，请将 qrel=name.replace("beir-", "") 传递给 calculate_trec_metrics。

批量处理 BEIR 和 DL 数据集

from rankify.dataset.dataset import Dataset
from rankify.metrics.metrics import Metrics

BEIR_TASKS = [
    "beir-arguana", "beir-covid", "beir-dbpedia", "beir-fever", "beir-fiqa", "beir-news",
    "beir-nfc", "beir-quora", "beir-robust04", "beir-scidocs", "beir-scifact",
    "beir-signal", "beir-touche",
]

for name in ["dl19", "dl20", *BEIR_TASKS]:
    docs = Dataset('bm25', name, n_docs=100).download(force_download=False)
    m = Metrics(docs)
    res = m.calculate_trec_metrics(ndcg_cuts=[10, 100], use_reordered=False)
    print(name, res)

（可选）添加重排序器并进行评估

from rankify.models.reranking import Reranking
from rankify.dataset.dataset import Dataset
from rankify.metrics.metrics import Metrics

name = "beir-arguana"
docs = Dataset('bm25', name, n_docs=100).download(force_download=False)
reranker = Reranking(method='transformer_ranker', model_name='bge-reranker-base')
reranker.rank(docs)

m = Metrics(docs)
print("之前:", m.calculate_trec_metrics(ndcg_cuts=[10, 100], use_reordered=False))
print("之后:", m.calculate_trec_metrics(ndcg_cuts=[10, 100], use_reordered=True))

📏 使用 RAGAS 评估 RAG

Rankify 提供了一个轻量级封装，围绕 ragas 构建，让生成答案的质量评估变得简单而灵活——无论您是用本地 HF 模型还是 OpenAI 等托管 API 进行判断。您可以运行 快速默认值，挑选特定指标，或在计算资源紧张时模拟预测结果。

✅ 安装

# Rankify RAG 的核心依赖
pip install bert-score
pip install ragas
pip install langchain_huggingface
pip install rouge-score

import torch
from rankify.dataset.dataset import Document, Question, Answer, Context
from rankify.generator.generator import Generator
from rankify.metrics.generator_metrics import GeneratorMetrics
from rankify.metrics.ragas_bridge import RagasModels

# 1) 构建一个小型文档
question = Question("法国的首都是什么？")
answers  = Answer(["巴黎"])
contexts = [
    Context(id=1, title="法国",   text="法国的首都就是巴黎。", score=0.9),
    Context(id=2, title="德国",  text="柏林是德国的首都。", score=0.5),
]
doc = Document(question=question, answers=answers, contexts=contexts)

# 2) 生成答案（或跳过并提供您自己的预测列表）
generator   = Generator(method="basic-rag",
                        model_name="meta-llama/Meta-Llama-3.1-8B-Instruct",
                        backend="huggingface",
                        torch_dtype=torch.float16)
predictions = generator.generate([doc])
print("生成的结果:", predictions)

# 3) 使用 RAGAS 进行评估（HF 判断器）
gen_metrics = GeneratorMetrics([doc])

ragas_hf = RagasModels(
    llm_kind="hf",
    llm_name="meta-llama/Meta-Llama-3.1-8B-Instruct",
    embeddings_kind="hf",
    embeddings_name="sentence-transformers/all-MiniLM-L6-v2",
    torch_dtype="float16",
    max_new_tokens=256,  # 输出越短，速度越快且成本越低
    timeout=180,         # 每次指标调用的秒数
    max_retries=1,
    max_workers=2,       # 在有限硬件上保持较小规模
)

# (A) 快速默认值
scores_fast = gen_metrics.all(predictions, ragas_models=ragas_hf)
print("RAGAS（快速）:", scores_fast)

# (B) 挑选特定指标
scores_specific = gen_metrics.ragas_generator(
    predictions,
    judge=ragas_hf,
    metrics=["faithfulness", "response_relevancy", "context_precision", "context_recall"],
)
print("RAGAS（特定）:", scores_specific)

# (C) OpenAI 判断器（如果您有 API 密钥，速度会快很多）
ragas_openai = RagasModels(llm_kind="openai", llm_name="gpt-4o-mini", timeout=30)
scores_openai = gen_metrics.all(predictions, ragas_models=ragas_openai)
print("RAGAS（OpenAI）:", {k: v for k, v in scores_openai.items() if k.startswith("ragas_")})

📜 支持的模型

1️⃣ 索引

• ✅ 维基百科
• ✅ MS-MARCO
• 🕒 在线搜索

1️⃣ 检索器

• ✅ BM25
• ✅ DPR
• ✅ ColBERT
• ✅ ANCE
• ✅ BGE
• ✅ Contriever
• ✅ BPR
• ✅ HYDE
• ✅ SFR
• ✅ E5
• ✅ GritLM
• ✅ M2
• ✅ Nomic
• ✅ Instructor
• ✅ RaDeR
• ✅ ReasonIR
• ✅ BGE-Reasoner
• ✅ ReasonEmbed
• ✅ DiverRetriever
• 🕒 RepLlama
• 🕒 coCondenser
• 🕒 Spar
• 🕒 Dragon
• 🕒 混合

---

2️⃣ 重排序器

• ✅ 交叉编码器
• ✅ RankGPT
• ✅ RankGPT-API
• ✅ MonoT5
• ✅ MonoBert
• ✅ RankT5
• ✅ ListT5
• ✅ LiT5Score
• ✅ LiT5Dist
• ✅ Vicuna 重排序器
• ✅ Zephyr 重排序器
• ✅ 基于句子转换器的
• ✅ FlashRank 模型
• ✅ 基于 API 的重排序器
• ✅ ColBERT 重排序器
• ✅ LLM 分层排名器
• ✅ Splade 重排序器
• ✅ UPR 重排序器
• ✅ Inranker 重排序器
• ✅ Transformer 重排序器
• ✅ FIRST 重排序器
• ✅ Blender 重排序器
• ✅ LLM2VEC 重排序器
• ✅ ECHO 重排序器
• ✅ 上下文内重排序器
• 🕒 DynRank
• 🕒 ASRank
• 🕒 RankLlama

---

3️⃣ 生成器

RAG 方法

• ✅ 零样本
• ✅ 基础 RAG
• ✅ 思维链 RAG
• ✅ 解码器中的融合（FiD）与 T5
• ✅ 上下文学习 RALM
• 🕒 自一致性 RAG
• 🕒 检索思维链

LLM 端点

• ✅ Hugging Face
• ✅ vLLM
• ✅ LiteLLM
• ✅ OpenAI

---

✨ 功能

• 🔥 统一框架：将检索、重排序和**检索增强生成（RAG）**整合到一个模块化工具包中。
• 📚 丰富的数据集支持：包含40 多个基准数据集，并附带预检索文档，方便无缝实验。
• 🧲 多样化的检索方法：支持BM25、DPR、ANCE、BPR、ColBERT、BGE、Contriever、SFR、E5、GritLM、M2、Nomic、Instructor、RaDeR、ReasonIR、BGE-Reasoner 和 ReasonEmbed，提供灵活的检索策略。
• 🎯 强大的重排序功能：实现24 种先进模型，包含41 种子方法，优化排名性能。
• 🛠 预构建索引：提供Wikipedia 和 MS MARCO 语料库，消除索引开销，加快检索速度。
• 🔮 无缝 RAG 集成：可与Hugging Face、OpenAI、vLLM、LiteLLM 等后端配合，支持GPT、LLAMA、T5 和解码器融合（FiD）等推理模型，实现多种检索增强生成方法。
• 🛠 可扩展与模块化：轻松集成自定义数据集、检索器、排名模型和 RAG 流水线。
• 📊 内置评估套件：包括检索、排名和 RAG 指标，用于稳健的基准测试。
• 📖 用户友好的文档：访问详细的**📖 在线文档、示例笔记本和教程**，便于快速上手。

🔍 路线图

Rankify 仍在开发中，这是我们的首个发布版本（v0.1.0）。尽管它已支持广泛的检索、重排序和 RAG 技术，我们正在积极增强其功能，增加更多检索器、排名器、数据集和特性。

📖 文档

如需完整 API 文档，请访问 Rankify 文档。

---

💡 贡献

按照以下步骤参与开发：

1. 将此仓库 Fork 到你的 GitHub 账户。

2. 创建一个新分支用于你的功能或修复：

   git checkout -b feature/YourFeatureName
   

3. 进行修改并提交：

   git commit -m "Add YourFeatureName"
   

4. 将更改推送到你的分支：

   git push origin feature/YourFeatureName
   

5. 提交 Pull Request以提出你的更改。

感谢你帮助让这个项目变得更好！

---

🌐 社区贡献

中文社区资源现已上线！

特别感谢 Xiumao 撰写了两篇关于 Rankify 的优秀中文博客文章：

• 📘 Rankify 简介
• 📘 深入解析 Rankify 中的重排序模型

这些文章经过高度流量优化，在中国学术界和开发者圈中广受推荐。

我们更新了 中文版，以反映这些博客贡献，同时保留原始内容——感谢 Xiumao 的持续支持！

:bookmark: 许可证

Rankify 采用 Apache-2.0 许可证——详情请参阅 LICENSE 文件。

🙏 致谢

我们衷心感谢以下库，它们为 Rankify 的开发做出了巨大贡献：

• Diver —— 提供密集检索器路由和缓存逻辑的参考实现，用于集成各种双编码器。
  🔗 GitHub 仓库

• Rerankers —— 强大的 Python 库，用于集成各种重排序方法。
  🔗 GitHub 仓库

• Pyserini —— 支持 BM25 基础检索，并与稀疏/密集检索器集成的工具包。
  🔗 GitHub 仓库

• FlashRAG —— 用于检索增强生成（RAG）研究的模块化框架。
  🔗 GitHub 仓库

:star2: 引用

如果您的研究需要，请引用我们的论文：

@article{abdallah2025rankify,
  title={Rankify：用于检索、重排序和检索增强生成的全面 Python 工具包},
  author={Abdallah, Abdelrahman 和 Mozafari, Jamshid 和 Piryani, Bhawna 和 Ali, Mohammed 和 Jatowt, Adam},
  journal={arXiv 预印本 arXiv:2502.02464},
  year={2025}
}

星数历史

Rankify 快速上手指南

环境准备

• Python 版本：3.10 或 3.11
• 推荐系统：Linux / macOS（Windows 可用 WSL2）
• GPU 支持（可选）：NVIDIA 显卡 + CUDA 12.4/12.6，显著提升检索与重排序性能
• 前置依赖：确保已安装 conda 或 pip

推荐使用 Conda 环境管理，避免依赖冲突。

安装步骤

1. 创建并激活虚拟环境

conda create -n rankify python=3.10
conda activate rankify

2. 安装 PyTorch（推荐 GPU 版本）

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

若无 GPU，可替换为 cu118 版本：--index-url https://download.pytorch.org/whl/cu118

3. 安装 Rankify（推荐完整版）

pip install "rankify[all]"

国内用户可使用清华源加速：

pip install "rankify[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

如需仅安装特定模块：

• 检索：pip install "rankify[retriever]"
• 重排序：pip install "rankify[reranking]"
• RAG 生成：pip install "rankify[rag]"

基本使用

一键 RAG 流水线（推荐）

from rankify import pipeline

# 使用默认配置执行 RAG
rag = pipeline("rag")
answers = rag("机器学习是什么？", documents)

# 自定义检索器、重排序器和生成器
rag = pipeline(
    "rag",
    retriever="bge",           # 使用 BGE 检索器
    reranker="flashrank",      # 使用 FlashRank 重排序
    generator="basic-rag"
)
answers = rag("什么是人工智能？", documents)

可用流水线类型：

• pipeline("search")：仅检索
• pipeline("rerank")：检索 + 重排序
• pipeline("rag")：完整 RAG 流程（检索 → 重排序 → 生成）

文档：Pipeline API 文档