beir

2.1k 239 非常简单 1 次阅读昨天Apache-2.0开发框架其他语言模型数据工具

AI 解读由 AI 自动生成，仅供参考

BEIR 是一个专为信息检索（IR）领域设计的异构基准测试工具，旨在帮助开发者和研究人员轻松评估各类 NLP 检索模型的性能。在人工智能应用中，如何验证一个检索模型是否具备广泛的适应能力而非仅针对特定数据过拟合，一直是个难题。BEIR 通过整合超过 15 个多样化的数据集，涵盖问答、事实核查、科学文献搜索等多种任务场景，提供了一个统一且标准化的评估框架，有效解决了模型泛化能力难以横向对比的痛点。

该工具特别适合从事搜索引擎优化、自然语言处理算法研发的研究人员及工程师使用。无论是学术界探索零样本（Zero-shot）学习的新方法，还是工业界需要筛选鲁棒性强的生产级模型，BEIR 都能提供可靠的支持。其核心技术亮点在于“异构性”与“易用性”：它不仅支持词汇匹配、稠密向量、稀疏表示及重排序等多种主流检索架构的评测，还允许用户快速接入自定义模型或数据集。只需几行代码，即可在多个基准上运行测试并生成包含多种权威指标的详细报告。此外，BEIR 与 Hugging Face 生态深度集成，方便用户直接调用预训练模型和标准数据集，极大地降低了高性能检索系统的研发门槛。

使用场景

某电商公司的搜索算法团队正在研发新一代语义搜索模型，旨在提升用户模糊查询下的商品匹配准确率。

没有 beir 时

数据整合耗时巨大：团队需手动收集、清洗并格式化来自新闻、问答、科学文献等 15+ 个不同领域的异构数据集，耗费数周时间且容易出错。
评估标准不统一：针对不同数据集需编写独立的评估脚本，导致 lexical（词汇）、dense（稠密）等不同架构模型的对比结果缺乏一致性，难以横向复盘。
零样本能力验证困难：缺乏统一的基准来测试模型在未见过的新领域（如医疗或法律文档）的表现，导致模型上线后在长尾场景下频繁失效。
复现与迭代成本高：每次调整模型结构后，重新跑通全套基准测试流程繁琐，严重拖慢了从实验到部署的迭代速度。

使用 beir 后

一键加载多源数据：通过 pip install beir 即可直接调用已预处理的 17 个基准数据集，将数据准备时间从数周缩短至几分钟。
标准化评估框架：利用其内置的统一接口，轻松在同一框架下对比稀疏检索、稠密向量及重排序模型，确保各项指标（如 NDCG@10）公平可比。
全面检验泛化性能：快速在涵盖生物医学、金融等多领域的异构任务上进行零样本（Zero-shot）评测，提前发现模型在特定领域的短板并针对性优化。
高效实验闭环：借助简洁的 API 快速集成自定义模型，自动化完成全流程评估，使团队能将精力集中在算法创新而非工程基建上。

beir 通过提供统一且多样的异构基准，彻底解决了信息检索模型在跨领域评估中“数据难凑、标准难齐、泛化难测”的核心痛点。

运行环境要求

操作系统

未说明

GPU

非必需（支持 CPU 运行，示例中包含 faiss-cpu）
若使用 vLLM 或 Flash Attention 加速则需 NVIDIA GPU

内存

未说明

依赖

notes基础安装仅需执行 'pip install beir'。若需运行高级示例（如 LoRA & vLLM），需额外安装 peft、vllm 和 accelerate；若使用 HuggingFace 示例中的 encode_and_retrieve 功能，需安装 faiss-cpu；若调用 API（如 Cohere），需安装对应客户端库。工具支持多种检索架构（词汇、稠密、稀疏及重排序），并提供 17 个预处理数据集。

python3.9+

peft

vllm

accelerate

faiss-cpu

cohere

快速开始

论文 | 安装 | 快速示例 | 数据集 | 维基 | Hugging Face

:beers: 它是什么？

BEIR 是一个包含多样化信息检索任务的 异构基准测试平台。它还提供了一个 通用且简便的框架，用于在该基准中评估基于自然语言处理的检索模型。

如需概览，请访问我们的 新维基页面：https://github.com/beir-cellar/beir/wiki。

如需了解 模型和数据集，请访问 Hugging Face (HF) 页面：https://huggingface.co/BeIR。

更多信息请参阅我们的出版物：

BEIR：用于零样本评估信息检索模型的异构基准（NeurIPS 2021，数据集与基准赛道）
构建BEIR的资源：可复现的参考模型与官方排行榜（SIGIR 2024 资源赛道）

:beers: 安装

通过 pip 安装：

pip install beir

如果您想从源代码构建，请使用：

$ git clone https://github.com/beir-cellar/beir.git
$ cd beir
$ pip install -e .

已测试兼容 Python 3.9 及以上版本。

:beers: 特性

可预处理您自己的信息检索数据集，或直接使用已预处理好的17个基准数据集。
设置广泛，涵盖适用于学术界和工业界的多样化基准。
支持对知名检索架构（词汇、稠密、稀疏及重排序）进行评估。
您可以在简单易用的框架中添加并评估自己的模型，并采用多种最先进的评估指标。

:beers: 快速示例

更多示例代码，请参阅我们的 示例与教程 维基页面。

Sentence-BERT 快速示例

from beir import util, LoggingHandler
from beir.retrieval import models
from beir.datasets.data_loader import GenericDataLoader
from beir.retrieval.evaluation import EvaluateRetrieval
from beir.retrieval.search.dense import DenseRetrievalExactSearch as DRES

import logging
import pathlib, os

#### 仅用于将调试信息打印到标准输出的代码
logging.basicConfig(format='%(asctime)s - %(message)s',
                    datefmt='%Y-%m-%d %H:%M:%S',
                    level=logging.INFO,
                    handlers=[LoggingHandler()])
#### /将调试信息打印到标准输出

#### 下载 scifact.zip 数据集并解压
dataset = "scifact"
url = f"https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/{dataset}.zip"
out_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "datasets")
data_path = util.download_and_unzip(url, out_dir)

#### 提供 scifact 已下载并解压的数据路径
corpus, queries, qrels = GenericDataLoader(data_folder=data_path).load(split="test")

#### 加载 SBERT 模型并使用余弦相似度进行检索
model = DRES(models.SentenceBERT("Alibaba-NLP/gte-modernbert-base"), batch_size=16)

retriever = EvaluateRetrieval(model, score_function="cos_sim") # 或 "dot" 用于点积
results = retriever.retrieve(corpus, queries)

#### 使用 NDCG@k、MAP@K、Recall@K 和 Precision@K 对您的模型进行评估，其中 k = [1,3,5,10,100,1000]
ndcg, _map, recall, precision = retriever.evaluate(qrels, results, retriever.k_values)
mrr = retriever.evaluate_custom(qrels, results, retriever.k_values, metric="mrr")

### 如果你想保存你的结果和运行文件（对重新排序很有用）
results_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "results")
os.makedirs(results_dir, exist_ok=True)

#### 保存评估的运行文件及结果
util.save_runfile(os.path.join(results_dir, f"{dataset}.run.trec"), results)
util.save_results(os.path.join(results_dir, f"{dataset}.json"), ndcg, _map, recall, precision, mrr)

使用LoRA与vLLM的快速示例

首先使用以下命令安装peft、vllm和accelerate：

pip install peft
pip install accelerate
pip install vllm

from beir import util, LoggingHandler
from beir.retrieval import models
from beir.datasets.data_loader import GenericDataLoader
from beir.retrieval.evaluation import EvaluateRetrieval
from beir.retrieval.search.dense import DenseRetrievalExactSearch as DRES

import logging
import pathlib, os

#### 仅用于将调试信息打印到标准输出的代码
logging.basicConfig(format='%(asctime)s - %(message)s',
                    datefmt='%Y-%m-%d %H:%M:%S',
                    level=logging.INFO,
                    handlers=[LoggingHandler()])
#### /将调试信息打印到标准输出

#### 下载scifact.zip数据集并解压
dataset = "scifact"
url = f"https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/{dataset}.zip"
out_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "datasets")
data_path = util.download_and_unzip(url, out_dir)

#### 提供scifact已下载并解压后的数据路径
corpus, queries, qrels = GenericDataLoader(data_folder=data_path).load(split="test")

#### 你也可以将LoRA模型权重合并到原始基础模型中，以加快推理速度。
#### 参考：https://github.com/beir-cellar/beir/blob/main/examples/retrieval/evaluation/dense/evaluate_lora_vllm.py

#### 加载vLLM嵌入模型，并使用余弦相似度进行检索
model = DRES(
    models.VLLMEmbed(
        model_path="Qwen/Qwen2.5-7B",
        lora_name_or_path="rlhn/Qwen2.5-7B-rlhn-400K",
        max_length=512,
        lora_r=16,
        pooling="eos",
        append_eos_token=True,
        normalize=True,
        prompts={"query": "query: ", "passage": "passage: "},
        convert_to_numpy=True
    ),
    batch_size=128,
)

retriever = EvaluateRetrieval(model, score_function="cos_sim") # 或者使用“dot”进行点积计算
results = retriever.encode_and_retrieve(corpus, queries, encode_output_path="./qwen_embeddings/")

#### 使用NDCG@k、MAP@K、Recall@K和Precision@K来评估你的模型，其中k取值为[1,3,5,10,100,1000]
ndcg, _map, recall, precision = retriever.evaluate(qrels, results, retriever.k_values)
mrr = retriever.evaluate_custom(qrels, results, retriever.k_values, metric="mrr")

### 如果你想保存你的结果和运行文件（对重新排序很有用）
results_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "results")
os.makedirs(results_dir, exist_ok=True)

#### 保存评估的运行文件及结果
util.save_runfile(os.path.join(results_dir, f"{dataset}.run.trec"), results)
util.save_results(os.path.join(results_dir, f"{dataset}.json"), ndcg, _map, recall, precision, mrr)

使用HuggingFace的快速示例

如果你使用`encode_and_retrieve()`方法，请确保安装faiss库：`pip install faiss-cpu`。

from beir import util, LoggingHandler
from beir.retrieval import models
from beir.datasets.data_loader import GenericDataLoader
from beir.retrieval.evaluation import EvaluateRetrieval
from beir.retrieval.search.dense import DenseRetrievalExactSearch as DRES

import logging
import pathlib, os

#### 仅用于将调试信息打印到标准输出的代码
logging.basicConfig(format='%(asctime)s - %(message)s',
                    datefmt='%Y-%m-%d %H:%M:%S',
                    level=logging.INFO,
                    handlers=[LoggingHandler()])
#### /将调试信息打印到标准输出

#### 下载scifact.zip数据集并解压
dataset = "scifact"
url = f"https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/{dataset}.zip"
out_dir = os.path.join(pathlib.Path(__file__).parent绝对(), "datasets")
data_path = util.download_and_unzip(url, out_dir)

#### 提供scifact已下载并解压后的数据路径
corpus, queries, qrels = GenericDataLoader(data_folder=data_path).load(split="test")

#### 加载HuggingFace模型，并使用余弦相似度进行检索
query_prompt = "指令：给定一个问题，检索能够最好地回答该问题的相关文档\n查询："

model = DRES(
    models.HuggingFace(
        model_path="intfloat/e5-mistral-7b-instruct",
        max_length=512,
        pooling="eos",
        append_eos_token=True,
        normalize=True,
        prompts={"query": query_prompt, "passage": ""},
        attn_implementation="flash_attention_2",
        torch_dtype="bfloat16"
    ),
    batch_size=128,
)

retriever = EvaluateRetrieval(model, score_function="cos_sim") # 或者使用“dot”进行点积计算
results = retriever.encode_and_retrieve(corpus, queries，encode_output_path="./embeddings/")

#### 使用NDCG@k、MAP@K、Recall@K和Precision@K来评估你的模型，其中k取值为[1,3,5,10,100,1000]
ndcg, _map, recall, precision = retriever.evaluate(qrels, results, retriever.k_values)
mrr = retriever.evaluate_custom(qrels, results, retriever.k_values, metric="mrr")

### 如果你想保存你的结果和运行文件（对重新排序很有用）
results_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "results")
os.makedirs(results_dir, exist_ok=True)

#### 保存评估的运行文件及结果
util.save_runfile(os.path.join(results_dir, f"{dataset}.run.trec"), results)
util.save_results(os.path.join(results_dir, f"{dataset}.json"), ndcg, _map, recall, precision, mrr)

使用 API 的快速示例，例如 Cohere

使用 pip install cohere 安装 Cohere API；如果你要使用 encode_and_retrieve()，还需通过 pip install faiss-cpu 安装 Faiss。

from beir import util, LoggingHandler
from beir.retrieval import apis
from beir.datasets.data_loader import GenericDataLoader
from beir.retrieval.evaluation import EvaluateRetrieval
from beir.retrieval.search.dense import DenseRetrievalExactSearch as DRES

import logging
import pathlib, os

#### 仅用于将调试信息打印到标准输出的代码
logging.basicConfig(format='%(asctime)s - %(message)s',
                    datefmt='%Y-%m-%d %H:%M:%S',
                    level=logging.INFO,
                    handlers=[LoggingHandler()])
#### /将调试信息打印到标准输出

#### 下载 scifact.zip 数据集并解压
dataset = "scifact"
url = f"https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/{dataset}.zip"
out_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "datasets")
data_path = util.download_and_unzip(url, out_dir)

#### 提供 scifact 已下载并解压后的数据路径
corpus, queries, qrels = GenericDataLoader(data_folder=data_path).load(split="test")

cohere_api_key = os.getenv("COHERE_API_KEY")
#### 加载 Cohere API 的嵌入模型，并使用余弦相似度进行检索
model = DRES(
    apis.CohereEmbedAPI(
        api_key=cohere_api_key, 
        model_path="embed-v4.0", 
        normalize=True, 
        torch_dtype="float32"
    ),
    batch_size=96,
)

retriever = EvaluateRetrieval(model, score_function="cos_sim") # 或者使用 "dot" 表示点积
results = retriever.encode_and_retrieve(corpus, queries, encode_output_path="./cohere/embeddings/")

#### 使用 NDCG@k、MAP@K、Recall@K 和 Precision@K 来评估你的模型，其中 k = [1,3,5,10,100,1000]
ndcg, _map, recall, precision = retriever.evaluate(qrels, results, retriever.k_values)
mrr = retriever.evaluate_custom(qrels, results, retriever.k_values, metric="mrr")

### 如果你想保存你的结果和运行文件（对重新排序很有用）
results_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "results")
os.makedirs(results_dir, exist_ok=True)

#### 保存评估的运行文件及结果
util.save_runfile(os.path.join(results_dir, f"{dataset}.run.trec"), results)
util.save_results(os.path.join(results_dir, f"{dataset}.json"), ndcg, _map, recall, precision, mrr)

:beers: 可用数据集

使用终端生成 md5hash 的命令：md5sum filename.zip。

您可以在这里或 Hugging Face 上查看所有可用的数据集。

数据集	官网	BEIR 名称	公开？	类型	查询	语料库	相关性 D/Q	下载	md5
MSMARCO	主页	`msmarco`	✅	`train` `dev` `test`	6,980	8.84M	1.1	链接	`444067daf65d982533ea17ebd59501e4`
TREC-COVID	主页	`trec-covid`	✅	`test`	50	171K	493.5	链接	`ce62140cb23feb9becf6270d0d1fe6d1`
NFCorpus	主页	`nfcorpus`	✅	`train` `dev` `test`	323	3.6K	38.2	链接	`a89dba18a62ef92f7d323ec890a0d38d`
BioASQ	主页	`bioasq`	❌	`train` `test`	500	14.91M	4.7	否	如何复现？
NQ	主页	`nq`	✅	`train` `test`	3,452	2.68M	1.2	链接	`d4d3d2e48787a744b6f6e691ff534307`
HotpotQA	主页	`hotpotqa`	✅	`train` `dev` `test`	7,405	5.23M	2.0	链接	`f412724f78b0d91183a0e86805e16114`
FiQA-2018	主页	`fiqa`	✅	`train` `dev` `test`	648	57K	2.6	链接	`17918ed23cd04fb15047f73e6c3bd9d9`
Signal-1M(RT)	主页	`signal1m`	❌	`test`	97	2.86M	19.6	否	如何复现？
TREC-NEWS	主页	`trec-news`	❌	`test`	57	595K	19.6	否	如何复现？
Robust04	主页	`robust04`	❌	`test`	249	528K	69.9	否	如何复现？
ArguAna	主页	`arguana`	✅	`test`	1,406	8.67K	1.0	链接	`8ad3e3c2a5867cdced806d6503f29b99`
Touche-2020	主页	`webis-touche2020`	✅	`test`	49	382K	19.0	链接	`46f650ba5a527fc69e0a6521c5a23563`
CQADupstack	主页	`cqadupstack`	✅	`test`	13,145	457K	1.4	链接	`4e41456d7df8ee7760a7f866133bda78`
Quora	主页	`quora`	✅	`dev` `test`	10,000	523K	1.6	链接	`18fb154900ba42a600f84b839c173167`
DBPedia	主页	`dbpedia-entity`	✅	`dev` `test`	400	4.63M	38.2	链接	`c2a39eb420a3164af735795df012ac2c`
SCIDOCS	主页	`scidocs`	✅	`test`	1,000	25K	4.9	链接	`38121350fc3a4d2f48850f6aff52e4a9`
FEVER	主页	`fever`	✅	`train` `dev` `test`	6,666	5.42M	1.2	链接	`5a818580227bfb4b35bb6fa46d9b6c03`
Climate-FEVER	主页	`climate-fever`	✅	`test`	1,535	5.42M	3.0	链接	`8b66f0a9126c521bae2bde127b4dc99d`
SciFact	主页	`scifact`	✅	`train` `test`	300	5K	1.1	链接	`5f7d1de60b170fc8027bb7898e2efca1`

:beers: 附加信息

我们还在我们的 Wiki 页面上提供了各种附加信息。请参阅以下页面以获取更多信息：

快速入门

数据集

模型

指标

可用指标

其他

:beers: 免责声明

与 TensorFlow 的 datasets 或 Hugging Face 的 datasets 库类似，我们只是下载并整理了公开的数据集。我们仅以特定格式分发这些数据集，但并不保证其质量或公平性，也不声称您拥有使用该数据集的许可。用户仍需自行判断是否根据数据集的许可协议有权使用该数据集，并正确引用数据集的原始所有者。

如果您是数据集的所有者，希望更新其中的任何部分，或者不希望您的数据集被包含在本库中，请随时在此处提交问题或发起拉取请求！

如果您是数据集的所有者，希望将您的数据集或模型纳入本库，请随时在此处提交问题或发起拉取请求！

:beers: 引用与作者

如果您觉得本仓库有所帮助，请随时引用我们的论文 BEIR：用于信息检索模型零样本评估的异构基准：

@inproceedings{
    thakur2021beir,
    title={{BEIR}: A Heterogeneous Benchmark for Zero-shot Evaluation of Information Retrieval Models},
    author={Nandan Thakur and Nils Reimers and Andreas R{\"u}ckl{\'e} and Abhishek Srivastava and Iryna Gurevych},
    booktitle={Thirty-fifth Conference on Neural Information Processing Systems Datasets and Benchmarks Track (Round 2)},
    year={2021},
    url={https://openreview.net/forum?id=wCu6T5xFjeJ}
}

如果您使用 BEIR 排行榜上的任何基线分数，请随时引用我们的论文 BEIR 打造资源：可复现的参考模型与官方排行榜：

@inproceedings{kamalloo:2024,
    author = {Kamalloo, Ehsan and Thakur, Nandan and Lassance, Carlos and Ma, Xueguang and Yang, Jheng-Hong and Lin, Jimmy},
    title = {Resources for Brewing BEIR: Reproducible Reference Models and Statistical Analyses},
    year = {2024},
    isbn = {9798400704314},
    publisher = {Association for Computing Machinery},
    address = {New York, NY, USA},
    url = {https://doi.org/10.1145/3626772.3657862},
    doi = {10.1145/3626772.3657862},
    abstract = {BEIR 是一个基准数据集，最初设计用于对跨 18 种不同领域/任务组合的检索模型进行零样本评估。近年来，基于表示学习的模型日益流行，这自然引出一个问题：当面对与训练数据不同的查询和文档时，这些模型的效果如何？虽然 BEIR 的设计正是为回答这一问题，但我们的工作指出了两个阻碍该基准充分发挥潜力的不足之处：首先，现代神经方法的复杂性和当前软件基础设施的复杂性为新手设置了进入壁垒。为此，我们提供了涵盖学习型密集和稀疏模型的可复现参考实现。其次，BEIR 上的比较通常是通过将来自异质数据集的分数简化为一个难以解释的单一平均值来进行的。为了解决这个问题，我们提出了针对各数据集效应量的元分析，能够准确量化模型之间的差异。通过解决这两个不足，我们的工作促进了未来在一系列有趣研究问题上的探索。},
    booktitle = {Proceedings of the 47th International ACM SIGIR Conference on Research and Development in Information Retrieval},
    pages = {1431–1440},
    numpages = {10},
    keywords = {domain generalization, evaluation, reproducibility},
    location = {Washington DC, USA},
    series = {SIGIR '24}
}

本仓库的主要贡献者如下：

Nandan Thakur，个人网站：thakur-nandan.gitub.io

联系人：Nandan Thakur，nandant@gmail.com

如果遇到任何问题（尽管不应该出现）或有其他疑问，请随时发送电子邮件或报告问题。

本仓库包含实验性软件，仅用于为相关论文提供额外的背景信息。

:beers: 合作

BEIR 基准的实现得益于以下大学和组织的共同努力：

:beers: 贡献者

感谢所有参与合作的机构和个人对 BEIR 基准的贡献：

_{Nandan Thakur}

_{Nils Reimers}

_{Iryna Gurevych}

_{Jimmy Lin}

_{Andreas Rücklé}

_{Abhishek Srivastava}

BEIR 快速上手指南

BEIR 是一个异构基准测试工具，包含多样化的信息检索（IR）任务。它提供了一个通用且易于使用的框架，用于在基准测试中评估基于 NLP 的检索模型（支持零样本评估）。

环境准备

操作系统：Linux, macOS, Windows
Python 版本：3.9 及以上
前置依赖：
- pip 包管理工具
- 若使用大规模向量检索（如 encode_and_retrieve），建议安装 faiss-cpu 或 faiss-gpu
- 若使用 LoRA 或 vLLM 模型，需额外安装 peft, accelerate, vllm

国内加速建议：建议使用清华或阿里镜像源加速 Python 包下载。
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

安装步骤

方式一：通过 PyPI 安装（推荐）

pip install beir

国内加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple beir

方式二：从源码安装

git clone https://github.com/beir-cellar/beir.git
cd beir
pip install -e .

基本使用

以下示例演示如何使用 BEIR 下载数据集、加载预训练模型（Sentence-BERT）、执行检索并评估结果。

1. 导入必要模块

from beir import util, LoggingHandler
from beir.retrieval import models
from beir.datasets.data_loader import GenericDataLoader
from beir.retrieval.evaluation import EvaluateRetrieval
from beir.retrieval.search.dense import DenseRetrievalExactSearch as DRES

import logging
import pathlib, os

# 配置日志输出
logging.basicConfig(format='%(asctime)s - %(message)s',
                    datefmt='%Y-%m-%d %H:%M:%S',
                    level=logging.INFO,
                    handlers=[LoggingHandler()])

2. 下载并加载数据集

BEIR 支持自动下载并解压数据集（以 scifact 为例）：

dataset = "scifact"
url = f"https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/{dataset}.zip"
out_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "datasets")

# 下载并解压
data_path = util.download_and_unzip(url, out_dir)

# 加载数据 (corpus: 文档库，queries: 查询集，qrels: 相关性地标)
corpus, queries, qrels = GenericDataLoader(data_folder=data_path).load(split="test")

3. 加载模型并执行检索

这里使用 SentenceBERT 模型进行稠密检索：

# 加载模型并封装为检索器
# 注意：模型路径可替换为其他 HuggingFace 模型
model = DRES(models.SentenceBERT("Alibaba-NLP/gte-modernbert-base"), batch_size=16)

# 初始化评估工具，设置相似度分数函数 (cos_sim 或 dot)
retriever = EvaluateRetrieval(model, score_function="cos_sim")

# 执行检索
results = retriever.retrieve(corpus, queries)

4. 评估结果

计算常用的检索指标（NDCG, MAP, Recall, Precision, MRR）：

# 定义评估的 k 值
k_values = [1, 3, 5, 10, 100, 1000]

# 标准指标评估
ndcg, _map, recall, precision = retriever.evaluate(qrels, results, k_values)

# 自定义指标评估 (如 MRR)
mrr = retriever.evaluate_custom(qrels, results, k_values, metric="mrr")

# 打印结果概览
print(f"NDCG@10: {ndcg['NDCG@10']:.4f}")
print(f"Recall@10: {recall['Recall@10']:.4f}")

5. 保存结果（可选）

保存结果文件以便后续分析或提交到排行榜：

results_dir = os.path.join(pathlib.Path(__file__).parent.absolute(), "results")
os.makedirs(results_dir, exist_ok=True)

# 保存 Run 文件 (TREC 格式)
util.save_runfile(os.path.join(results_dir, f"{dataset}.run.trec"), results)

# 保存评估指标 JSON
util.save_results(os.path.join(results_dir, f"{dataset}.json"), ndcg, _map, recall, precision, mrr)

提示：BEIR 还支持多种高级用法，包括使用 LoRA 微调模型、vLLM 加速推理、调用 Cohere 等 API 模型，详细代码请参考官方 Wiki 中的 Examples 部分。

版本历史

v2.2.02025/06/04

v2.1.02025/02/25

v2.0.02023/08/03

v1.0.12022/06/30

v1.0.02022/03/21

v0.2.32021/10/22

v0.2.22021/08/17

v0.2.12021/07/19

v0.2.02021/07/06

常见问题

为什么我无法复现论文中报告的 BM25 基线分数（例如 NDCG@10）？

NQ 数据集的训练集 qrels 文件（train.tsv）缺失了吗？

如何在 BEIR 中运行或集成 ColBERT 模型？

对于新手用户，推荐哪些模型作为检索基准？

在哪里可以找到查询生成模型（QGenModel，如 T5-small）的训练代码？

BEIR 是否支持使用自定义模型或混合模型进行训练和评估？

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|1周前

Agent开发框架图像

stable-diffusion-webui

stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。

★ 162.1k|★★★☆☆|1周前

开发框架图像Agent

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上

★ 158.1k|★★☆☆☆|今天

开发框架Agent语言模型

ComfyUI

ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。

★ 108.3k|★★☆☆☆|6天前

开发框架图像Agent

gemini-cli

gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。

★ 100.8k|★★☆☆☆|1周前

插件Agent图像

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器

★ 93.4k|★★☆☆☆|1周前

插件开发框架