Reranking
Reorder the first page with your own cross-encoder endpoint — configuration, the HTTP contract, timeouts and how to see what changed.
A reranker re-scores the top results of the first page with a cross-encoder
model you host (for example bge-reranker-v2-m3 behind a small HTTP service).
It is an HTTP scorer, not an LLM: the search hot path stays fast and predictable.
Configuration
Index → Search settings → Reranking, stored as settings.search.rerank:
| Key | Meaning |
|---|---|
enabled | On / off |
provider | http |
url | Your endpoint: https://, or http://localhost outside production |
model | Optional, passed through to your endpoint |
topN | Hits sent for scoring, 1–50 |
timeoutMs | Hard timeout, 10–150 ms |
fields | Up to 8 document fields concatenated into the text |
The contract your endpoint implements
POST <url>
Content-Type: application/json
{ "query": "trail shoe", "documents": [{ "id": "sku-1", "text": "Trail shoe\nAcme" }], "model": "bge-reranker-v2-m3" }{ "scores": [0.91] }documentsare the top-N of the first page after ACL, filters and rules. Hits pinned or hidden by a rule are not sent and keep their place.textis the configuredfieldsjoined with\n, at most 2000 characters. Private fields are never sent for an unprivileged call.- Return exactly one finite number per document, in the same order. Higher ranks higher. Equal scores keep the engine order.
- Requests go through the platform's outbound-URL guard: no redirects, no private networks.
Failure is invisible to users
On timeout, non-200, invalid JSON or a wrong number of scores, the original order is returned and the response says why:
{ "rerank": "skipped:timeout" }Reasons: timeout, http_<status>, bad_json, bad_shape, unsafe_url, error.
A successful pass reports "rerank": "applied". Skipped responses are not stored
in the result cache.
What reranking never does
- It never adds documents and never changes
found. - It does not touch page 2 and beyond.
Seeing what moved
Hits moved by the reranker carry a reason of kind rerank in hit_reasons.
With explain=true the response also contains
explain.rerank = { applied, topN, tookMs, skipped? }.
Known limit
When diversity (MMR) is enabled on the index it is applied after reranking and may reorder some reranked hits again.