ir_datasets

ir_datasets是一个Python包，为许多IR临时排名基准、训练数据集等提供了通用接口。

当可从公共来源获取时，该包负责下载数据集（包括文档、查询、相关性判断等）。对于不公开可用的数据集，会提供获取说明。

ir_datasets提供了通用的迭代器格式，使其易于在Python中使用。它尝试以未经改变的形式提供数据（即保留所有字段和标记），同时处理文件格式、编码等方面的差异。适配器提供了额外的功能，例如允许通过ID快速查找文档。

还提供了命令行界面。

您可以在这里找到数据集及其特性列表。想要新的数据集、添加功能或修复bug？欢迎提出问题或发起拉取请求！

入门

对于Python API的快速入门，请查看我们的Colab教程： Python 命令行

通过pip安装：

pip install ir_datasets

如果您想要主分支，可以这样安装：

pip install git+https://github.com/allenai/ir_datasets.git

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

$ git clone https://github.com/allenai/ir_datasets
$ cd ir_datasets
$ python setup.py bdist_wheel
$ pip install dist/ir_datasets-*.whl

已在Python 3.7、3.8、3.9和3.10版本上测试。（最低Python版本为3.7。）

特性

Python和命令行接口。通过简单的Python API和命令行访问数据集。

import ir_datasets
dataset = ir_datasets.load('msmarco-passage/train')
# 文档
for doc in dataset.docs_iter():
    print(doc)
# GenericDoc(doc_id='0', text='The presence of communication amid scientific minds was equa...
# GenericDoc(doc_id='1', text='The Manhattan Project and its atomic bomb helped bring an en...
# ...

ir_datasets export msmarco-passage/train docs | head -n2
0 The presence of communication amid scientific minds was equally important to the success of the Manh...
1 The Manhattan Project and its atomic bomb helped bring an end to World War II. Its legacy of peacefu...

自动下载源文件（当可用时）。当查询、文档、qrels等公开可用时，将根据需要下载并验证源文件。 CI构建每周检查以确保所有可下载内容可用且正确：。我们在mirror.ir-datasets.com上镜像了一些有问题的文件，当原始源不可用时会自动切换到镜像。

import ir_datasets
dataset = ir_datasets.load('msmarco-passage/train')
for doc in dataset.docs_iter(): # 首次使用时将下载并解压MS-MARCO的collection.tar.gz
    ...
for query in dataset.queries_iter(): # 首次使用时将下载并解压MS-MARCO的queries.tar.gz
    ...

数据集访问说明（当不公开可用时）。当数据不公开在线可用时（例如，需要数据使用协议），提供如何获取数据副本的说明。

import ir_datasets
dataset = ir_datasets.load('trec-arabic')
for doc in dataset.docs_iter():
    ...
# 提供以下说明：
# 该数据集基于阿拉伯新闻通讯社语料库。可从LDC获取：<https://catalog.ldc.upenn.edu/LDC2001T55>
# 要继续，请将源文件符号链接到此处：[给出路径]

支持大小数据集。通过使用迭代器，支持可能不适合系统内存的大型数据集，如ClueWeb。

import ir_datasets
dataset = ir_datasets.load('clueweb09')
for doc in dataset.docs_iter():
    ... # 将遍历所有约10亿个文档

修复已知数据集问题。例如，自动纠正MS-MARCO段落集合中的文档UTF-8编码问题。

import ir_datasets
dataset = ir_datasets.load('msmarco-passage')
docstore = dataset.docs_store()
docstore.get('243').text
# "John Maynard Keynes, 1st Baron Keynes, CB, FBA (/ˈkeɪnz/ KAYNZ; 5 June 1883 – 21 April [略]"
# 简单的UTF-8解码会产生双重编码的问题，如：
# "John Maynard Keynes, 1st Baron Keynes, CB, FBA (/Ë\x88keÉªnz/ KAYNZ; 5 June 1883 â\x80\x93 21 April [略]"
#                                                  ~~~~~~  ~~                       ~~~~~~~~~

快速随机文档访问。 构建数据结构，允许快速高效地查找文档内容。对于大型数据集，如ClueWeb，使用检查点文件从源加载文档的速度比正常情况快40倍。结果会被缓存，使后续访问更快。

import ir_datasets
dataset = ir_datasets.load('clueweb12')
docstore = dataset.docs_store()
docstore.get_many(['clueweb12-0000tw-05-00014', 'clueweb12-0000tw-05-12119', 'clueweb12-0106wb-18-19516'])
# {'clueweb12-0000tw-05-00014': ..., 'clueweb12-0000tw-05-12119': ..., 'clueweb12-0106wb-18-19516': ...}

高级迭代切片。 有时能够选择数据范围很有帮助（例如，在多个设备上并行处理文档集合）。切片操作的高效实现允许比使用itertools.slice更快地进行数据集分区。

import ir_datasets
dataset = ir_datasets.load('clueweb12')
dataset.docs_iter()[500:1000] # 普通切片行为
# WarcDoc(doc_id='clueweb12-0000tw-00-00502', ...), WarcDoc(doc_id='clueweb12-0000tw-00-00503', ...), ...
dataset.docs_iter()[-10:-8] # 包括负索引
# WarcDoc(doc_id='clueweb12-1914wb-28-24245', ...), WarcDoc(doc_id='clueweb12-1914wb-28-24246', ...)
dataset.docs_iter()[::100] # 支持跳跃（仅正值）
# WarcDoc(doc_id='clueweb12-0000tw-00-00000', ...), WarcDoc(doc_id='clueweb12-0000tw-00-00100', ...), ...
dataset.docs_iter()[1/3:2/3] # 支持比例切片（这取集合的中间三分之一）
# WarcDoc(doc_id='clueweb12-0605wb-28-12714', ...), WarcDoc(doc_id='clueweb12-0605wb-28-12715', ...), ...

数据集

可用的数据集包括：

每个数据集下都有"子集"。例如，clueweb12/b13/trec-misinfo-2019提供了2019 TREC 错误信息轨道的查询和判断，而msmarco-document/orcas提供了ORCAS 数据集。它们通常以文档集合作为顶层进行组织。

有关每个数据集的详细信息、可用子集以及它们提供的数据，请参阅 ir_datasets 文档（ir_datasets.com）。

环境变量

IR_DATASETS_HOME：ir_datasets数据的主目录（默认为~/.ir_datasets/）。包含每个顶级数据集的目录。
IR_DATASETS_TMP：临时工作目录（默认为/tmp/ir_datasets/）。
IR_DATASETS_DL_TIMEOUT：下载流读取超时时间，以秒为单位（默认为15）。如果在此时间内未收到数据，将假定连接已断开，可能会尝试重新下载。
IR_DATASETS_DL_TRIES：抛出异常前的默认下载尝试次数（默认为3）。当服务器接受Range请求时，会使用它们。否则，将重新下载整个文件。
IR_DATASETS_DL_DISABLE_PBAR：设置为true以禁用下载进度条。在无法使用交互式控制台的环境中很有用。
IR_DATASETS_DL_SKIP_SSL：设置为true以在下载文件时禁用SSL证书检查。当SSL证书过期或无效时，可作为短期解决方案。请注意，这不会禁用下载内容的哈希验证。
IR_DATASETS_SKIP_DISK_FREE：设置为true以禁用在下载内容或创建大文件之前检查磁盘是否有足够的可用空间。
IR_DATASETS_SMALL_FILE_SIZE：被视为"小"文件的大小，以字节为单位。不显示链接小文件而不是下载它们的说明。默认为5000000（5MB）。

引用

使用本包提供的数据集时，请务必正确引用。每个数据集的Bibtex引用可在数据集文档页面上找到。

如果您使用了这个工具，请引用我们的SIGIR资源论文：

@inproceedings{macavaney:sigir2021-irds,
  author = {MacAvaney, Sean and Yates, Andrew and Feldman, Sergey and Downey, Doug and Cohan, Arman and Goharian, Nazli},
  title = {Simplified Data Wrangling with ir_datasets},
  year = {2021},
  booktitle = {SIGIR}
}