Rerank — Noirdoc Docs

POST /v1/rerank

Familie: rerank
Maskierung: nein
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.

Feld	Pflicht	Inhalt
`model`	ja	Modell-ID der Familie `rerank`
`query`	ja	Suchanfrage als nicht leerer String
`documents`	ja	Liste von 1 bis 1.000 Strings
`top_n`	nein	ganze Zahl ab 1: Das Ergebnis enthält nur die besten `top_n` Dokumente. Ohne Angabe bewertet es alle.
`return_documents`	nein	`true`: 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:

Feld	Inhalt
`results`	Liste der bewerteten Dokumente in der Reihenfolge des Anbieters, üblicherweise nach Relevanz absteigend
`results[].index`	Position des Dokuments in Ihrer Liste `documents`, ab 0
`results[].relevance_score`	Relevanz des Dokuments für `query`. Die Skala legt das Modell fest; vergleichen Sie Werte nur innerhalb einer Antwort.
`results[].document`	Objekt `{"text": …}` mit dem Text des Dokuments. Mit `return_documents: true` ist es enthalten; ob es ohne diese Option erscheint, hängt vom Anbieter ab.
`usage`	Token-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

Bereich	Verhalten
Modell	Das Gateway löst die Modell-ID über den Katalog auf und sendet dem Anbieter dessen eigenen Modellnamen.
Anbieter	Der Header `X-Noirdoc-Provider` in der Antwort nennt den Anbieter. Siehe Anbieter & Routing.
Antwort	`results[].document` ist immer ein Objekt mit `text`, siehe Antwort.
Maskierung	Keine. Senden Sie `X-Noirdoc-Mask: on`, lehnt das Gateway die Anfrage mit 403 `masking_not_supported_for_endpoint` ab, statt sie unmaskiert weiterzuleiten. Mit der Maskierungsrichtlinie `enforced` lehnt es jede Anfrage auf diesem Endpunkt so ab. Mit `default_on` und `default_off` leitet es Anfragen ohne diesen Header unmaskiert weiter. Der Antwort-Header `X-Noirdoc-Masked` ist bei Antworten des Anbieters immer `false`.
Streaming	Keines. `"stream": true` beantwortet das Gateway mit 400 `streaming_not_supported_for_endpoint`.
Abrechnung	Je nach Modell nach Eingabe-Tokens (`per1MTokens`) oder je Anfrage (`perRequest`). 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.
Header	Das Gateway entfernt Ihren Schlüssel, bevor es die Anfrage weiterleitet.

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. Bei `/v1/detect` und `/v1/pseudonymize` antwortet das Gateway mit Statuscode 422, wenn der Body die Feldprüfung nicht besteht, etwa wenn `text` fehlt; `message` nennt das Feld.
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.
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	`masking_not_supported_for_endpoint`	Der Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist `enforced` oder die Anfrage sendet `X-Noirdoc-Mask: on`.
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.
502	`provider_unreachable`	Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
504	`provider_timeout`	Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. Die Antwort enthält `Retry-After` mit 10 Sekunden.