Rerank
POST /v1/rerank: give a question and a list of passages, and get them back in order of how well
each one answers it. Served by BGE Reranker v2 M3 as bge-reranker-v2-m3, in the request and answer
shape Cohere and Jina use. €0.01 / 1M tokens.
The usual place is right after embeddings: embeddings find the 20 to 50 passages closest to the question, the reranker reads the question together with each of them and puts the ones that answer it first, and the best few go to the chat model.
Request & response
curl https://api.axforge.ai/v1/rerank \
-H "Authorization: Bearer $AXFORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bge-reranker-v2-m3",
"query": "When is the invoice due?",
"documents": ["The office is closed on Mondays.", "Payment is due within 30 days of the invoice date.", "Invoices are sent by email."],
"top_n": 2
}'$body = @{
model = 'bge-reranker-v2-m3'
query = 'When is the invoice due?'
documents = @('The office is closed on Mondays.', 'Payment is due within 30 days of the invoice date.', 'Invoices are sent by email.')
top_n = 2
} | ConvertTo-Json
$r = Invoke-RestMethod https://api.axforge.ai/v1/rerank -Method Post `
-Headers @{ Authorization = "Bearer $env:AXFORGE_API_KEY" } `
-ContentType 'application/json' -Body $body
$r.results[0].index # 1curl -s https://api.axforge.ai/v1/rerank -H "Authorization: Bearer %AXFORGE_API_KEY%" -H "Content-Type: application/json" -d "{\"model\":\"bge-reranker-v2-m3\",\"query\":\"When is the invoice due?\",\"documents\":[\"The office is closed on Mondays.\",\"Payment is due within 30 days of the invoice date.\",\"Invoices are sent by email.\"],\"top_n\":2}"{
"model": "bge-reranker-v2-m3",
"results": [
{"index": 1, "document": {"text": "Payment is due within 30 days of the invoice date."}, "relevance_score": 0.91},
{"index": 2, "document": {"text": "Invoices are sent by email."}, "relevance_score": 0.01}
],
"usage": {"prompt_tokens": 66, "total_tokens": 66}
}The request
| Field | Meaning |
|---|---|
| model | bge-reranker-v2-m3 (or rerank). |
| query | The question. |
| documents | The passages to order, as strings. |
| top_n | Optional. Only the best this many come back. |
In the answer, results are ordered best first. index is the passage's position in
documents, and relevance_score runs from 0 (does not answer it) to 1.
From your code
import os
import requests
passages = ["The office is closed on Mondays.",
"Payment is due within 30 days of the invoice date.",
"Invoices are sent by email."]
r = requests.post(
"https://api.axforge.ai/v1/rerank",
headers={"Authorization": "Bearer " + os.environ["AXFORGE_API_KEY"]},
json={"model": "bge-reranker-v2-m3", "query": "When is the invoice due?", "documents": passages, "top_n": 2},
timeout=60,
)
for hit in r.json()["results"]:
print(round(hit["relevance_score"], 2), passages[hit["index"]])const passages = ["The office is closed on Mondays.",
"Payment is due within 30 days of the invoice date.",
"Invoices are sent by email."];
const r = await fetch("https://api.axforge.ai/v1/rerank", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.AXFORGE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ model: "bge-reranker-v2-m3", query: "When is the invoice due?", documents: passages, top_n: 2 }),
});
for (const hit of (await r.json()).results) console.log(hit.relevance_score.toFixed(2), passages[hit.index]);Specs
| Model | bge-reranker-v2-m3 |
|---|---|
| Languages | 100+ |
| Context | 4,096 tokens for the query and one passage together |
| Price | €0.01 / 1M tokens |
Every passage is read together with the question, so the tokens counted are the question's once per passage plus each passage's own. All input is processed with zero retention, like every endpoint here.