Rerankers (original) (raw)

A reranker, given a query and many documents, returns the (ranks of) relevancy between the query and documents. The documents oftentimes are the preliminary results from an embedding-based retrieval system, and the reranker refines the ranks of these candidate documents and provides more accurate relevancy scores.

Unlike embedding models that encode queries and documents separately, rerankers are cross-encoders that jointly process a pair of query and document, enabling more accurate relevancy prediction. Thus, it is a common practice to apply a reranker on the top candidates retrieved with embedding-based search (or with lexical search algorithms such as BM25 and TF-IDF).

Voyage currently provides the following reranker models:

Model Context Length (tokens) Description
rerank-2.5 32,000 Our generalist reranker optimized for quality with instruction-following and multilingual support. See blog post for details.
rerank-2.5-lite 32,000 Our generalist reranker optimized for both latency and quality with instruction-following and multilingual support. See blog post for details.

Older models

The following are our earlier models, which are still accessible from our API. We recommend using the new models above for better quality and efficiency. Our latest models listed in the above table will be strictly better than the legacy models in all aspects, such as quality, context length, latency, and throughput.

Model Context Length (tokens) Description
rerank-2 16,000 Our generalist second-generation reranker optimized for quality with multilingual support. See blog post for details.
rerank-2-lite 8000 Our generalist second-generation reranker optimized for both latency and quality with multilingual support. See blog post for details.
rerank-1 8000 Our generalist first-generation reranker optimized for quality. Multilingual support. See blog post for details.
rerank-lite-1 4000 Our generalist first-generation reranker optimized for both latency and quality. See blog post for details.

Voyage reranker is accessible in Python through the voyageai package. Please first install the voyageai package and setup the API key.

Voyage reranker receives as input a query and a list of candidate documents, e.g., the documents retrieved by a nearest neighbor search with embeddings. It reranks the candidate documents according to their semantic relevances to the search query, and returns the list of relevance scores. To access the reranker, create a voyageai.Client object and use its rerank() method.

voyageai.Client.rerank (query: str, documents: List[str], model: str, top_k: Optional[int] = None, truncation: bool = True)

Parameters

Returns

Example

import voyageai

vo = voyageai.Client()
# This will automatically use the environment variable VOYAGE_API_KEY.
# Alternatively, you can use vo = voyageai.Client(api_key="<your secret key>")

query = "When is Apple's conference call scheduled?"
documents = [
    "The Mediterranean diet emphasizes fish, olive oil, and vegetables, believed to reduce chronic diseases.",
    "Photosynthesis in plants converts light energy into glucose and produces essential oxygen.",
    "20th-century innovations, from radios to smartphones, centered on electronic advancements.",
    "Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.",
    "Apple’s conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.",
    "Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature."
]

reranking = vo.rerank(query, documents, model="rerank-2.5", top_k=3)
for r in reranking.results:
    print(f"Document: {r.document}")
    print(f"Relevance Score: {r.relevance_score}")
    print()
Document: Apple’s conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.
Relevance Score: 0.94140625
Index: 0


Document: 20th-century innovations, from radios to smartphones, centered on electronic advancements.
Relevance Score: 0.28515625
Index: 1


Document: Photosynthesis in plants converts light energy into glucose and produces essential oxygen.
Relevance Score: 0.255859375
Index: 2

Voyage reranker can be accessed by calling the endpoint POST https://api.voyageai.com/v1/rerank. Please refer to the Reranker API Reference for the specification.

Example

curl https://api.voyageai.com/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -d '{
    "query": "Sample query",
    "documents": [
        "Sample document 1",
        "Sample document 2"
    ],
    "model": "rerank-2"
  }'

Voyage rerankers are accessible in TypeScript through the Voyage TypeScript Library, which exposes all the functionality of our reranker endpoint (see Reranker API Reference).

For a full tutorial on using Voyage rerankers, see our detailed guide.

The Jupyter Notebook for this tutorial is available on GitHub in our GenAI Showcase repository. To follow along, run the notebook in Google Colab or your preferred environment, and refer to the tutorial for explanations of key code blocks.