Reranking

Reranking scores how relevant each document is to a query and returns them ordered best-first. It is the second half of a retrieval-augmented generation (RAG) pipeline: a first pass with embeddings casts a wide net and pulls back, say, the top 50 candidates; a reranker then reads each query-and-document pair together and sorts them by true relevance, so you can keep just the handful you actually feed to the model.

Embeddings compare a query and a document by their vectors, computed separately. A reranker is a cross-encoder — it looks at the query and the document at the same time — which makes it more accurate at judging relevance, at the cost of running once per document. That's why it's used to re-sort a shortlist rather than to search the whole corpus.

Rerank a shortlist

Send a query and the list of documents to score. You get back a results array sorted by relevance_score (highest first), where each result's index points back to the document's position in your original list. Use top_n to keep only the best few.

import requests

resp = requests.post(
    "https://api.pendra.ai/v1/rerank",
    headers={"Authorization": "Bearer pdr_sk_..."},
    json={
        "model": "bge-reranker-v2-m3",
        "query": "How do I rotate an API key?",
        "documents": [
            "Billing is invoiced monthly.",
            "Create a new key, then revoke the old one.",
            "API keys are shown only once at creation.",
        ],
        "top_n": 2,
    },
)
for r in resp.json()["results"]:
    print(r["index"], round(r["relevance_score"], 3))

const resp = await fetch('https://api.pendra.ai/v1/rerank', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pdr_sk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bge-reranker-v2-m3',
    query: 'How do I rotate an API key?',
    documents: [
      'Billing is invoiced monthly.',
      'Create a new key, then revoke the old one.',
      'API keys are shown only once at creation.',
    ],
    top_n: 2,
  }),
});
const { results } = await resp.json();
for (const r of results) {
  console.log(r.index, r.relevance_score.toFixed(3));
}

1 8.734    # "Create a new key, then revoke the old one."
0 -4.219   # "Billing is invoiced monthly."

The most relevant document (index 1) comes first. Scores are raw relevance values — higher means more relevant — and are only meaningful relative to each other within a single request, not as absolute or normalized numbers.

Choosing a model

Pendra ships bge-reranker-v2-m3, a multilingual cross-encoder that handles long documents (up to 8K tokens). Browse the options at /models?type=rerank.

A typical RAG flow

1. Embed your documents once and store the vectors.
2. At query time, embed the query and pull the top ~20–50 nearest documents.
3. Rerank those candidates against the query and keep the top few.
4. Pass the survivors to a chat model as context.