# 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](https://tokenlane.de/docs/guides/embeddings.md?lang=de).

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

### curl

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

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

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

```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`:

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

Das zugehörige Ergebnis:

```json
{ "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](https://tokenlane.de/models) 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](https://tokenlane.de/models).

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_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.
