# Rerank


# 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     # 1
```

```
curl -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.

      ← Embeddings
      Xev decisions →



Source: https://dev.axforge.ai/docs/rerank/