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
| Feld | Wert |
|---|---|
model | Pflicht. Ein Rerank-Modell. Ein Chat-Modell scheitert mit 404 no_endpoint. |
query | Pflicht. Text, höchstens 65.536 UTF-8-Bytes, nicht leer. |
documents | Pflicht. 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_n | Ganzzahl ab 1 bis zur Zahl der Dokumente. Standard: alle Dokumente. |
return_documents | Boolean. 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. |
provider | Routing 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 Anfrage | An den Anbieter gesendet | An den Aufrufer zurück |
|---|---|---|
query | Ja, unverändert. | Nein. |
| Text jedes Dokuments | Ja, 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_n | Nein. Das Gateway ordnet alle Dokumente und behält danach die besten top_n. | Nur so viele Ergebnisse. |
return_documents | Nein. | Ohne Wirkung. |
model | Die 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:
| Feld | Bedeutung |
|---|---|
results[].index | Nullbasierte Position in documents. |
results[].relevance_score | Eine Zahl von 0 bis 1. Absteigend sortiert; gleiche Werte behalten die eigene Reihenfolge. |
results[].document | Immer. Das gesendete Dokument: ein String als { "text": … }, ein Objekt mit allen seinen Feldern. |
usage | prompt_tokens, total_tokens, estimated, cost (EUR). |
id, model, provider | Generierungs-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, Typ | Ursache und Abhilfe |
|---|---|
400 invalid_parameter | Leere 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_exceeded | Ein Paar aus Anfrage und Dokument ist länger als der Kontext des Modells. Abhilfe: Die Dokumente kürzen. |
404 no_endpoint | Das Modell ist kein Reranker. Abhilfe: Ein Modell aus remedy_hint wählen. |
502 provider_invalid_response | Der Anbieter lieferte eine ungültige Rangliste. Abhilfe: Wiederholen; ein anderer Anbieter wird automatisch versucht. |
402 insufficient_credits, 429 | Guthaben oder Limits. Abhilfe: Wie beim Chat. |
Bewährte Praxis
- Erst abrufen, dann neu ordnen: 50 bis 200 Kandidaten aus der Vektorsuche, danach
top_nvon 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_scoreordnet 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_nklein halten;return_documents: falseverkü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 ausGET /v1/models),query(String),documents(1 bis 1000 Strings oder Objekte mittext). - Optional:
top_n(Ganzzahl von 1 bis zur Dokumentzahl, vom Gateway angewandt),return_documents(Boolean, ohne Wirkung),provider. - Antwort:
results[]sortiert nachrelevance_score(0 bis 1, absteigend) mitindex(Position indocuments) unddocument(immer: das eigene Objekt unverändert oder{ "text": … }für einen String);usage.cost(EUR). - Datenfluss: Nur
queryund die Dokumenttexte erreichen den Anbieter; Objektfelder,top_nundreturn_documentsbleiben 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_parameterundcontext_length_exceeded, 404no_endpoint, 502provider_invalid_response, 402, 429.