Rerank

Kandidatendokumente nach Relevanz zu einer Anfrage ordnen: Anfrageformat, Grenzen, Kosten und Fehler.

Wann nutzen

Rerank ist der zweite Schritt des Retrievals. Eine Vektor- oder Stichwortsuche liefert schnell etwa 100 Kandidaten; ein Rerank-Modell liest die Anfrage zusammen mit jedem Kandidaten und ordnet sie viel genauer. Danach gehen die besten wenigen an das Chat-Modell. Rerank durchsucht keine Datenbank und erzeugt keine Antwort. Für den ersten Schritt siehe Embeddings.

Minimalbeispiel

Eine Anfrage und zwei Dokumente; top_n begrenzt das Ergebnis auf den besten Treffer.

curl

curl --request POST \
  --url 'https://api.tokenlane.de/v1/rerank' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "documents": [
    "Paris is in France.",
    "A recipe for soup."
  ],
  "top_n": 1
}'

node

const response = await fetch("https://api.tokenlane.de/v1/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "documents": [
    "Paris is in France.",
    "A recipe for soup."
  ],
  "top_n": 1
}`,
});
console.log(await response.text());

python

import os
import urllib.request

body = (r'''{
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "documents": [
    "Paris is in France.",
    "A recipe for soup."
  ],
  "top_n": 1
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/rerank",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

vercel

// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/rerank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "model": "baai/bge-reranker-v2-m3",
  "query": "European capital",
  "documents": [
    "Paris is in France.",
    "A recipe for soup."
  ],
  "top_n": 1
}`,
});
console.log(await response.text());

Jedes Ergebnis hat den index des Dokuments in der eigenen Liste, einen relevance_score und das gesendete document. Die Liste ist nach Relevanz absteigend sortiert.

Anfrageformat

FeldWert
modelPflicht. Ein Rerank-Modell. Ein Chat-Modell scheitert mit 404 no_endpoint.
queryPflicht. Text, höchstens 65.536 UTF-8-Bytes, nicht leer.
documentsPflicht. 1 bis 1.000 Elemente. Jedes ist ein String oder ein Objekt mit einem nicht leeren String text, höchstens 65.536 UTF-8-Bytes. Anfrage und Dokumente zusammen höchstens 4 MiB Text.
top_nGanzzahl ab 1 bis zur Zahl der Dokumente. Standard: alle Dokumente.
return_documentsBoolean. Aus Kompatibilitätsgründen angenommen, ohne Wirkung: Jedes Ergebnis trägt document, ob das Feld fehlt, true oder false ist. null oder ein anderer Typ scheitert mit 400.
providerRouting wie beim Chat.

Was der Anbieter erhält und was zurückkommt

Die Antwort enthält immer die eigenen Dokumente, denn das Rerank-Format von OpenRouter verlangt in jedem Ergebnis ein document. Eine Option nur für Index und Score gibt es nicht.

Teil der AnfrageAn den Anbieter gesendetAn den Aufrufer zurück
queryJa, unverändert.Nein.
Text jedes DokumentsJa, alle Dokumente in der eigenen Reihenfolge, auch mit top_n.Ja, in results[].document.text, nur für die zurückgegebenen Ergebnisse.
Weitere Felder eines Dokumentobjekts (eigene ID, Titel, verschachtelte Metadaten)Nein.Ja, unverändert in results[].document.
top_nNein. Das Gateway ordnet alle Dokumente und behält danach die besten top_n.Nur so viele Ergebnisse.
return_documentsNein.Ohne Wirkung.
modelDie Modell-ID des Anbieters für die Route.Die öffentliche Modell-ID in model.

Ein String-Dokument kommt als Objekt mit text zurück, ein Objekt mit allen seinen Feldern. Die eigene ID in das Dokumentobjekt zu schreiben spart das Zurückrechnen von index:

"documents": [{ "text": "Madrid is in Spain.", "id": "doc-9", "source": "wiki" }]

Das zugehörige Ergebnis:

{ "document": { "id": "doc-9", "source": "wiki", "text": "Madrid is in Spain." }, "index": 0, "relevance_score": 0.91 }

Alles in document ist die eigene Eingabe; nichts wird ergänzt. Wer die Ergebnisse an einen Browser, ein Log oder einen anderen Dienst weitergibt, entfernt vorher document oder die Felder, die nicht mitgehen sollen.

Antwortfelder:

FeldBedeutung
results[].indexNullbasierte Position in documents.
results[].relevance_scoreEine Zahl von 0 bis 1. Absteigend sortiert; gleiche Werte behalten die eigene Reihenfolge.
results[].documentImmer. Das gesendete Dokument: ein String als { "text": … }, ein Objekt mit allen seinen Feldern.
usageprompt_tokens, total_tokens, estimated, cost (EUR).
id, model, providerGenerierungs-ID (auch in x-generation-id), das Modell und der Anbieter, der geantwortet hat.

Das Gateway prüft die Rangliste des Anbieters: Werte außerhalb von 0 bis 1, ein fehlender oder doppelter Index oder eine fehlerhafte Antwort werden zu 502 provider_invalid_response, und der nächste Anbieter wird versucht.

Jedes Paar aus Anfrage und Dokument muss in den Kontext des Modells passen (geschätzt werden 4 Bytes Text je Token). Bei einem Kontext von 8.192 Tokens sind das etwa 32 KB je Paar; ein längeres Paar scheitert mit 400 context_length_exceeded.

Modell wählen

Ein Modell wählen, das den Rerank-Endpunkt bedient. Im Katalog nimmt es Text als Eingabe, zeigt einen Preis je Anfrage (pricing.request) und führt keine Sampling-Parameter. Kontextlänge (das längste Paar aus Anfrage und Dokument) und Preis vergleichen. Ein Chat-Modell ist kein Reranker, und ein Reranker kann nicht chatten.

Kosten

Rerank hat keine Ausgabe. Der Preis hängt von der Route ab: ein fester Preis je Anfrage (pricing.request), ein Preis je Eingabe-Token oder beides. Der Betrag steht in usage.cost (EUR), aufgeteilt in cost_details. Meldet ein Anbieter keine Token-Nutzung, ist die Tokenzahl eine Schätzung (usage.estimated: true), erlaubt nur bei Routen mit festem Anfragepreis; der Betrag ist exakt.

Bei festem Preis je Anfrage kostet eine Suche über 100 Kandidaten einen Anfragepreis, 1.000 Suchen kosten 1.000 Anfragepreise, egal wie viele Dokumente jede hat. Die aktuellen Preise stehen auf jeder Modellseite im Katalog.

Bei einer Route mit festem Preis alle Kandidaten in einer Anfrage senden statt in mehreren kleinen. Die Reservierung vor dem Aufruf besteht aus dem Anfragepreis plus den Kosten der geschätzten Eingabe-Tokens zum Prompt-Preis der Route.

Häufige Fehler

Status, TypUrsache und Abhilfe
400 invalid_parameterLeere query, keine oder mehr als 1.000 documents, ein Objekt ohne text, Text über 65.536 Bytes, top_n unter 1 oder über der Dokumentzahl, ein nicht boolesches return_documents. Abhilfe: Jeden Pfad in issues korrigieren.
400 context_length_exceededEin Paar aus Anfrage und Dokument ist länger als der Kontext des Modells. Abhilfe: Die Dokumente kürzen.
404 no_endpointDas Modell ist kein Reranker. Abhilfe: Ein Modell aus remedy_hint wählen.
502 provider_invalid_responseDer Anbieter lieferte eine ungültige Rangliste. Abhilfe: Wiederholen; ein anderer Anbieter wird automatisch versucht.
402 insufficient_credits, 429Guthaben oder Limits. Abhilfe: Wie beim Chat.

Bewährte Praxis

  • Erst abrufen, dann neu ordnen: 50 bis 200 Kandidaten aus der Vektorsuche, danach top_n von 3 bis 10 für den Prompt.
  • Dokumente auf einen Gedanken beschränken, einige hundert Tokens. Lange Seiten verwässern den Score und verbrauchen Kontext.
  • Ein relevance_score ordnet Dokumente für eine Anfrage. Er ist keine Wahrscheinlichkeit und unterscheidet sich zwischen Modellen; Werte nur innerhalb einer Antwort vergleichen und eine Schwelle an eigenen Daten testen.
  • Jedes Ergebnis trägt seinen Dokumenttext, die Antwort wächst also mit den Dokumenten. Bei langen Dokumenten top_n klein halten; return_documents: false verkürzt die Antwort nicht.
  • Duplikate vor dem Rerank entfernen; sie nehmen besseren Dokumenten die Plätze weg.
  • Die Dokumente in der neuen Reihenfolge und mit ihren IDs an das Chat-Modell geben, damit Antworten Quellen nennen können.

Für KI-Agenten

  • Endpunkt: [POST /rerank](https://tokenlane.de/docs/gateway/post-L3JlcmFuaw.md?lang=de).
  • Pflicht: model (ein Rerank-Modell aus GET /v1/models), query (String), documents (1 bis 1000 Strings oder Objekte mit text).
  • Optional: top_n (Ganzzahl von 1 bis zur Dokumentzahl, vom Gateway angewandt), return_documents (Boolean, ohne Wirkung), provider.
  • Antwort: results[] sortiert nach relevance_score (0 bis 1, absteigend) mit index (Position in documents) und document (immer: das eigene Objekt unverändert oder { "text": … } für einen String); usage.cost (EUR).
  • Datenfluss: Nur query und die Dokumenttexte erreichen den Anbieter; Objektfelder, top_n und return_documents bleiben im Gateway.
  • Grenzen: 1000 Dokumente; 65.536 UTF-8-Bytes je Text; insgesamt 4 MiB; jedes Paar aus Anfrage und Dokument im Kontext des Modells; kein Streaming.
  • Fehler: 400 invalid_parameter und context_length_exceeded, 404 no_endpoint, 502 provider_invalid_response, 402, 429.