> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/products/serverless-inference/reranking.md).

# Reranking

Reorder retrieved documents by relevance with Nebula Block's reranking models, the second stage of a RAG pipeline.

A reranker scores how relevant each document is to a query. It is the second stage of a typical retrieval pipeline: use [embeddings](/products/serverless-inference/embeddings.md) to pull back a few dozen candidates cheaply, then rerank them to put the best ones on top before you spend tokens sending them to a model.

## Models available

| Model                   | Model ID                  | Notes                                           |
| ----------------------- | ------------------------- | ----------------------------------------------- |
| BGE-reranker-v2-m3 🇨🇦 | `BAAI/bge-reranker-v2-m3` | Multilingual, 568M parameters, hosted in Canada |

See the [Model Catalog](/products/serverless-inference/model-catalog.md#reranking) for the current list.

## Rerank documents

```bash
curl -X POST "https://inference.nebulablock.com/v1/rerank" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $NEBULA_API_KEY" \
    --data-raw '{
        "model": "BAAI/bge-reranker-v2-m3",
        "query": "How do I rent a GPU by the hour?",
        "documents": [
            "Object Storage is an S3-compatible service for datasets and checkpoints.",
            "GPU instances are billed hourly and can be deployed in minutes from the console.",
            "Tier 3 requires a $10 deposit."
        ],
        "top_n": 2
    }'
```

The response ranks the documents by `relevance_score`, highest first, with `index` pointing back at the position in the `documents` array you sent:

```json
{
  "id": "rerank-...",
  "results": [
    { "index": 1, "relevance_score": 0.98 },
    { "index": 2, "relevance_score": 0.41 }
  ]
}
```

### Python

```python
import os

import requests

response = requests.post(
    "https://inference.nebulablock.com/v1/rerank",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['NEBULA_API_KEY']}",
    },
    json={
        "model": "BAAI/bge-reranker-v2-m3",
        "query": "How do I rent a GPU by the hour?",
        "documents": documents,
        "top_n": 5,
    },
)

for hit in response.json()["results"]:
    print(hit["relevance_score"], documents[hit["index"]])
```

## Using it in a RAG pipeline

1. Embed your corpus once with [Embeddings](/products/serverless-inference/embeddings.md) and store the vectors.
2. At query time, embed the query and retrieve the top 25–100 candidates by vector similarity.
3. Rerank those candidates and keep the top 3–5.
4. Put only those into the prompt you send to [Chat Completions](/products/serverless-inference/text-generation.md).

Reranking is far cheaper than sending every candidate to a large model, and it usually improves answer quality more than swapping in a bigger generation model does.

## See also

* [Rerank API reference](/api-reference/inference-api/rerank.md)
* [Embeddings](/products/serverless-inference/embeddings.md)
* [Model Catalog](/products/serverless-inference/model-catalog.md)