Texto

Reordenar documentos

Reordena documentos según su relevancia respecto a una consulta

POST
/v1/rerank

Use GET /v1/models?recommended_for=rerank para listar los modelos de rerank actuales. Use un modelo cuyos detalles incluyan la operación rerank.

Reordene documentos utilizando modelos de similitud semántica. Útil para mejorar los resultados de búsqueda y las aplicaciones RAG.

Cuerpo de la solicitud

Este endpoint responde una vez finalizada la clasificación. Para conjuntos grandes de documentos, establezca el timeout de su cliente HTTP en al menos 120s.

modelstringobligatorio

ID del modelo de rerank que se va a utilizar (por ejemplo, qwen3-vl-rerank).

querystringobligatorio

La consulta con respecto a la cual se clasificarán los documentos. Longitud máxima: 32,000 caracteres.

documentsarrayobligatorio

Lista de documentos (cadenas de texto) a reordenar. Límites: hasta 1,000 documentos, cada documento de hasta 100,000 caracteres y un máximo de 2,000,000 de caracteres totales entre todos los documentos.

top_ninteger

Número de mejores resultados a devolver, desde 1 hasta documents.length. Si se omite, el modelo seleccionado determina el número de resultados.

return_documentsbooleanpredeterminado: false

Indica si se debe incluir el texto original del documento en cada resultado. Envíelo únicamente cuando los detalles del modelo indiquen return_documents.

Respuesta

resultsarray

Lista clasificada de documentos con puntuaciones.

Cada resultado contiene:

  • index (integer): Índice original del documento
  • relevance_score (number): Puntuación de relevancia. Su rango depende del modelo seleccionado.
  • document (string): Texto original (si return_documents=true)
modelstring

El modelo utilizado para el reranking. Cuando esté disponible.

usageobject

Uso reportado para la solicitud, cuando esté disponible: total_tokens o search_units para modelos facturados por búsqueda.

Solicitud

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
  }'

Respuesta

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

Errores

EstadoCódigoCausa
400invalid_requestFalta un campo, está vacío o supera un límite indicado anteriormente. param lo especifica
400unsupported_endpointEl modelo no está publicado para este endpoint

Gestione otros estados según se indica en Manejar errores de la API.

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

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

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json