Noemad Docs

Rerank

Relevance ordering for a bounded set of candidate documents.

Integration guide · planned capabilities. Model-specific capabilities, usage rates, and x402 upto settlement require backend implementation and validation. The preview runs local samples; documented contracts do not imply live availability.

Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.

Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization.

A second pass after retrieval

POST /v1/rerank scores supplied documents against a query and returns original document indexes in descending relevance. Use it after keyword or vector retrieval to select useful context for a model.

Discover models with GET /v1/models?type=rerank. A model-specific score is not a calibrated universal probability; evaluate thresholds on representative data.

Archived rerank records

Model specification reference. Names and capability limits come from the imported catalog snapshot. Enabled models require fresh qualification. USD rates below are listed only when verified for the exact model against an official source; unverified prices are marked.

Model reference	Candidate bound	Languages
BGE Reranker Base `bge-reranker-base`	100 documents	multilingual
Voyage rerank-3 `voyage-rerank-3`	100 documents	multilingual
Voyage rerank-3-lite `voyage-rerank-3-lite`	100 documents	multilingual
Voyage rerank-2.5 `voyage-rerank-2.5`	100 documents	multilingual
Voyage rerank-2.5-lite `voyage-rerank-2.5-lite`	100 documents	multilingual

Request limits

Field	Reference contract
model	An explicit qualified rerank model; do not rely on a hidden default
query	Required, non-empty, up to 2,048 characters
documents	1–100 strings; up to 8,192 characters per document
top_n	1 through the supplied document count; omitted means all candidates

json

{
  "model": "MODEL_ID_FROM_DISCOVERY",
  "query": "How can I improve a product brief?",
  "documents": [
    "Begin with the user problem and the intended outcome.",
    "A recipe for sourdough bread.",
    "List the constraints, owner, and next decision."
  ],
  "top_n": 2
}

Response

json

{
  "object": "list",
  "model": "MODEL_ID_FROM_DISCOVERY",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.94
    },
    {
      "index": 2,
      "relevance_score": 0.87
    }
  ]
}

Indexes refer to the original input order. Verify uniqueness, bounds, finite scores, and the requested result count. Keep the original candidates in the application rather than trusting a returned index without validation.

Language and quality

Ranking often works best when query and documents use compatible languages. Test Indonesian, Malay, English, and mixed-language cases with realistic candidates before qualifying a model. Record model and profile version when comparing evaluation results.

All submitted candidates count

The archived rerank billing basis includes the query and every submitted document with a model-specific minimum. top_n limits returned results; it does not reduce the input processed or quoted. The exact tokenizer and unit belong to the selected adapter’s price snapshot.

Authorize the bounded request maximum and collect the measured actual amount. A failure or unknown outcome must be classified and reconciled before another chargeable attempt.

PreviousEmbeddings NextStructured evaluation →