Skip to content

Rerank API

The Rerank API improves the accuracy of search systems by re-evaluating the relevance of documents retrieved from an initial search (like vector lookup). It uses a "Cross-Encoder" approach to jointly process the query and each document for superior ranking precision.

Base URL

https://llm.siraya.pro/v1/rerank

How it Works

  1. Retrieval: Fetch a candidate list of documents (e.g., top 100) using embeddings or keyword search.
  2. Reranking: Send the query and candidates to the Rerank API.
  3. Result: Receive the documents sorted by their actual semantic relevance to the query.

Example Request

import requests

url = "https://llm.siraya.pro/v1/rerank"
headers = {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
}

data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital of Nevada.",
        "Washington, D.C. is the capital of the United States.",
        "Albany is the capital of New York state."
    ]
}

response = requests.post(url, headers=headers, json=data)
results = response.json()["results"]

for res in results:
    print(f"Rank: {res['index']}, Score: {res['relevance_score']}")

curl https://llm.siraya.pro/v1/rerank \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital of Nevada.",
        "Washington, D.C. is the capital of the United States.",
        "Albany is the capital of New York state."
    ]
  }'

Request Parameters

Parameter Type Description
model string The ID of the reranker model (e.g., voyage-rerank-2.5, jina-reranker-v2-base-multilingual).
query string The search query.
documents array An array of strings representing the document contents to be ranked.
top_n integer (Optional) The number of top results to return.

Tips for Better Performance

  • Structured Data: If your documents contain structured fields, formatting them as YAML strings often yields better reranking results than plain JSON or flat text.
  • Max Documents: Most rerankers perform best when given between 50 and 100 candidate documents.

Supported providers include Voyage AI, Jina, and more. See the Models Directory for a full list.