Entwickeln / Referenz

Rerank

Ordnet Dokumente nach ihrer Relevanz für eine Suchanfrage und prüft Anfrage, Anweisung und Dokumente vor der Weiterleitung mit Noirdoc Shield, wenn Shield aktiv ist.

POST /v1/rerank
Familie
rerank
Shield
ja
Streaming
nein
Format
JSON
Abrechnung
Tokens (Eingabe) oder je Anfrage

Ein Reranker bewertet, wie gut jedes Dokument zu einer Suchanfrage passt. In einer RAG-Pipeline setzen Sie ihn nach der Vektorsuche ein: Die Suche liefert Kandidaten, der Reranker ordnet sie neu, und nur die besten gehen an das Sprachmodell.

Anfrage

Der Body folgt dem verbreiteten Rerank-Format (POST /v1/rerank). model ist Pflicht und muss ein Modell der Familie rerank aus GET /v1/models sein. Ein Chat- oder Embedding-Modell auf diesem Endpunkt beantwortet das Gateway mit 400 wrong_endpoint_for_model, ebenso ein Rerank-Modell auf einem anderen Endpunkt.

FeldPflichtInhalt
modeljaModell-ID der Familie rerank
queryjaSuchanfrage als nicht leerer String
documentsjaListe von 1 bis 1.000 Strings
instructionneinoptionale Aufgabenanweisung als String (wird bei aktivem Shield mitgeprüft und an den Anbieter weitergeleitet)
top_nneinganze Zahl ab 1: Das Ergebnis enthält nur die besten top_n Dokumente. Ohne Angabe bewertet es alle.
return_documentsneintrue: Jedes Ergebnis enthält zusätzlich den Text des Dokuments. Das Gateway leitet das Feld unverändert weiter.

Der Endpunkt nimmt nur Text an. Bilder oder Inhaltsteile (content-Arrays) in query oder documents lehnt das Gateway ab, auch wenn das Modell beim Anbieter Bilder verarbeiten könnte. Verstöße gegen die Regeln der Tabelle beantwortet es mit 400 invalid_rerank_request, bevor es die Anfrage weiterleitet.

Shell
curl https://api.noirdoc.de/v1/rerank \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-VL-Reranker-8B",
    "query": "Wie lange ist die Kündigungsfrist?",
    "documents": [
      "Der Vertrag endet zum Quartalsende.",
      "Die Kündigungsfrist beträgt drei Monate.",
      "Die Miete ist zum Monatsersten fällig."
    ],
    "top_n": 2,
    "return_documents": true
  }'
Python
import os
import httpx

key = os.environ["NOIRDOC_API_KEY"]

response = httpx.post(
    "https://api.noirdoc.de/v1/rerank",
    headers={"Authorization": f"Bearer {key}"},
    json={
        "model": "Qwen/Qwen3-VL-Reranker-8B",
        "query": "Wie lange ist die Kündigungsfrist?",
        "documents": [
            "Der Vertrag endet zum Quartalsende.",
            "Die Kündigungsfrist beträgt drei Monate.",
            "Die Miete ist zum Monatsersten fällig.",
        ],
        "top_n": 2,
        "return_documents": True,
    },
)
response.raise_for_status()
for result in response.json()["results"]:
    print(result["index"], result["relevance_score"])

Antwort

Das Gateway gibt die Antwort des Anbieters in einer einheitlichen Form zurück, gleich welcher Anbieter sie geliefert hat:

FeldInhalt
resultsListe der bewerteten Dokumente in der Reihenfolge des Anbieters, üblicherweise nach Relevanz absteigend
results[].indexPosition des Dokuments in Ihrer Liste documents, ab 0
results[].relevance_scoreRelevanz des Dokuments für query. Die Skala legt das Modell fest; vergleichen Sie Werte nur innerhalb einer Antwort.
results[].documentObjekt {"text": …} mit dem Text des Dokuments. Mit return_documents: true ist es enthalten; ob es ohne diese Option erscheint, hängt vom Anbieter ab.
usageToken-Nutzung, wenn der Anbieter sie meldet. Fehlt sie, schätzt das Gateway die Eingabe-Tokens für die Abrechnung selbst.

Liefert ein Anbieter das Dokument als einfachen String, setzt das Gateway ihn in ein Objekt mit dem Feld text um. Objekte gibt es unverändert weiter. Fehler des Anbieters meldet es im einheitlichen Fehlerobjekt, siehe Fehlercodes.

JSON
{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.94,
      "document": {
        "text": "Die Kündigungsfrist beträgt drei Monate."
      }
    },
    {
      "index": 0,
      "relevance_score": 0.31,
      "document": {
        "text": "Der Vertrag endet zum Quartalsende."
      }
    }
  ],
  "usage": { "total_tokens": 48 }
}

Prompt-Tags für Qwen3-Reranker

Einige Reranker erwarten ihre Eingaben in einem festen Prompt-Format. Qwen3-Reranker-Modelle liefern die besten Ergebnisse, wenn query eine Aufgabenbeschreibung und die Suchanfrage mit den Tags <Instruct>: und <Query>: enthält und jedes Dokument mit <Document>: beginnt.

Das Gateway setzt diese Tags nicht selbst. Es leitet query und documents so weiter, wie Sie sie senden. Ob ein Modell Tags braucht, steht in der Dokumentation des Modells. Modelle, die keine Tags erwarten, rufen Sie mit dem reinen Text auf.

Python
instruct = (
    "Finde Vertragsklauseln, die die Frage beantworten."
)
question = "Wie lange ist die Kündigungsfrist?"
docs = [
    "Der Vertrag endet zum Quartalsende.",
    "Die Kündigungsfrist beträgt drei Monate.",
]

payload = {
    "model": "<qwen3-reranker-modell>",
    "query": f"<Instruct>: {instruct}\n<Query>: {question}",
    "documents": [f"<Document>: {d}" for d in docs],
}

Was Noirdoc ändert

BereichVerhalten
ModellDas Gateway löst die Modell-ID über den Katalog auf und sendet dem Anbieter dessen eigenen Modellnamen.
AnbieterDer Header X-Noirdoc-Provider in der Antwort nennt den Anbieter. Siehe Anbieter & Routing.
Antwortresults[].document ist immer ein Objekt mit text, siehe Antwort. Hat Shield Dokumente geschwärzt, enthält text bei return_documents: true die geschwärzte Fassung.
Noirdoc ShieldIst Shield aktiv (default_on, enforced, shield_mode: on auf Schlüssel oder Request-Tag oder X-Noirdoc-Shield: on), prüft Shield query, instruction und documents[] vor der Weiterleitung. Die Antwort trägt X-Noirdoc-Shield: redacted=<n> und X-Noirdoc-Masked: true; schlägt eine block-Regel an, lehnt das Gateway mit 403 shield_violation ab (siehe Geprüfte Felder).
StreamingKeines. "stream": true beantwortet das Gateway mit 400 streaming_not_supported_for_endpoint.
AbrechnungJe nach Modell nach Eingabe-Tokens (per1MTokens) oder je Anfrage (perRequest), zuzüglich Noirdoc Shield bei aktiver Prüfung (Abrechnung). Bei Tokens rechnet das Gateway die Nutzung aus usage ab; meldet der Anbieter keine, schätzt es die Eingabe-Tokens aus query und documents. Bei perRequest kostet jede erfolgreiche Anfrage den Preis aus price_input, unabhängig von der Zahl der Dokumente. Die Preise nennt Modelle & Preise.
HeaderDas Gateway entfernt Ihren Schlüssel, X-Noirdoc-Shield und X-Noirdoc-Mask, bevor es die Anfrage weiterleitet.

Nur Bestandsorganisationen, die während der Übergangsfrist bis zum 30.11.2026 noch die klassische Maskierung nutzen, erhalten auf /v1/rerank bei enforced oder X-Noirdoc-Mask: on den Fehler 403 masking_not_supported_for_endpoint — solange sie nicht per X-Noirdoc-Shield: on oder durch Umstellung unter Models → Shield Noirdoc Shield einschalten.

Unterrouten

Keine. Andere Pfade unter /v1/rerank/ beantwortet das Gateway mit 404 unsupported_endpoint. Der Endpunkt nimmt nur POST an; andere Methoden beantwortet das Gateway mit 405 method_not_allowed.

Fehler auf diesem Endpunkt

Status Code Bedeutung
400 model_required Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld).
400 wrong_endpoint_for_model Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt.
400 streaming_not_supported_for_endpoint Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht.
400 invalid_request_body Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert.
400 invalid_rerank_request query ist kein nicht leerer String, documents ist keine Liste von 1 bis 1.000 Strings oder top_n ist keine ganze Zahl ab 1; message nennt das Feld.
402 insufficient_credit Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage (einschließlich Noirdoc Shield, auch auf BYOK-Routen mit aktivem Shield).
402 key_budget_exhausted Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus.
403 model_not_allowed_for_key Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels.
403 provider_not_allowed_for_tenant Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet.
403 provider_not_allowed_for_key Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus.
403 starter_model_not_allowed Die Organisation nutzt noch ausschließlich das Startguthaben, und das Modell bzw. sein verwalteter Anbieter ist im Startguthaben nicht freigegeben.
403 shield_violation Noirdoc Shield hat die Anfrage vor der Weiterleitung an den Anbieter blockiert, weil ein aktiver Schutzfilter mit der Aktion block angeschlagen hat; message nennt die ausgelöste Regel (secrets, pii, ner, injection oder custom).
403 masking_not_supported_for_endpoint Der Endpunkt unterstützt weder Noirdoc Shield noch die klassische Maskierung, aber die Richtlinie steht auf enforced oder die Anfrage sendet X-Noirdoc-Mask: on (auf /v1/images/generations auch X-Noirdoc-Shield: on). Während der Übergangsfrist der klassischen Maskierung bis zum 30.11.2026 betrifft das auf Bestandsorganisationen ohne Shield auch /v1/embeddings und /v1/rerank.
403 model_not_billable Für das Modell ist kein vollständiger Preis hinterlegt, deshalb lässt es sich mit Guthaben nicht nutzen.
404 model_not_available Die Modell-ID ist für die Organisation nicht verfügbar.
405 method_not_allowed Der Endpunkt nimmt nur POST an.
413 shield_input_too_large Der zu prüfende Text der Anfrage überschreitet das Limit des Shield-Dienstes von 4 MiB kodiertem Text in einem Aufruf.
422 shield_config_invalid Die gespeicherte Shield-Konfiguration der Organisation ist ungültig (zum Beispiel enforced ohne aktiven Schutzfilter oder ein nicht kompilierbares Muster); das Gateway hat die Anfrage nicht weitergeleitet.
502 provider_unreachable Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
503 shield_unavailable Der Noirdoc-Shield-Prüfdienst ist vorübergehend nicht erreichbar; das Gateway leitet eine zu prüfende Anfrage niemals ungeprüft weiter (Fail-closed). Die Antwort enthält Retry-After mit 5 Sekunden.
504 provider_timeout Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält Retry-After mit 10 Sekunden.