Anserini

Anserini is a toolkit for reproducible information retrieval research. By building on Lucene, we aim to bridge the gap between academic information retrieval research and the practice of building real-world search applications. Among other goals, our effort aims to be the opposite of this.* Anserini grew out of a reproducibility study of various open-source retrieval engines in 2016 (Lin et al., ECIR 2016). See Yang et al. (SIGIR 2017) and Yang et al. (JDIQ 2018) for overviews.

NOTE: Anserini was upgraded to Lucene 9.3 at commit 272565 (8/2/2022): this upgrade created backward compatibility issues, see #1952. Anserini will automatically detect Lucene 8 indexes and disable consistent tie-breaking to avoid runtime errors. However, Lucene 9 code running on Lucene 8 indexes may give slightly different results than Lucene 8 code running on Lucene 8 indexes. Lucene 8 code will not run on Lucene 9 indexes. Pyserini has also been upgraded and similar issues apply: Lucene 9 code running on Lucene 8 indexes may give slightly different results than Lucene 8 code running on Lucene 8 indexes.

🎬 Getting Started

Many Anserini features are exposed in the Pyserini Python interface. If you're looking for basic indexing and search capabilities, you might want to start there. A low-effort way to try out Anserini is to look at our online notebooks, which will allow you to get started with just a few clicks.

You'll need Java 11 and Maven 3.3+ to build Anserini. Clone our repo with the --recurse-submodules option to make sure the eval/ submodule also gets cloned (alternatively, use git submodule update --init). Then, build using using Maven:

mvn clean package appassembler:assemble

Note that on Windows, tests may fail due to encoding issues, see #1466. A simple workaround is to skip tests by adding -Dmaven.test.skip=true to the above mvn command. See #1121 for additional discussions on debugging Windows build errors.

The tools/ directory, which contains evaluation tools and other scripts, is actually this repo, integrated as a Git submodule (so that it can be shared across related projects). Build as follows (you might get warnings, but okay to ignore):

cd tools/eval && tar xvfz trec_eval.9.0.4.tar.gz && cd trec_eval.9.0.4 && make && cd ../../..
cd tools/eval/ndeval && make && cd ../../..

With that, you should be ready to go!

⚗️ Regression Experiments (+ Reproduction Guides)

Anserini is designed to support experiments on various standard IR test collections out of the box. The following experiments are backed by rigorous end-to-end regression tests with run_regression.py and the Anserini reproducibility promise. For the most part, these runs are based on default parameter settings. These pages can also serve as guides to reproduce our results. See individual pages for details!

📃 Additional Documentation

The experiments described below are not associated with rigorous end-to-end regression testing and thus provide a lower standard of reproducibility. For the most part, manual copying and pasting of commands into a shell is required to reproduce our results.

MS MARCO (V1)

• Reproducing BM25 baselines for MS MARCO Passage Ranking
• Reproducing BM25 baselines for MS MARCO Document Ranking
• Reproducing baselines for the MS MARCO Document Ranking Leaderboard
• Reproducing doc2query results (MS MARCO Passage Ranking and TREC-CAR)
• Reproducing docTTTTTquery results (MS MARCO Passage and Document Ranking)
• Notes about reproduction issues with MS MARCO Document Ranking w/ docTTTTTquery

MS MARCO (V2)

• Reproducing BM25 baselines on the MS MARCO V2 Collections

TREC-COVID and CORD-19

• Indexing AI2's COVID-19 Open Research Dataset
• Baselines for the TREC-COVID Challenge
• Baselines for the TREC-COVID Challenge using doc2query
• Ingesting AI2's COVID-19 Open Research Dataset into Solr and Elasticsearch

Other Experiments

• Working with the 20 Newsgroups Dataset
• Guide to BM25 baselines for the FEVER Fact Verification Task
• Guide to reproducing "Neural Hype" Experiments
• Guide to running experiments on the AI2 Open Research Corpus
• Experiments from Yang et al. (JDIQ 2018)
• Runbooks for TREC 2018: [Anserini group] [h2oloo group]
• Runbook for ECIR 2019 paper on axiomatic semantic term matching
• Runbook for ECIR 2019 paper on cross-collection relevance feedback

Other Features

• Use Anserini in Python via Pyserini
• Anserini integrates with SolrCloud via Solrini
• Anserini integrates with Elasticsearch via Elasterini
• Anserini supports approximate nearest-neighbor search on arbitrary dense vectors with Lucene

🙋 How Can I Contribute?

If you've found Anserini to be helpful, we have a simple request for you to contribute back. In the course of reproducing baseline results on standard test collections, please let us know if you're successful by sending us a pull request with a simple note, like what appears at the bottom of the page for Disks 4 & 5. Reproducibility is important to us, and we'd like to know about successes as well as failures. Since the regression documentation is auto-generated, pull requests should be sent against the raw templates. Then the regression documentation can be generated using the bin/build.sh script. In turn, you'll be recognized as a contributor.

Beyond that, there are always open issues we would appreciate help on!

ℹ️ Release History

• v0.21.0: March 31, 2023 [Release Notes]
• v0.20.0: January 20, 2023 [Release Notes]
• v0.16.2: December 12, 2022 [Release Notes]
• v0.16.1: November 2, 2022 [Release Notes]
• v0.16.0: October 23, 2022 [Release Notes]
• v0.15.0: September 22, 2022 [Release Notes]
• v0.14.4: July 31, 2022 [Release Notes]
• v0.14.3: May 9, 2022 [Release Notes]
• v0.14.2: March 24, 2022 [Release Notes]
• v0.14.1: February 27, 2022 [Release Notes]
• v0.14.0: January 10, 2022 [Release Notes]

✨ References

• Jimmy Lin, Matt Crane, Andrew Trotman, Jamie Callan, Ishan Chattopadhyaya, John Foley, Grant Ingersoll, Craig Macdonald, Sebastiano Vigna. Toward Reproducible Baselines: The Open-Source IR Reproducibility Challenge. ECIR 2016.
• Peilin Yang, Hui Fang, and Jimmy Lin. Anserini: Enabling the Use of Lucene for Information Retrieval Research. SIGIR 2017.
• Peilin Yang, Hui Fang, and Jimmy Lin. Anserini: Reproducible Ranking Baselines Using Lucene. Journal of Data and Information Quality, 10(4), Article 16, 2018.

🙏 Acknowledgments

This research is supported in part by the Natural Sciences and Engineering Research Council (NSERC) of Canada. Previous support came from the U.S. National Science Foundation under IIS-1423002 and CNS-1405688. Any opinions, findings, and conclusions or recommendations expressed do not necessarily reflect the views of the sponsors.