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).

Model Specifics

Voyage currently provides the following reranker models.

Python API

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

• query (str) - The query as a string. The query can contain a maximum of 1000 tokens for rerank-lite-1 and 2000 tokens for rerank-1.
• documents (List[str]) - The documents to be reranked as a list of strings.
  • The number of documents cannot exceed 1000.
  • The sum of the number of tokens in the query and the number of tokens in any single document cannot exceed 4000 for rerank-lite-1 and 8000 for rerank-1.
  • The total number of tokens, defined as "the number of query tokens × the number of documents + sum of the number of tokens in all documents", cannot exceed 300K for rerank-lite-1 and 100K for rerank-1. Please see our FAQ.
• model (str) - Name of the model. Recommended options: rerank-lite-1, rerank-1.
• top_k (int, optional, defaults to None) - The number of most relevant documents to return. If not specified, the reranking results of all documents will be returned.
• truncation (bool, optional, defaults to True) - Whether to truncate the input to satisfy the "context length limit" on the query and the documents.
  • If True, the query and documents will be truncated to fit within the context length limit, before processed by the reranker model.
  • If False, an error will be raised when the query exceeds 1000 tokens for rerank-lite-1 and 2000 tokens for rerank-1, or the sum of the number of tokens in the query and the number of tokens in any single document exceeds 4000 for rerank-lite-1 and 8000 for rerank-1.

Returns

• A RerankingObject, containing the following attributes:
  • results (List[RerankingResult]) - A list of RerankingResult, with format specified below, sorted by the descending order of relevance scores. The length of the list equals to top_k if this argument is specified, otherwise the number of the input documents. Each element in the list is a RerankingResult object, which contains attributes:
    • index (int) - The index of the document in the input list.
    • document (str) - The document as a string.
    • relevance_score (float) - The relevance score of the document with respect to the query.
  • total_tokens (int) - The total number of tokens in the input, which is defined as "the number of query tokens × the number of documents + sum of the number of tokens in all documents".

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-lite-1", top_k=3)
for r in reranking.results:
    print(f"Document: {r.document}")
    print(f"Relevance Score: {r.relevance_score}")

REST API

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-lite-1"
  }'