/v1/rerank

Resumen

Reordena una lista de documentos candidatos por relevancia respecto a una query. El patrón típico de RAG es de dos etapas: un modelo de embeddings recupera los top-K candidatos desde tu vector store (rápido, con pérdida), y luego un reranker puntúa cada par `(query, doc)` end-to-end sobre el texto crudo (más lento, mucho más preciso). El reranking es la mejora de precisión más grande que puedes añadir encima de un índice vectorial — especialmente si guardas los embeddings con dimensión reducida (p. ej. 1 536-dim en pgvector + HNSW), porque el reranker re-lee el texto completo y recupera la precisión que se perdió al truncar.

Endpoint y modelo

POST `https://api.tesseraai.cloud/v1/rerank`. El campo `model` en el request es el literal `Qwen/Qwen3-Reranker-4B`. La forma de la respuesta sigue el contrato de Cohere `/rerank`.

Cuándo aporta valor el reranking

Vale la pena enchufar reranking cuando se cumple al menos uno de estos casos:

• Recuperas de un vector store y el top-1 no es de forma fiable el documento correcto — la respuesta buena está en el top-K pero posicionada 5.ª, 12.ª, a veces 30.ª.
• Truncaste los embeddings para encajar en un tier de almacenamiento (p. ej. `dimensions: 1536` para entrar en el techo HNSW de pgvector). El reranker re-lee el texto crudo y recupera la precisión que la truncación cedió.
• Tu dominio tiene ruido de parafraseo cercano (legal, soporte, knowledge bases) donde dos documentos parecen semánticamente próximos pero solo uno responde la query.
• Hoy pagas reranking a Cohere / Voyage / Jina y quieres la misma API compatible con Cohere sobre infraestructura EU/LATAM dentro de tu factura plana de Tessera.

Request

Envía la query y la lista de documentos candidatos devueltos por tu vector store. El reranker devuelve el índice de cada documento y un score de relevancia en `[0, 1]`. Pipeline típico: recuperar top 50–100 desde el vector store, hacer rerank, quedarse con los top 10 para la ventana de contexto del LLM.

curl https://api.tesseraai.cloud/v1/rerank \
  -H "Authorization: Bearer $TESSERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-Reranker-4B",
    "query": "cómo restablezco mi contraseña",
    "documents": [
      "Para restablecer tu contraseña, pulsa en olvidé mi contraseña en la pantalla de login.",
      "Nuestro horario de oficina es de lunes a viernes, de 9 a 18.",
      "Requisitos de contraseña: 12+ caracteres, un número, un símbolo."
    ]
  }'

Response

Envelope canónico de Cohere. `results[].index` referencia el orden original del array `documents`; ordena `results` por `relevance_score` descendente y quédate con los top-N para uso aguas abajo.

{
  "id": "a1f2…",
  "results": [
    {"index": 0, "relevance_score": 0.9902},
    {"index": 2, "relevance_score": 0.4118},
    {"index": 1, "relevance_score": 0.00003}
  ],
  "meta": {
    "billed_units": {"total_tokens": 176},
    "tokens": {"input_tokens": 176, "output_tokens": 0}
  }
}

Emparejamiento con /v1/embeddings

Los modelos de embeddings y reranker de Tessera son de la misma familia Qwen3 y están entrenados conjuntamente. Usar ambos es el setup recomendado — mismo tokenizer, mismo template instructivo, sin penalty de calidad por mezclar familias de distintos vendors.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tesseraai.cloud/v1",
    api_key=os.environ["TESSERA_API_KEY"],
)

# Etapa 1 — embed y retrieve de top-50 desde tu vector store.
query_vec = client.embeddings.create(
    model="Qwen/Qwen3-Embedding-8B",
    input=[user_query],
    dimensions=1536,           # encaja en HNSW de pgvector
).data[0].embedding
candidates = vector_store.query(query_vec, top_k=50)

# Etapa 2 — rerank de los 50 candidatos, quedarse con top 10.
import httpx
resp = httpx.post(
    "https://api.tesseraai.cloud/v1/rerank",
    headers={"Authorization": f"Bearer {os.environ['TESSERA_API_KEY']}"},
    json={
        "model": "Qwen/Qwen3-Reranker-4B",
        "query": user_query,
        "documents": [c.text for c in candidates],
    },
    timeout=30.0,
).json()
top10 = sorted(resp["results"], key=lambda r: -r["relevance_score"])[:10]
context = [candidates[r["index"]].text for r in top10]

Casos de uso típicos

• Boost de calidad RAG: mantén tu índice de embeddings actual, mete el reranker entre el retrieval y el LLM — suele ser el cambio de una sola línea con más impacto en exactitud de respuesta.
• Recuperación tras truncar embeddings: si indexaste a 768 / 1 024 / 1 536 dimensiones para encajar en un tier de almacenamiento, el rerank recupera la precisión que la reducción dimensional cedió.
• Retrieval cross-language: query en español, documentos en inglés (o al revés) — el reranker maneja la relevancia translingüística de forma nativa.
• Migración desde Cohere / Voyage / Jina: la forma de la respuesta coincide con la de Cohere, así que cambiar es modificar `base_url` + `model` en la mayoría de clientes.