Rerank es la segunda etapa de ordenamiento en una cadena de recuperación: primero se recupera un conjunto de candidatos con vectores o palabras clave, luego un modelo de reordenamiento puntúa cada documento y los más relevantes se colocan en el contexto del modelo grande. Resuelve el problema de «recuperar bastante, pero con el orden superior poco preciso»; no resuelve el caso de «no se recuperó nada».

Este artículo recorre el endpoint y la autenticación, la solicitud y la respuesta, top_n y el tamaño del conjunto de candidatos, la integración con búsqueda vectorial, la latencia y la degradación, los errores comunes y las métricas de evaluación. Los modelos y precios se rigen por los precios de modelos del sitio.

Nota: Cohere, Jina AI, BAAI y Alibaba Cloud son nombres que pertenecen a sus respectivos titulares; aquí solo se usan para explicaciones técnicas. ZSQH AI Gateway no tiene relación de afiliación con esos proveedores. Las interfaces, los modelos y la facturación se rigen por la información del sitio.

1. Dónde encaja el reordenamiento en la cadena de recuperación

Una recuperación RAG típica tiene tres etapas: recuperación, reordenamiento y generación. La recuperación busca velocidad y cobertura; el reordenamiento busca precisión; la generación solo usa el contexto ya filtrado.

Etapa Método típico Entrada Salida Métrica principal
Recuperación Búsqueda vectorial, BM25, búsqueda híbrida Consulta del usuario 30–100 candidatos Recall@k
Reordenamiento Modelo de rerank Consulta + conjunto de candidatos 5–10 documentos nDCG@10
Generación Modelo de lenguaje grande Contexto reordenado Respuesta Exactitud, fidelidad

Los modelos de reordenamiento suelen ser codificadores cruzados: leen la consulta y cada documento juntos y emiten una puntuación de relevancia. Son más precisos que la similitud vectorial, pero también más lentos. Su lugar es después de la recuperación, no en sustitución de ella.

2. Interfaz, autenticación y parámetros de la solicitud

El endpoint de reordenamiento de ZSQH AI Gateway es:

POST https://ai.zhongshangqihang.com/v1/rerank

La autenticación usa Authorization: Bearer <key> y el cuerpo es JSON. El gateway también acepta la ruta /rerank. La creación y la configuración segura de la clave se explican en otro tutorial.

Parámetro Obligatorio Descripción
model Sí Nombre del modelo de reordenamiento, según la lista de modelos del sitio
query Sí Consulta del usuario; no puede estar vacía
documents Sí Arreglo de documentos candidatos, normalmente cadenas; la estructura de objetos varía según el proveedor
top_n No Número de resultados; conviene fijarlo de forma explícita en lugar de depender del valor predeterminado
return_documents No Indica si se devuelve el contenido del documento en los resultados
max_chunk_per_doc No Límite de fragmentos para documentos largos; la compatibilidad depende del proveedor
overlap_tokens No Tokens de solapamiento entre fragmentos; confirma la documentación del proveedor

La mayoría de las implementaciones aceptan un arreglo de cadenas; algunas también aceptan objetos con un campo text. Antes de integrar, confirma el formato con una solicitud mínima; no migres un lote completo a ciegas.

3. Solicitud y respuesta: Python y curl

Ejemplo en Python, primero recuperar y luego reordenar:

import os
import requests

api_key = os.environ["RERANK_API_KEY"]
base_url = "https://ai.zhongshangqihang.com/v1"

documents = [
    "El período de prueba es de 14 días y puede solicitarse una extensión antes del vencimiento.",
    "Se aceptan transferencias empresariales y pagos con custodia de la plataforma.",
    "La factura se emite dentro de los 3 días hábiles posteriores al pago.",
]

resp = requests.post(
    f"{base_url}/rerank",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "nombre-de-tu-modelo-de-rerank",
        "query": "¿Cuánto dura el período de prueba?",
        "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"]])

La misma solicitud con curl:

curl "https://ai.zhongshangqihang.com/v1/rerank" \
  -H "Authorization: Bearer $RERANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nombre-de-tu-modelo-de-rerank",
    "query": "¿Cuánto dura el período de prueba?",
    "documents": ["El período de prueba es de 14 días.", "Se acepta transferencia empresarial."],
    "top_n": 2
  }'

El campo results de la respuesta ya viene ordenado por relevancia descendente y cada elemento contiene:

  • index: la posición del documento en el arreglo original documents, no su rango. Úsalo siempre para recuperar el texto original.
  • relevance_score: puntuación de relevancia, normalmente normalizada entre 0 y 1, pero no es una probabilidad ni implica diferencias lineales.
  • document: puede aparecer solo cuando return_documents es true; la estructura varía según el proveedor.
  • usage: consumo de tokens, útil para conciliar la factura y analizar costos.

No reutilices relevance_score directamente como umbral. Al cambiar de modelo, de idioma o de tipo de documento, la distribución de puntuaciones cambia y el umbral debe recalibrarse.

4. top_n y tamaño del conjunto de candidatos

top_n es el número de resultados devueltos; el tamaño del conjunto de candidatos es la cantidad de documentos que se envían al modelo. No son lo mismo. Un error común es fijar un top_n muy grande y recuperar solo una docena de documentos, con lo que el reordenamiento no tiene margen para actuar.

Tamaño del conjunto Caso de uso Latencia relativa Consideración
20–30 Bases pequeñas, preguntas y respuestas de baja latencia Baja El techo de recuperación es bajo y se pueden perder respuestas
50 Punto de partida para la mayoría de los RAG Media Evalúa antes de aumentar o reducir
100 Muchos documentos y consultas variadas Alta Cuida la longitud por documento y los truncamientos
Más de 200 Consultas de alto valor, evaluación fuera de línea Alta Hay que evaluar costo y latencia por separado

Recomendación práctica: empieza con 30–50 candidatos y un top_n de 5–10. Un conjunto demasiado pequeño limita el techo; uno demasiado grande eleva la latencia y el costo y puede introducir ruido en el contexto. El proveedor puede imponer límites al número de documentos y a la longitud de cada uno; los documentos demasiado largos se truncan, y el corte puede eliminar justamente la frase clave.

Además, algunos proveedores devuelven un solo resultado cuando se omite top_n. En el código de producción, pasa siempre top_n de forma explícita y no dependas del comportamiento predeterminado.

5. Integración con búsqueda vectorial

El reordenamiento no es un paso aislado: el orden de integración afecta la calidad y el costo. Flujo recomendado:

  1. Reescribe la consulta del usuario cuando sea necesario para resolver referencias y elipsis.
  2. Convierte la consulta en un vector con un modelo de embeddings.
  3. Recupera los primeros 30–50 candidatos con búsqueda vectorial; en paralelo, puedes ejecutar una recuperación por palabras clave o BM25.
  4. Combina los resultados de ambas rutas y elimina duplicados por ID de documento.
  5. Aplica filtros de permisos y metadatos antes de enviar al reordenamiento, para no pasar documentos sin permiso al modelo.
  6. Llama a la API de Rerank y toma un top_n de 5–10.
  7. Define un umbral de puntuación o un límite de elementos, arma el contexto y entrégalo al modelo generativo.

Puntos que suelen pasarse por alto:

  • Filtra antes de reordenar: permisos, inquilino, idioma y versión deben filtrarse durante la recuperación o antes del reordenamiento; no esperes a borrar después de generar.
  • Conserva IDs estables: el reordenamiento devuelve índices; el sistema de negocio debe poder mapearlos de vuelta al ID del documento, el título y la URL.
  • Reordena por fragmentos: en RAG normalmente se reordenan fragmentos, no documentos completos. Un fragmento demasiado largo diluye la relevancia; uno demasiado corto pierde contexto.
  • Recuperación híbrida: los nombres propios, modelos y números se recuperan mejor por palabras clave; las preguntas semánticas, mejor por vectores. Combinar ambas rutas antes de reordenar suele dar mejores resultados que una sola.

6. Latencia, tiempos de espera y degradación

La latencia del reordenamiento crece aproximadamente con «cantidad de documentos × longitud de cada documento». Cien documentos cortos suelen responderse rápido; cientos de documentos largos se vuelven notablemente más lentos. Antes de lanzar, mide al menos tres cifras: latencia P50 y P95 con 30, 50 y 100 candidatos.

Recomendaciones de ingeniería:

  • Asigna un tiempo de espera independiente a las solicitudes de Rerank; un punto de partida habitual es 10–30 segundos, y luego ajústalo según las mediciones.
  • Reintenta con retroceso solo un número limitado de veces ante 429 y 5xx; no reintentes 401, 403 o 422.
  • Si el reordenamiento agota el tiempo o falla, degrada al orden original de la recuperación vectorial; no hagas fallar toda la respuesta.
  • Cachea resultados de consultas frecuentes y de baja variación; la clave de caché debe incluir al menos la consulta, los IDs de documentos y el nombre del modelo.
  • Ejecuta en paralelo la recuperación vectorial y la de palabras clave, combina y luego reordena para reducir esperas en serie.
  • La interfaz de reordenamiento devuelve el resultado completo de una vez y no admite streaming; no diseñes el frontend como si fuera una interfaz de streaming.

Si la latencia sigue siendo alta, reduce primero el conjunto de candidatos y la longitud de los documentos; después considera un modelo más pequeño. Pasar directamente a un modelo más grande no siempre compensa, sobre todo cuando la calidad de la recuperación inicial no es buena.

7. Errores comunes y diagnóstico

Código o síntoma Causa habitual Acción
400 / 422 query vacía, documents vacío o estructura JSON incorrecta Revisa los campos obligatorios y el tipo de arreglo
401 Clave no válida, expirada o encabezado ausente Verifica Authorization y el estado de la clave
403 La clave no tiene permiso de modelo o la cuenta está restringida Revisa el alcance de modelos y el estado de la cuenta
404 Nombre de modelo o ruta del endpoint incorrectos Confirma /v1/rerank y la lista de modelos
429 Concurrencia o cuota que activa el límite de velocidad Reintenta con retroceso y revisa cuota y límites
500 / 502 / 504 Anomalía o tiempo de espera del proveedor Reintenta de forma limitada y luego usa la ruta de degradación

El gateway valida query y documents; si están vacíos, devuelve directamente un error de parámetros. Al diagnosticar, revisa primero el campo message de la respuesta y luego compara con el registro de la solicitud; no trates un 400 como un problema de red y lo reintentes una y otra vez.

8. Evaluación: no te quedes con «parece más preciso»

Antes de lanzar el reordenamiento, prepara un conjunto pequeño de datos etiquetados: 100–300 consultas reales, cada una con 1–3 documentos relevantes marcados. Si no hay condiciones para etiquetar, revisa manualmente al menos 50 consultas y registra ambos órdenes.

Métrica Qué observa Cómo usarla
Recall@50 Si la respuesta correcta está en el conjunto de candidatos Determina el techo de recuperación; si es bajo, corrige primero la recuperación
nDCG@10 Calidad del orden en los primeros puestos Compara con y sin reordenamiento
MRR Posición del primer resultado relevante Adecuada para consultas de pregunta y respuesta
Exactitud de respuesta Si el resultado generado es correcto Validación de extremo a extremo
Latencia P95 Cuán lentas son las solicitudes lentas Define el conjunto de candidatos y el tiempo de espera
Costo por consulta Gasto de recuperación por pregunta Estímalo con la página de precios

Durante la evaluación mantén las variables fijas: las mismas consultas, el mismo resultado de recuperación y el mismo top_n, cambiando solo si hay reordenamiento o qué modelo se usa. Después haz una prueba A/B con poco tráfico en producción y observa exactitud, tasa de respuestas sin resultado y latencia. Si el reordenamiento empeora el resultado, revisa primero si el conjunto de candidatos omite documentos, si los documentos se truncan, si el modelo es adecuado para el idioma y si el umbral se copió de otro escenario.

9. Preguntas frecuentes

¿Rerank puede sustituir la búsqueda vectorial?

No. El reordenamiento solo puede reordenar candidatos existentes; no recupera documentos que nunca entraron al conjunto. La recuperación cubre la cobertura y el reordenamiento la precisión de los primeros puestos.

¿Qué valor conviene para top_n?

Para armar el contexto de un modelo grande, 5–10 es un punto de partida común; si después hay reglas de negocio que filtran, puede fijarse en 20–50. La evaluación decide el valor final.

¿Un conjunto de candidatos más grande siempre es mejor?

No. Un conjunto mayor eleva el techo de recuperación, pero también la latencia, el costo y el ruido. Empieza con 30–50 y usa Recall@50 y nDCG@10 para decidir si amplías.

¿Por qué el resultado empeora después de agregar reordenamiento?

Hay cuatro causas habituales: el conjunto de candidatos no incluye el documento correcto, los fragmentos son demasiado largos o demasiado cortos, el modelo no coincide con el idioma, o el umbral se copió de otro escenario. Revísalas una por una; no cambies solo de modelo.

¿La interfaz de Rerank admite respuestas en streaming?

No. El reordenamiento necesita ver todo el conjunto de candidatos para producir el orden completo y normalmente devuelve todo de una vez. El frontend debe tratarlo como una solicitud JSON normal y configurar un tiempo de espera razonable.

Lecturas relacionadas