Reranking ist die zweite Sortierstufe in der Retrieval-Kette: Zuerst werden per Vektorsuche oder Stichwortsuche Kandidaten abgerufen, dann bewertet ein Rerank-Modell jeden Kandidaten einzeln und die relevantesten Treffer gelangen in den Kontext des großen Modells. Das löst das Problem „viele Treffer, aber die vorderen sind ungenau“ — nicht aber das Problem „es wurde gar nichts gefunden“.
Dieser Beitrag behandelt Endpunkt und Authentifizierung, Request und Response, top_n und Kandidatenmenge, die Integration in die Vektorsuche, Latenz und Degradation, häufige Fehler und Evaluationsmetriken. Modelle und Preise richten sich nach den Modellpreisen.
Hinweis: Cohere, Jina AI, BAAI und Alibaba Cloud sind Marken ihrer jeweiligen Inhaber und werden nur zur technischen Erläuterung genannt. Der ZSQH AI Gateway ist mit diesen Anbietern nicht verbunden; Schnittstellen, Modelle und Abrechnung richten sich nach den Angaben im Portal.
1. Wo das Reranking in der Retrieval-Kette steht
Typisches RAG-Retrieval besteht aus drei Schritten: Abruf, Neubewertung, Generierung. Der Abruf zielt auf Geschwindigkeit und Abdeckung, die Neubewertung auf Präzision, und die Generierung nutzt nur den gefilterten Kontext.
| Phase | Typische Methode | Eingabe | Ausgabe | Wichtige Metrik |
|---|---|---|---|---|
| Abruf | Vektorsuche, BM25, hybride Suche | Nutzer-Query | 30–100 Kandidaten | Recall@k |
| Neubewertung | Rerank-Modell | Query + Kandidaten | 5–10 Treffer | nDCG@10 |
| Generierung | Großes Sprachmodell | Neu sortierter Kontext | Antwort | Korrektheit, Treue |
Rerank-Modelle sind meist Cross-Encoder: Sie lesen Query und Dokument gemeinsam und geben einen Relevanzwert aus. Das ist genauer als Vektorähnlichkeit, aber langsamer. Sie gehören nach den Abruf und ersetzen ihn nicht.
2. Endpunkt, Authentifizierung und Parameter
Der Rerank-Endpunkt des ZSQH AI Gateway lautet:
POST https://ai.zhongshangqihang.com/v1/rerank
Die Authentifizierung erfolgt mit Authorization: Bearer <key>, der Body ist JSON. Das Gateway unterstützt auch den Pfad /rerank. Erstellung und sichere Konfiguration des Keys sind in einer anderen Anleitung beschrieben.
| Parameter | Pflicht | Erläuterung |
|---|---|---|
model |
Ja | Name des Rerank-Modells laut Modellliste im Portal |
query |
Ja | Nutzer-Query, darf nicht leer sein |
documents |
Ja | Array der Kandidatendokumente, meist Strings; Objektstruktur je Upstream unterschiedlich |
top_n |
Nein | Anzahl der Treffer; explizit setzen und nicht auf den Standardwert verlassen |
return_documents |
Nein | Ob der Dokumentinhalt in der Antwort zurückgegeben wird |
max_chunk_per_doc |
Nein | Obergrenze für Chunks pro Langdokument, abhängig vom Upstream |
overlap_tokens |
Nein | Überlappende Token beim Chunking, laut Upstream-Dokumentation |
Die meisten Implementierungen akzeptieren ein String-Array, manche Plattformen auch Objekte mit text-Feld. Vor der Integration mit einer minimalen Anfrage das Format bestätigen und nicht direkt einen ganzen Batch migrieren.
3. Request und Response: Python und curl
Python-Beispiel mit Abruf und anschließender Neubewertung:
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = "https://ai.zhongshangqihang.com/v1"
documents = [
"Die Testphase dauert 14 Tage; vor Ablauf kann eine Verlängerung beantragt werden.",
"Überweisung vom Firmenkonto und Treuhandzahlung über die Plattform sind möglich.",
"Die Rechnung wird innerhalb von 3 Werktagen nach Zahlung ausgestellt.",
]
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "Ihr Rerank-Modellname",
"query": "Wie lange dauert die Testphase?",
"documents": documents,
"top_n": 2,
"return_documents": False,
},
timeout=20,
)
resp.raise_for_status()
for item in resp.json()["results"]:
print(item["index"], item["relevance_score"], documents[item["index"]])
Dieselbe Anfrage mit curl:
curl "https://ai.zhongshangqihang.com/v1/rerank" \
-H "Authorization: Bearer $RERANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Ihr Rerank-Modellname",
"query": "Wie lange dauert die Testphase?",
"documents": ["Die Testphase dauert 14 Tage.", "Überweisung vom Firmenkonto ist möglich."],
"top_n": 2
}'
Die results in der Antwort sind bereits nach Relevanz absteigend sortiert. Jeder Eintrag enthält:
index: Position des Dokuments im ursprünglichendocuments-Array, nicht der Rang. Damit muss der Originaltext nachgeschlagen werden.relevance_score: Relevanzwert, meist auf 0 bis 1 normalisiert, aber keine Wahrscheinlichkeit und kein linearer Abstand.document: Möglicherweise nur beireturn_documents: trueenthalten; Struktur je Upstream unterschiedlich.usage: Token-Verbrauch für Abrechnungsabgleich und Kostenanalyse.
relevance_score sollte nicht direkt als Schwellenwert wiederverwendet werden. Bei einem anderen Modell, einer anderen Sprache oder anderen Dokumenttypen ändert sich die Verteilung; der Schwellenwert muss neu kalibriert werden.
4. top_n und Kandidatenmenge
top_n ist die Zahl der zurückgegebenen Treffer; die Kandidatenmenge ist die Zahl der an das Modell übergebenen Dokumente. Beides ist nicht dasselbe. Ein häufiger Fehler ist ein großes top_n bei nur wenigen abgerufenen Dokumenten — dann hat das Reranking keinen Spielraum.
| Kandidatenmenge | Geeignetes Szenario | Relative Latenz | Hinweis |
|---|---|---|---|
| 20–30 | Kleine Wissensbasis, latenzkritische Fragen | Niedrig | Geringe Abrufobergrenze, Antworten können fehlen |
| 50 | Üblicher Startpunkt für RAG | Mittel | Erst evaluieren, dann erhöhen oder senken |
| 100 | Viele Dokumente, vielfältige Formulierungen | Höher | Länge einzelner Dokumente und Truncation beachten |
| Über 200 | Hochwertige Queries, Offline-Evaluation | Hoch | Kosten und Latenz separat bewerten |
Empfehlung: Mit 30–50 Kandidaten beginnen und top_n auf 5–10 setzen. Eine zu kleine Kandidatenmenge begrenzt die Qualität, eine zu große erhöht Latenz und Kosten und kann Rauschen in den Kontext bringen. Upstreams können Dokumentanzahl und Einzellänge begrenzen; zu lange Dokumente werden abgeschnitten, womöglich genau an der entscheidenden Stelle.
Außerdem liefern manche Upstreams bei fehlendem top_n nur einen Treffer. Im Produktivcode immer explizit top_n übergeben und sich nicht auf Standardverhalten verlassen.
5. Integration in die Vektorsuche
Reranking ist kein isolierter Schritt; die Reihenfolge beeinflusst Qualität und Kosten. Empfohlener Ablauf:
- Die Nutzer-Query bei Bedarf umschreiben und Pronomen sowie Auslassungen ergänzen.
- Die Query mit einem Embedding-Modell in einen Vektor umwandeln.
- Per Vektorsuche die ersten 30–50 Treffer abrufen; parallel kann eine Stichwort- oder BM25-Suche laufen.
- Beide Ergebnislisten zusammenführen und nach Dokument-ID deduplizieren.
- Vor dem Reranking Berechtigungen und Metadaten filtern, damit keine unberechtigten Dokumente an das Modell gehen.
- Die Rerank API aufrufen und
top_nauf 5–10 setzen. - Einen Score-Schwellenwert oder eine Obergrenze setzen und den Kontext an das Generierungsmodell übergeben.
Einige leicht übersehene Punkte:
- Erst filtern, dann neu bewerten: Berechtigungen, Mandanten, Sprache und Version sollten beim Abruf oder vor dem Reranking gefiltert werden, nicht erst nach der Generierung.
- Stabile IDs behalten: Das Reranking liefert Indizes; die Anwendung muss sie auf Dokument-ID, Titel und URL abbilden können.
- Chunk-Reranking: In RAG werden meist Chunks neu bewertet, nicht ganze Dokumente. Zu lange Chunks verwässern die Relevanz, zu kurze verlieren Kontext.
- Hybrider Abruf: Eigennamen, Modellnummern und Codes finden Stichwortverfahren zuverlässiger, semantische Fragen die Vektorsuche; die Kombination vor dem Reranking ist meist besser als ein einzelner Weg.
6. Latenz, Timeout und Degradation
Die Rerank-Latenz wächst ungefähr mit „Dokumentanzahl × Dokumentlänge“. 100 kurze Dokumente sind meist schnell, mehrere hundert lange deutlich langsamer. Vor dem Start mindestens drei Messungen durchführen: P50 und P95 bei 30, 50 und 100 Kandidaten.
Empfehlungen für die Technik:
- Für Rerank-Anfragen ein eigenes Timeout setzen, üblicher Start 10–30 Sekunden, danach anhand der Messung straffen.
- Nur bei 429 und 5xx begrenzt mit Backoff wiederholen; 401, 403 und 422 nicht.
- Bei Timeout oder Fehler auf die Reihenfolge der Vektorsuche zurückfallen, nicht die gesamte Frage-Antwort-Kette scheitern lassen.
- Häufige, wenig veränderliche Queries cachen; der Cache-Key sollte mindestens Query, Dokument-IDs und Modellname enthalten.
- Vektorsuche und Stichwortsuche parallel ausführen und erst danach zusammenführen und neu bewerten, um serielle Wartezeit zu sparen.
- Die Rerank-Schnittstelle liefert das vollständige Ergebnis auf einmal und unterstützt kein Streaming; das Frontend nicht als Streaming-Schnittstelle entwerfen.
Ist die Latenz weiterhin hoch, zuerst Kandidatenmenge und Dokumentlänge reduzieren und dann über ein kleineres Modell nachdenken. Ein größeres Modell ist nicht automatisch wirtschaftlich, besonders wenn die Abrufqualität ohnehin niedrig ist.
7. Häufige Fehler und Diagnose
| Statuscode oder Symptom | Häufige Ursache | Behandlung |
|---|---|---|
| 400 / 422 | query leer, documents leer, JSON-Struktur fehlerhaft |
Pflichtfelder und Array-Typ prüfen |
| 401 | Key ungültig, abgelaufen oder Header fehlt | Authorization und Key-Status prüfen |
| 403 | Key ohne Modellberechtigung oder Konto eingeschränkt | Modellumfang und Kontostatus prüfen |
| 404 | Modellname oder Endpunktpfad falsch | /v1/rerank und Modellliste abgleichen |
| 429 | Parallelität oder Kontingent löst Drosselung aus | Backoff, Kontingent und Rate-Limit prüfen |
| 500 / 502 / 504 | Upstream-Ausnahme oder Timeout | Begrenzt wiederholen, danach Degradationsweg |
Das Gateway prüft query und documents und gibt bei leerem Inhalt direkt einen Parameterfehler zurück. Zuerst die message im Antwortkörper lesen und dann mit dem Request-Log abgleichen; einen 400 nicht als Netzwerkproblem wiederholt senden.
8. Evaluation: nicht nur „fühlt sich genauer an“
Vor dem Produktivstart einen kleinen annotierten Datensatz vorbereiten: 100–300 echte Queries, jeweils mit 1–3 relevanten Dokumenten. Ohne Annotation mindestens 50 Fälle manuell prüfen und beide Sortierungen festhalten.
| Metrik | Was sie zeigt | Verwendung |
|---|---|---|
| Recall@50 | Ist die richtige Antwort in der Kandidatenmenge? | Abrufobergrenze beurteilen; bei niedrigem Wert zuerst den Abruf verbessern |
| nDCG@10 | Qualität der vorderen Sortierung | Vergleich mit und ohne Reranking |
| MRR | Position des ersten relevanten Treffers | Geeignet für Frage-Antwort-Queries |
| Antwortkorrektheit | Ist das Generierungsergebnis korrekt? | End-to-End-Prüfung |
| P95-Latenz | Wie langsam sind die langsamsten Anfragen? | Kandidatenmenge und Timeout festlegen |
| Kosten pro Query | Retrieval-Aufwand je Frage | Mit der Preisseite schätzen |
Bei der Evaluation Variablen konstant halten: dieselben Queries, dasselbe Abrufergebnis, dasselbe top_n; nur Reranking an oder aus beziehungsweise das Modell wechseln. Danach im Livebetrieb ein kleines A/B-Testing durchführen und Korrektheit, Rate ohne Antwort sowie Latenz beobachten. Wird das Ergebnis durch Reranking schlechter, zuerst prüfen, ob der Abruf Treffer verfehlt, Dokumente abgeschnitten wurden, das Modell zur Sprache passt und Schwellenwerte aus einem anderen Szenario übernommen wurden.
9. Häufige Fragen
Kann Reranking die Vektorsuche ersetzen?
Nein. Reranking sortiert nur vorhandene Kandidaten neu und kann nicht gefundene Dokumente nicht zurückholen. Der Abruf liefert die Abdeckung, das Reranking die Präzision an der Spitze.
Wie groß sollte top_n sein?
Für die Kontextübergabe an das große Modell sind 5–10 ein üblicher Start; folgen danach weitere fachliche Filter, sind 20–50 möglich. Entscheidend ist die Evaluation.
Ist eine größere Kandidatenmenge immer besser?
Nein. Eine größere Menge erhöht die mögliche Abdeckung, aber auch Latenz, Kosten und Rauschen. Mit 30–50 beginnen und anhand von Recall@50 und nDCG@10 entscheiden, ob eine Erweiterung sinnvoll ist.
Warum wird das Ergebnis mit Reranking schlechter?
Vier häufige Ursachen: Die Kandidatenmenge enthält das richtige Dokument nicht, Chunks sind zu lang oder zu kurz, Modell und Sprache passen nicht, oder Schwellenwerte wurden aus einem anderen Szenario übernommen. Punkt für Punkt prüfen statt nur das Modell zu wechseln.
Unterstützt die Rerank-Schnittstelle Streaming?
Nein. Das Reranking muss die gesamte Kandidatenmenge sehen, bevor es die vollständige Sortierung ausgeben kann, und liefert deshalb in der Regel alles auf einmal. Das Frontend sollte eine normale JSON-Anfrage mit angemessenem Timeout verwenden.
Weiterlesen:
