Text & Chat

Dokumente reranken

Rerankt Dokumente nach Relevanz für eine Abfrage

POST
/v1/rerank

Verwenden Sie GET /v1/models?recommended_for=rerank, um die aktuellen Rerank-Modelle aufzulisten. Verwenden Sie ein Modell, in dessen Details die Operation rerank aufgeführt ist.

Reranken Sie Dokumente mithilfe von Modellen zur semantischen Ähnlichkeit. Nützlich zur Verbesserung von Suchergebnissen und RAG-Anwendungen.

Request-Body

Dieser Endpunkt antwortet, sobald das Ranking abgeschlossen ist. Setzen Sie für große Dokumentenmengen das Timeout Ihres HTTP-Clients auf mindestens 120s.

modelstringerforderlich

ID des zu verwendenden Reranker-Modells (z. B. qwen3-vl-rerank).

querystringerforderlich

Die Abfrage, anhand derer die Dokumente bewertet werden sollen. Maximale Länge: 32,000 Zeichen.

documentsarrayerforderlich

Liste der zu rerankenden Dokumente (Strings). Limits: bis zu 1,000 Dokumente, jedes Dokument bis zu 100,000 Zeichen und maximal 2,000,000 Dokumentzeichen insgesamt.

top_ninteger

Anzahl der zurückzugebenden Top-Ergebnisse, von 1 bis documents.length. Wenn weggelassen, bestimmt das ausgewählte Modell die Anzahl der Ergebnisse.

return_documentsbooleanStandard: false

Gibt an, ob der ursprüngliche Dokumenttext in jedem Ergebnis enthalten sein soll. Senden Sie dies nur, wenn in den Modelldetails return_documents aufgeführt ist.

Antwort

resultsarray

Rangliste der Dokumente mit Scores.

Jedes Ergebnis enthält:

  • index (integer): Ursprünglicher Dokumentindex
  • relevance_score (number): Relevanz-Score. Der Wertebereich hängt vom ausgewählten Modell ab.
  • document (string): Ursprünglicher Text (falls return_documents=true)
modelstring

Das für das Reranking verwendete Modell, sofern verfügbar.

usageobject

Gemeldete Nutzung für die Anfrage, sofern verfügbar: total_tokens oder search_units für Modelle, die pro Suche abgerechnet werden.

Anfrage

curl -X POST "https://api.tokenlab.sh/v1/rerank" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-rerank",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning is a subset of AI",
      "The weather is nice today",
      "Deep learning uses neural networks"
    ],
    "top_n": 2,
    "return_documents": true
  }'

Antwort

Response
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": "Machine learning is a subset of AI"
    },
    {
      "index": 2,
      "relevance_score": 0.82,
      "document": "Deep learning uses neural networks"
    }
  ],
  "model": "qwen3-vl-rerank",
  "usage": {
    "total_tokens": 45
  }
}

Fehler

StatusCodeUrsache
400invalid_requestEin Feld fehlt, ist leer oder überschreitet ein oben genanntes Limit. param gibt den Namen an
400unsupported_endpointDas Modell ist für diesen Endpunkt nicht freigegeben

Behandeln Sie andere Statuscodes wie unter API-Fehler behandeln beschrieben.

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Header

X-TokenLab-Delivery-Policy?string

Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.

Zulässige Werte

  • "auto"
  • "verified"
  • "official"

Anfragekörper

application/json

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

application/json