RankLLM

新闻

• [2026.03.26] RankLLM 现在支持新的 rank-llm 命令行界面 (CLI)。
• [2025.08.25] 添加了对 OpenRouter API 的支持 - 发布 v0.25.7
• [2025.07.23] 添加了使用 YAML 文件自定义提示模板的支持 - 发布 v0.25.0。现在只需几行代码即可集成您自己的提示和语言模型。请查看 Reasonrank 集成 作为示例。
• [2025.05.25] 我们的 RankLLM 资源论文已被 SIGIR 2025 接受！🎉🎉🎉

概述

我们提供一系列重排序器——包括单点模型如 MonoT5、成对模型如 DuoT5，以及以开源 LLM 为重点的列表式模型，这些模型与 vLLM、SGLang 或 TensorRT-LLM 兼容。我们还支持 RankGPT 和 RankGemini 变体，它们是专有的列表式重排序器。此外，我们还支持仅使用第一个 token 的 logits 进行重排序，以提高推理效率。本仓库中的部分代码借鉴自 RankGPT、PyGaggle 和 LiT5！

发布版本

current_version = "0.25.7"

内容

1. 安装
2. 快速入门
3. 端到端运行与 2CR
4. 模型库
5. 训练
6. 社区贡献
7. 参考文献与引用
8. 致谢

📟 安装

uv 是本仓库的标准贡献工作流。现有的 conda 和 pip 路径仍然可用作备用。

安装 uv

使用 Astral 的官方安装程序安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

先决条件

• 仅当您计划通过 rank-llm[pyserini] 使用检索或评估流程时，才需要安装 Java 21。不支持 JDK 11。
• 如果您希望获得比默认 Python 包解析更优的 GPU 优化构建版本，则需单独安装 CUDA 特定的 PyTorch wheel。

开发环境安装

对于开发或获取最新功能，请创建一个仓库本地的虚拟环境：

git clone https://github.com/castorini/rank_llm.git
cd rank_llm
uv python install 3.11
uv venv --python 3.11
source .venv/bin/activate
uv sync --group dev

如果您不想激活虚拟环境，可以通过 uv run 来执行命令，例如 uv run python -m unittest discover test。

可选扩展

仅安装您需要的堆栈：

uv sync --group dev --extra <extra>

将 <extra> 替换为下方功能矩阵中的其中一个扩展。您可以重复使用 --extra 来在一个环境中组合多个堆栈。

功能矩阵

工作流程	扩展	备注
托管的 OpenAI 或 OpenRouter 重排序器	openai	包含 python-dotenv 和 tiktoken
托管的 Gemini 重排序器	genai	gemini 是别名
所有托管提供商的重排序器	cloud	安装 openai 和 genai
本地的 Hugging Face 和 PyTorch 重排序器	local	安装 torch 和 transformers，用于 MonoT5、DuoT5、MonoELECTRA 及相关本地路径
Pyserini 检索和评估	pyserini	需要 Java 21
轻量级 HTTP API 依赖	api	安装 FastAPI、Flask 和 Uvicorn，而不包含较重的检索或推理堆栈
MCP 服务器依赖	mcp	引入打包好的 serve mcp 依赖集，包括 Pyserini 和模型服务后端
使用 vLLM 的开源模型进行列表式重排序	vllm	基于 local 并添加 vLLM 后端
批量 SGLang 推理	sglang	必要时需单独安装 flashinfer
批量 TensorRT-LLM 推理	tensorrt-llm	必要时需单独安装 flash-attn
完整的 HTTP 和 MCP 服务器捆绑包	server	api 和 mcp 扩展的集合
微调和训练脚本	training	将仅用于训练的依赖项排除在基础安装之外
全部	all	所有扩展的集合

PyPI 安装

创建一个隔离的虚拟环境并安装已发布的包：

uv venv --python 3.11
source .venv/bin/activate
uv pip install rank-llm

备用 conda / pip 流程

如果您想继续使用 conda：

conda create -n rankllm python=3.11 -c conda-forge -y
conda activate rankllm
pip install -e .

然后安装您需要的可选堆栈，例如：

pip install -e ".[<extra>]"

将 <extra> 替换为下方功能矩阵中的其中一个扩展。您可以根据需要组合多个扩展，例如 pip install -e ".[openai,api]"。

请记住，当这些堆栈需要时，务必为 sglang 后端安装 flashinfer，为优化的 TensorRT-LLM 或训练流程安装 flash-attn。

pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
pip install flash-attn --no-build-isolation

⏳ 快速入门

打包好的 rank-llm 命令是本仓库的标准命令行界面。 src/rank_llm/scripts/ 目录下的旧版脚本仍然可用，但现在它们只是对同一命令行界面的兼容性封装。

rank-llm rerank --model-path castorini/rank_zephyr_7b_v1_full --dataset dl20 \
  --retrieval-method bm25 --top-k-candidates 100

rank-llm prompt list
rank-llm view demo_outputs/rerank_results.jsonl
rank-llm evaluate --model-name castorini/rank_zephyr_7b_v1_full
rank-llm serve http --model-path castorini/rank_zephyr_7b_v1_full --port 8082
rank-llm serve mcp --transport stdio

以下代码片段是对从 DL19 查询中检索、重排序、评估以及对前100篇检索文档进行调用分析的最小化演示。在该示例中，使用 BM25 作为检索器，RankZephyr 作为重排序器。更多示例片段可在 src/rank_llm/demo 目录下运行。

from pathlib import Path

from rank_llm.analysis.response_analysis import ResponseAnalyzer
from rank_llm.data import DataWriter
from rank_llm.evaluation.trec_eval import EvalFunction
from rank_llm.rerank import Reranker, get_openai_api_key
from rank_llm.rerank.listwise import (
    SafeOpenai,
    VicunaReranker,
    ZephyrReranker,
)
from rank_llm.retrieve.retriever import RetrievalMethod, Retriever
from rank_llm.retrieve.topics_dict import TOPICS

# -------- 检索 --------

# 默认使用 BM25 检索前100个候选文档。
dataset_name = "dl19"
retrieved_results = Retriever.from_dataset_with_prebuilt_index(dataset_name)

# 用户可以指定其他检索方法和检索的候选文档数量。
# retrieved_results = Retriever.from_dataset_with_prebuilt_index(
#     dataset_name, RetrievalMethod.SPLADE_P_P_ENSEMBLE_DISTIL, k=50
# )
# ---------------------------

# --------- 重排序 ----------

# Rank Zephyr 模型
reranker = ZephyrReranker()

# Rank Vicuna 模型
# reranker = VicunaReranker()

# RankGPT
# model_coordinator = SafeOpenai("gpt-4o-mini", 4096, keys=get_openai_api_key())
# reranker = Reranker(model_coordinator)

kwargs = {"populate_invocations_history": True}
rerank_results = reranker.rerank_batch(requests=retrieved_results, **kwargs)
# ---------------------------

# ------- 评估 --------

# 评估检索结果。
topics = TOPICS[dataset_name]
ndcg_10_retrieved = EvalFunction.from_results(retrieved_results, topics)
print(ndcg_10_retrieved)

# 评估重排序结果。
ndcg_10_rerank = EvalFunction.from_results(rerank_results, topics)
print(ndcg_10_rerank)

# 默认评估指标为 ndcg@10，也可以指定其他值：
# eval_args = ["-c", "-m", "map_cut.100", "-l2"]
# map_100_rerank = EvalFunction.from_results(rerank_results, topics, eval_args)
# print(map_100_rerank)

# eval_args = ["-c", "-m", "recall.20"]
# recall_20_rerank = EvalFunction.from_results(rerank_results, topics, eval_args)
# print(recall_20_rerank)

# ---------------------------

# --- 分析调用情况 ---
analyzer = ResponseAnalyzer.from_inline_results(rerank_results)
error_counts = analyzer.count_errors(verbose=True)
print(error_counts)
# ---------------------------

# ------ 保存结果 -------
writer = DataWriter(rerank_results)
Path(f"demo_outputs/").mkdir(parents=True, exist_ok=True)
writer.write_in_jsonl_format(f"demo_outputs/rerank_results.jsonl")
writer.write_in_trec_eval_format(f"demo_outputs/rerank_results.txt")
writer.write_inference_invocations_history(
    f"demo_outputs/inference_invocations_history.json"
)
# ---------------------------

端到端运行与2CR

如果您有兴趣端到端地运行检索和重排序，或复现【参考文献】中的结果，rank-llm rerank 是标准命令。run_rank_llm.py 仍作为旧版自动化工具的兼容性封装而保留。

我们两步即可复现的完整命令列表，分别在 MS MARCO V1 和 MS MARCO V2 页面上提供，对应 DL19、DL20 和 DL21-23 数据集。未来，我们计划在 2CR 页面上覆盖更多数据集和检索器。本节剩余内容将提供一些端到端运行的示例。

RankZephyr

我们可以使用以下命令运行 RankZephyr 模型：

rank-llm rerank --model-path castorini/rank_zephyr_7b_v1_full --top-k-candidates 100 --dataset dl20 \
--retrieval-method SPLADE++_EnsembleDistil_ONNX --prompt-template-path src/rank_llm/rerank/prompt_templates/rank_zephyr_template.yaml --context-size 4096 --variable-passages

加入 --sglang_batched 标志后，您就可以使用 SGLang 库以批处理模式运行模型。

加入 --tensorrt_batched 标志后，您就可以使用 TensorRT-LLM 库以批处理模式运行模型。

如果您希望多次运行模型，可以使用 --num_passes 标志。

RankGPT4-o

我们可以使用以下命令运行 RankGPT4-o 模型：

rank-llm rerank --model-path gpt-4o --top-k-candidates 100 --dataset dl20 \
  --retrieval-method bm25 --prompt-template-path src/rank_llm/rerank/prompt_templates/rank_gpt_apeer_template.yaml --context-size 4096 --use-azure-openai

请注意，--prompt_template_path 已设置为 rank_gpt_apeer，以使用来自 APEER 的 LLM 优化提示。此路径也可更改为 rank_GPT 以使用原始提示。

LiT5

我们可以使用以下命令运行 LiT5-Distill V2 模型（该模型可以在一次运行中对100篇文档进行重排序）：

python src/rank_llm/scripts/run_rank_llm.py  --model_path=castorini/LiT5-Distill-large-v2 --top_k_candidates=100 --dataset=dl19 \
        --retrieval_method=bm25 --prompt_template_path=src/rank_llm/rerank/prompt_templates/rank_fid_template.yaml  --context_size=150 --batch_size=4 \
    --variable_passages --window_size=100

我们可以使用以下命令运行 LiT5-Distill 原始模型（该模型的工作窗口大小为20）：

python src/rank_llm/scripts/run_rank_llm.py  --model_path=castorini/LiT5-Distill-large --top_k_candidates=100 --dataset=dl19 \
    --retrieval_method=bm25 --prompt_template_path=src/rank_llm/rerank/prompt_templates/rank_fid_template.yaml  --context_size=150 --batch_size=32 \
    --variable_passages

我们还可以使用以下命令运行 LiT5-Score 模型：

python src/rank_llm/scripts/run_rank_llm.py  --model_path=castorini/LiT5-Score-large --top_k_candidates=100 --dataset=dl19 \
    --retrieval_method=bm25 --prompt_template_path=src/rank_llm/rerank/prompt_templates/rank_fid_score_template.yaml --context_size=150 --batch_size=8 \
    --window_size=100 --variable_passages

MonoT5

以下命令运行经过1万步训练的MonoT5 3B版本：

python src/rank_llm/scripts/run_rank_llm.py --model_path=castorini/monot5-3b-msmarco-10k --top_k_candidates=1000 --dataset=dl19 \
    --retrieval_method=bm25 --prompt_template_path=src/rank_llm/rerank/prompt_templates/monot5_template.yaml --context_size=512

请注意，我们通常使用MonoT5对1000个候选结果进行重排序。

MonoELECTRA

以下命令运行MonoELECTRA模型：

python src/rank_llm/scripts/run_rank_llm.py --model_path=monoelectra --top_k_candidates=1000 --dataset=dl19 \
    --retrieval_method=bm25 --context_size=512

或者使用完整的模型路径：

python src/rank_llm/scripts/run_rank_llm.py --model_path=castorini/monoelectra-base --top_k_candidates=1000 --dataset=dl19 \
    --retrieval_method=bm25 --context_size=512

与MonoT5类似，我们通常使用MonoELECTRA对1000个候选结果进行重排序。

DuoT5

以下命令运行经过1万步训练的DuoT5 #B版本：

python src/rank_llm/scripts/run_rank_llm.py --model_path=castorini/duot5-3b-msmarco-10k --top_k_candidates=50 --dataset=dl19 \
    --retrieval_method=bm25 --prompt_template_path=src/rank_llm/rerank/prompt_templates/duot5_template.yaml

由于Duo的成对比较具有$O(n^2)$的时间复杂度，我们建议使用DuoT5模型对前50名候选结果进行重排序。

FirstMistral

我们可以使用以下命令运行FirstMistral模型，并仅使用第一个token的logits进行重排序：

python src/rank_llm/scripts/run_rank_llm.py  --model_path=castorini/first_mistral --top_k_candidates=100 --dataset=dl20 --retrieval_method=SPLADE++_EnsembleDistil_ONNX --prompt_template_path=src/rank_llm/rerank/prompt_templates/rank_zephyr_template.yaml  --context_size=4096 --variable_passages --use_logits --use_alpha --num_gpus 1

如果您希望执行传统的列表式重排序，请省略--use_logits。

Gemini Flash 2.0

首先安装Gemini提供者的额外依赖：

uv sync --group dev --extra genai
# 或：pip install -e ".[genai]"

然后运行以下命令：

python src/rank_llm/scripts/run_rank_llm.py  --model_path=gemini-2.0-flash-001 --top_k_candidates=100 --dataset=dl20 \
    --retrieval_method=SPLADE++_EnsembleDistil_ONNX --prompt_template_path=src/rank_llm/rerank/prompt_templates/rank_gpt_apeer_template.yaml  --context_size=4096

🦙🐧 模型库

以下是本仓库主要支持的列表式模型表格（模型托管在Hugging Face上）：

vLLM、SGLang和TensorRT-LLM后端仅支持RankZephyr和RankVicuna模型。

模型名称	Hugging Face 标识符/链接
RankZephyr 7B V1 - Full - BF16	castorini/rank_zephyr_7b_v1_full
RankVicuna 7B - V1	castorini/rank_vicuna_7b_v1
RankVicuna 7B - V1 - 无数据增强	castorini/rank_vicuna_7b_v1_noda
RankVicuna 7B - V1 - FP16	castorini/rank_vicuna_7b_v1_fp16
RankVicuna 7B - V1 - 无数据增强 - FP16	castorini/rank_vicuna_7b_v1_noda_fp16

我们还正式支持由我们团队构建的以下重排序器：

LiT5 系列

以下是专门针对我们LiT5系列模型的表格，这些模型托管在Hugging Face上：

模型名称	🤗 Hugging Face 标识符/链接
LiT5 Distill base	castorini/LiT5-Distill-base
LiT5 Distill large	castorini/LiT5-Distill-large
LiT5 Distill xl	castorini/LiT5-Distill-xl
LiT5 Distill base v2	castorini/LiT5-Distill-base-v2
LiT5 Distill large v2	castorini/LiT5-Distill-large-v2
LiT5 Distill xl v2	castorini/LiT5-Distill-xl-v2
LiT5 Score base	castorini/LiT5-Score-base
LiT5 Score large	castorini/LiT5-Score-large
LiT5 Score xl	castorini/LiT5-Score-xl

现在您可以使用v2版本的模型在单次通过中高效地完成前100名的重排序！

MonoT5 系列 - 点式重排序器

以下是专门针对我们monoT5系列模型的表格，这些模型托管在Hugging Face上：

模型名称	🤗 Hugging Face 标识符/链接
monoT5 Small MSMARCO 10K	castorini/monot5-small-msmarco-10k
monoT5 Small MSMARCO 100K	castorini/monot5-small-msmarco-100k
monoT5 Base MSMARCO	castorini/monot5-base-msmarco
monoT5 Base MSMARCO 10K	castorini/monot5-base-msmarco-10k
monoT5 Large MSMARCO 10K	castorini/monot5-large-msmarco-10k
monoT5 Large MSMARCO	castorini/monot5-large-msmarco
monoT5 3B MSMARCO 10K	castorini/monot5-3b-msmarco-10k
monoT5 3B MSMARCO	castorini/monot5-3b-msmarco
monoT5 Base Med MSMARCO	castorini/monot5-base-med-msmarco
monoT5 3B Med MSMARCO	castorini/monot5-3b-med-msmarco

我们建议在生物医学检索任务中使用Med系列模型。我们同时提供1万步（通常在OOD场景下效果更好）和10万步（在域内表现更佳）的检查点。

训练

请查看 training 目录，了解如何微调开源的列表式重排序模型。

外部集成

RankLLM 已被集成到许多流行的工具包中，如 LlamaIndex、rerankers 和 LangChain。有关在这些工具包中使用 RankLLM 的方法及示例，请参阅外部集成 README。

社区贡献

如果您希望为该项目做出贡献，请参阅 贡献指南。

📜️ 发布历史

• v0.25.7：2025年8月25日 [发布说明]
• v0.25.6：2025年8月5日 [发布说明]
• v0.25.0：2025年7月23日 [发布说明]

✨ 参考文献

如果您使用 RankLLM，请引用以下相关论文：

[2505.19284] RankLLM：用于基于 LLM 进行重排序的 Python 包

@inproceedings{sharifymoghaddam2025rankllm,
author = {Sharifymoghaddam, Sahel and Pradeep, Ronak and Slavescu, Andre and Nguyen, Ryan and Xu, Andrew and Chen, Zijian and Zhang, Yilin and Chen, Yidi and Xian, Jasper and Lin, Jimmy},
title = {{RankLLM}: A Python Package for Reranking with LLMs},
year = {2025},
isbn = {9798400715921},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
booktitle = {Proceedings of the 48th International ACM SIGIR Conference on Research and Development in Information Retrieval},
pages = {3681–3690},
numpages = {10},
keywords = {information retrieval, large language models, python, reranking},
location = {Padua, Italy},
series = {SIGIR '25}
}

[2309.15088] RankVicuna：使用开源大型语言模型进行零样本列表式文档重排序

@ARTICLE{pradeep2023rankvicuna,
  title   = {{RankVicuna}: Zero-Shot Listwise Document Reranking with Open-Source Large Language Models},
  author  = {Ronak Pradeep and Sahel Sharifymoghaddam and Jimmy Lin},
  year    = {2023},
  journal = {arXiv:2309.15088}
}

[2312.02724] RankZephyr：高效且稳健的零样本列表式重排序轻而易举！

@ARTICLE{pradeep2023rankzephyr,
  title   = {{RankZephyr}: Effective and Robust Zero-Shot Listwise Reranking is a Breeze!},
  author  = {Ronak Pradeep and Sahel Sharifymoghaddam and Jimmy Lin},
  year    = {2023},
  journal = {arXiv:2312.02724}
}

如果您使用 LiT5 模型之一，请引用以下相关论文：

[2312.16098] 缩小规模，提升性能：使用序列到序列编码器-解码器模型实现高效的零样本列表式重排序

@ARTICLE{tamber2023scaling,
  title   = {Scaling Down, LiTting Up: Efficient Zero-Shot Listwise Reranking with Seq2seq Encoder-Decoder Models},
  author  = {Manveer Singh Tamber and Ronak Pradeep and Jimmy Lin},
  year    = {2023},
  journal = {arXiv:2312.16098}
}

如果您使用 monoT5 模型之一，请引用以下相关论文：

[2101.05667] 面向文本排名的预训练序列到序列模型的 Expando-Mono-Duo 设计模式

@ARTICLE{pradeep2021emd,
  title = {The Expando-Mono-Duo Design Pattern for Text Ranking with Pretrained Sequence-to-Sequence Models},
  author = {Ronak Pradeep and Rodrigo Nogueira and Jimmy Lin},
  year = {2021},
  journal = {arXiv:2101.05667},
}

如果您使用 monoELECTRA 模型，请考虑引用：

从石头中挤出水来：进一步提升交叉编码器重排序效果的一系列技巧

@inproceedings{pradeep2022monoelectra,
  author = {Pradeep, Ronak and Liu, Yuqi and Zhang, Xinyu and Li, Yilin and Yates, Andrew and Lin, Jimmy},
  title = {Squeezing Water from a Stone: A Bag of Tricks for Further Improving Cross-Encoder Effectiveness for Reranking},
  year = {2022},
  publisher = {Springer-Verlag},
  address = {Berlin, Heidelberg},
  booktitle = {Advances in Information Retrieval: 44th European Conference on IR Research, ECIR 2022, Stavanger, Norway, April 10–14, 2022, Proceedings, Part I},
  pages = {655–670},
  numpages = {16},
  location = {Stavanger, Norway}
}

如果您使用 FirstMistral 模型，请考虑引用：

[2411.05508] 早期 FIRST 复现及单标记解码改进，用于快速列表式重排序

@ARTICLE{chen2024firstrepro,
  title   = title={An Early FIRST Reproduction and Improvements to Single-Token Decoding for Fast Listwise Reranking},
  author  = {Zijian Chen and Ronak Pradeep and Jimmy Lin},
  year    = {2024},
  journal = {arXiv:2411.05508}
}

如果您想引用 FIRST 方法论，请考虑引用：

[2406.15657] FIRST：通过单标记解码实现更快更优的列表式重排序

@ARTICLE{reddy2024first,
  title   = {FIRST: Faster Improved Listwise Reranking with Single Token Decoding},
  author  = {Reddy, Revanth Gangi and Doo, JaeHyeok and Xu, Yifei and Sultan, Md Arafat and Swain, Deevya and Sil, Avirup and Ji, Heng},
  year    = {2024}
  journal = {arXiv:2406.15657},
}

🙏 致谢

本研究部分得到了加拿大自然科学与工程研究委员会（NSERC）的支持。

RankLLM 快速上手指南

RankLLM 是一个强大的重排序（Rerank）工具套件，支持多种开源大语言模型（如 RankZephyr、MonoT5）及专有模型（如 RankGPT、RankGemini）。它兼容 vLLM、SGLang 和 TensorRT-LLM 后端，旨在提供高效、灵活的文档重排序解决方案。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS。
• Python 版本: 3.11 (官方推荐)。
• Java 环境: 如果计划使用检索或评估工作流（通过 pyserini），必须安装 Java 21 (不支持 JDK 11)。
• GPU 驱动: 如需 GPU 加速，请确保已安装正确的 NVIDIA 驱动和 CUDA 工具包。

安装步骤

官方推荐使用 uv 进行环境管理和安装，同时也支持传统的 pip 和 conda。

方法一：使用 uv 推荐安装（首选）

uv 是该项目标准的开发工作流工具，安装速度极快。

1. 安装 uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   export PATH="$HOME/.local/bin:$PATH"
   

2. 克隆项目并创建虚拟环境:

   git clone https://github.com/castorini/rank_llm.git
   cd rank_llm
   uv python install 3.11
   uv venv --python 3.11
   source .venv/bin/activate
   

3. 安装依赖:

   • 基础开发版:

     uv sync --group dev
     

   • 按需安装特定功能栈 (可组合使用):

     # 例如：安装本地 HuggingFace 模型支持 + OpenAI API 支持
     uv sync --group dev --extra local --extra openai
     
     # 例如：安装 vLLM 后端支持
     uv sync --group dev --extra vllm
     

     常用 Extra 说明:

     • local: 本地 PyTorch/HF 模型 (MonoT5, DuoT5 等)
     • openai / genai / cloud: 调用 OpenAI, Gemini 等云端 API
     • vllm / sglang / tensorrt-llm: 高性能推理后端
     • pyserini: 检索与评估功能 (需 Java 21)
     • all: 安装所有功能

方法二：使用 pip 直接安装（简易版）

如果您只需使用发布版功能，可直接通过 pip 安装：

uv venv --python 3.11
source .venv/bin/activate
uv pip install rank-llm

# 如需额外功能，例如本地模型支持：
uv pip install "rank-llm[local]"
# 或云端 API 支持：
uv pip install "rank-llm[cloud]"

注意: 若使用 sglang 或 tensorrt-llm，可能需要单独安装 flashinfer 或 flash-attn：

pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/
pip install flash-attn --no-build-isolation

基本使用

RankLLM 提供了统一的命令行工具 rank-llm 和 Python API 两种使用方式。

1. 命令行快速重排序 (CLI)

以下命令使用预训练的 RankZephyr 模型，对 dl20 数据集通过 BM25 检索出的前 100 个候选文档进行重排序：

rank-llm rerank --model-path castorini/rank_zephyr_7b_v1_full --dataset dl20 \
  --retrieval-method bm25 --top-k-candidates 100

其他常用命令:

• 查看可用提示词模板：rank-llm prompt list
• 查看重排序结果：rank-llm view demo_outputs/rerank_results.jsonl
• 启动 HTTP 服务：rank-llm serve http --model-path castorini/rank_zephyr_7b_v1_full --port 8082

2. Python API 最小示例

以下代码演示了完整的流程：检索 -> 重排序 -> 评估 -> 保存结果。

from pathlib import Path

from rank_llm.analysis.response_analysis import ResponseAnalyzer
from rank_llm.data import DataWriter
from rank_llm.evaluation.trec_eval import EvalFunction
from rank_llm.rerank.listwise import ZephyrReranker
from rank_llm.retrieve.retriever import Retriever
from rank_llm.retrieve.topics_dict import TOPICS

# 1. 检索 (默认使用 BM25 检索前 100 个候选文档)
dataset_name = "dl19"
retrieved_results = Retriever.from_dataset_with_prebuilt_index(dataset_name)

# 2. 重排序 (使用 RankZephyr 模型)
reranker = ZephyrReranker()
kwargs = {"populate_invocations_history": True}
rerank_results = reranker.rerank_batch(requests=retrieved_results, **kwargs)

# 3. 评估 (默认指标为 NDCG@10)
topics = TOPICS[dataset_name]
ndcg_10_retrieved = EvalFunction.from_results(retrieved_results, topics)
print(f"Retrieval NDCG@10: {ndcg_10_retrieved}")

ndcg_10_rerank = EvalFunction.from_results(rerank_results, topics)
print(f"Rerank NDCG@10: {ndcg_10_rerank}")

# 4. 分析调用错误 (可选)
analyzer = ResponseAnalyzer.from_inline_results(rerank_results)
error_counts = analyzer.count_errors(verbose=True)
print(error_counts)

# 5. 保存结果
writer = DataWriter(rerank_results)
Path("demo_outputs/").mkdir(parents=True, exist_ok=True)
writer.write_in_jsonl_format("demo_outputs/rerank_results.jsonl")
writer.write_in_trec_eval_format("demo_outputs/rerank_results.txt")

进阶提示

• 批量加速: 在使用 CLI 时，添加 --sglang_batched 或 --tensorrt_batched 标志可启用 SGLang 或 TensorRT-LLM 后端进行批量推理，显著提升速度。
• 自定义 Prompt: 支持通过 YAML 文件自定义提示词模板，适配不同的模型或任务需求。