rerankers: Unified API for Reranking and Cross-Encoder Models

Introduction

rerankers is a lightweight, low-dependency Python library developed by Answer.AI that offers a unified API for integrating various reranking and cross-encoder models into your applications. Its primary goal is to simplify the use of diverse reranking approaches, providing a consistent interface regardless of the underlying model architecture. This makes it easier for developers to experiment with and deploy different rerankers in their retrieval pipelines.

Installation

The core rerankers package is designed to be dependency-free by default, avoiding conflicts with your existing environment. You can then install specific dependencies based on the models you intend to use.

# Core package only, will require other dependencies already installed
pip install rerankers

# All transformers-based approaches (cross-encoders, t5, colbert)
pip install "rerankers[transformers]"

# RankGPT
pip install "rerankers[gpt]"

# API-based rerankers (Cohere, Jina, MixedBread, Pinecone, Isaacus)
pip install "rerankers[api]"

# FlashRank rerankers (ONNX-optimised, very fast on CPU)
pip install "rerankers[flashrank]"

# RankLLM rerankers (better RankGPT + support for local models such as RankZephyr and RankVicuna)
# Note: RankLLM is only supported on Python 3.10+! This will not work with Python 3.9
pip install "rerankers[rankllm]"

# To support Multi-Modal rerankers such as MonoQwen2-VL and other MonoVLM models, which require flash-attention, peft, accelerate, and recent versions of `transformers`
pip install "rerankers[monovlm]"

# To support LLM-Layerwise rerankers (which need flash-attention installed)
pip install "rerankers[llmlayerwise]"

# All of the above
pip install "rerankers[all]"

Examples

Using rerankers is straightforward. You can load any supported reranker with a single line of code and then use its rank method to reorder documents based on a query.

from rerankers import Reranker, Document

# Load a default cross-encoder
ranker = Reranker('cross-encoder')

# Load a specific cross-encoder model
ranker = Reranker('mixedbread-ai/mxbai-rerank-large-v1', model_type='cross-encoder')

# Load an API-based reranker (e.g., Cohere)
# ranker = Reranker("cohere", lang='en', api_key = "YOUR_API_KEY")

# Load RankGPT
# ranker = Reranker("rankgpt", api_key = "YOUR_API_KEY")

# Define your query and documents
query = "I love you"
docs = [
    Document(text="I really like you", doc_id=0, metadata={'source': 'twitter'}),
    Document(text="I hate you", doc_id=1, metadata={'source': 'reddit'})
]

# Rank the documents
results = ranker.rank(query=query, docs=docs)

# Print the ranked results
print(results)
# Example output:
# RankedResults(results=[Result(document=Document(text='I really like you', doc_id=0, metadata={'source': 'twitter'}), score=-2.453125, rank=1), Result(document=Document(text='I hate you', doc_id=1, metadata={'source': 'reddit'}), score=-4.14453125, rank=2)], query='I love you', has_scores=True)

# Access top k results
top_result = results.top_k(1)[0]
print(top_result.text) # 'I really like you'
print(top_result.document.metadata) # {'source': 'twitter'}

Why use rerankers?

Rerankers are a crucial component in modern retrieval architectures, yet their implementation can often be complex and fragmented. Different reranking methods, from traditional cross-encoders to advanced LLM-based approaches like RankGPT, often reside in separate libraries with inconsistent APIs and varying levels of documentation. This creates a significant barrier to entry for developers and makes it challenging to compare and integrate different models.

rerankers addresses these issues by providing a simple, unified API. It aims to be:

Lightweight: Ships with only essential dependencies.
Easy-to-understand: Offers a minimal set of calls to learn, enabling access to a wide range of models.
Easy-to-integrate: Designed to fit seamlessly into existing pipelines with minimal code changes.
Easy-to-expand: New reranking models can be added with little effort, requiring only a class with a rank() function.

By centralizing access to various reranking models, rerankers empowers developers to efficiently build and optimize their information retrieval systems.