Búsqueda Híbrida y Reranking Dentro de Postgres: Medí el Recall, No Adivines

1. El Problema: Los Vectores Pierden Términos Exactos, las Keywords Pierden Significado

Pedile a un retriever denso ’error E1042 en el checkout’ y te devuelve páginas sobre fallos de pago en general: cercanas semánticamente, prácticamente inútiles. Pedile a un índice por keywords ’¿por qué me rechazaron la tarjeta?’ cuando el documento dice ’transacción rechazada por el emisor’ y no devuelve nada. La búsqueda densa generaliza el significado y desdibuja los identificadores; la léxica clava los identificadores y no tiene idea de paráfrasis. Los corpus reales — docs, tickets, código, contratos — traen los dos tipos de consulta todos los días.

La solución tiene tres piezas, y las tres caben dentro de Postgres: dos retrievers baratos que fallan distinto, una fusión por rango que no necesita calibrar scores y un cross-encoder caro que solo ve una lista corta de candidatos. Salteo a propósito lo básico de pgvector y el chunking — la guía de bases vectoriales y la de chunking, en los artículos relacionados, los cubren — y arranco donde ellas terminan.

2. Conceptos Mínimos Antes de Tocar Código

Seis ideas cubren casi todo lo que sigue. Con esto claro, el SQL y el Python se leen como castellano simple.

3. Elegí la Pata Léxica: tsvector, pg_textsearch o pg_search

Postgres te da tres opciones realistas para el lado de keywords, y la correcta depende menos de las features que de lo que tu hosting te deja instalar. Chequeé los datos de abajo contra la documentación de cada proyecto en octubre de 2026; estos proyectos se mueven rápido, así que verificá antes de fijar una versión.

Preguntale a tu base qué puede instalar realmente

SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('vector', 'pg_textsearch', 'pg_search');

4. Paso 1 — Schema y la Query Fusionada (Una Sola Sentencia SQL)

Una tabla guarda el texto, el embedding y un tsvector generado. Los dos índices son estándar: GIN para la pata léxica, HNSW con cosine ops para la densa. Las 384 dimensiones coinciden con el modelo de sentence-transformers de los pasos en Python; cambialo para que coincida con el tuyo.

SQL — tabla e índices

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
    id        bigserial PRIMARY KEY,
    doc_id    text NOT NULL,
    content   text NOT NULL,
    embedding vector(384),
    tsv       tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
);

CREATE INDEX chunks_tsv_idx ON chunks USING GIN (tsv);
CREATE INDEX chunks_emb_idx ON chunks USING hnsw (embedding vector_cosine_ops);

La fusión vive en una sola sentencia, adaptada del ejemplo de RRF del repo Python de pgvector. Cada pata es una subquery con ORDER BY y LIMIT, así que el índice hace el trabajo; ROW_NUMBER convierte posición en rank; un FULL OUTER JOIN suma weight / (k + rank) con COALESCE para los chunks que solo devolvió una pata. Los placeholders %(name)s son parámetros nombrados de psycopg. Uso k = 60 y pesos iguales como puntos de partida, no como conclusiones.

SQL — hybrid.sql (parámetros nombrados de psycopg)

WITH semantic AS (
    SELECT id, ROW_NUMBER() OVER (ORDER BY dist, id) AS rank
    FROM (
        SELECT id, embedding <=> %(embedding)s AS dist
        FROM chunks
        ORDER BY embedding <=> %(embedding)s
        LIMIT %(n)s
    ) s
),
lexical AS (
    SELECT id, ROW_NUMBER() OVER (ORDER BY score DESC, id) AS rank
    FROM (
        SELECT id, ts_rank_cd(tsv, q) AS score
        FROM chunks, websearch_to_tsquery('english', %(query)s) AS q
        WHERE tsv @@ q
        ORDER BY score DESC, id
        LIMIT %(n)s
    ) l
),
fused AS (
    SELECT COALESCE(s.id, l.id) AS id,
           COALESCE(%(w_dense)s / (%(k)s + s.rank), 0.0)
         + COALESCE(%(w_lex)s   / (%(k)s + l.rank), 0.0) AS score
    FROM semantic s
    FULL OUTER JOIN lexical l ON s.id = l.id
)
SELECT c.id, c.doc_id, c.content, f.score
FROM fused f
JOIN chunks c ON c.id = f.id
ORDER BY f.score DESC, c.id
LIMIT %(limit)s;

Cuando el harness diga que el lado de keywords es el eslabón débil, cambiá solo el CTE léxico. Esta es la versión con pg_textsearch, siguiendo su README: creás el índice bm25 con un text_config y ordenás por el operador <@>, que devuelve scores BM25 negativos, así que el orden ascendente pone primero al mejor match.

SQL — pata léxica BM25 con pg_textsearch

-- después de agregar pg_textsearch a shared_preload_libraries y reiniciar
CREATE EXTENSION pg_textsearch;

CREATE INDEX chunks_bm25_idx ON chunks
    USING bm25 (content) WITH (text_config = 'english');

-- reemplaza el CTE "lexical" de hybrid.sql
lexical AS (
    SELECT id, ROW_NUMBER() OVER (ORDER BY score, id) AS rank
    FROM (
        SELECT id, content <@> to_bm25query(%(query)s, 'chunks_bm25_idx') AS score
        FROM chunks
        ORDER BY content <@> to_bm25query(%(query)s, 'chunks_bm25_idx')
        LIMIT %(n)s
    ) l
),

5. Paso 2 — Rerank con Cross-Encoder (Local o Hosteado)

Traé el top-N desde SQL, puntuá cada par (consulta, chunk) con un cross-encoder y ordená por ese score. La función rerank recibe las filas que devolvió el SQL, así que podés cambiar de modelo sin tocar el retrieval. La versión local usa BAAI/bge-reranker-v2-m3 vía FlagEmbedding, siguiendo su model card.

Python — retrieval.py (SQL híbrido + rerank local)

from pathlib import Path

import psycopg
from FlagEmbedding import FlagReranker
from pgvector.psycopg import register_vector
from sentence_transformers import SentenceTransformer

conn = psycopg.connect("dbname=hybrid_demo", autocommit=True)
register_vector(conn)

embedder = SentenceTransformer("multi-qa-MiniLM-L6-cos-v1")  # 384 dims, como en el schema
reranker = FlagReranker("BAAI/bge-reranker-v2-m3", use_fp16=True)

HYBRID_SQL = Path("hybrid.sql").read_text()


def hybrid(query, n=50, k=60, limit=50, w_dense=1.0, w_lex=1.0):
    params = {
        "embedding": embedder.encode(query), "query": query,
        "n": n, "k": k, "limit": limit, "w_dense": w_dense, "w_lex": w_lex,
    }
    return conn.execute(HYBRID_SQL, params).fetchall()  # (id, doc_id, content, score)


def rerank(query, rows, top_k=10):
    pairs = [[query, content] for _, _, content, _ in rows]
    scores = reranker.compute_score(pairs, normalize=True)  # sigmoid -> 0..1
    if isinstance(scores, float):  # un solo par devuelve un escalar
        scores = [scores]
    order = sorted(range(len(rows)), key=lambda i: scores[i], reverse=True)
    return [rows[i] for i in order[:top_k]]

¿Qué modelo? Las dos opciones abiertas de abajo son Apache-2.0 en sus model cards de Hugging Face, y las dos APIs hosteadas exponen la misma forma: mandás una consulta y una lista de textos, recibís índices y scores de relevancia. Tomá los tamaños y límites como los declara la documentación hoy y volvé a chequearlos antes de comprometerte.

Python — alternativas intercambiables (misma firma)

# Local: Qwen3-Reranker vía sentence-transformers (requiere transformers>=4.51.0)
from sentence_transformers import CrossEncoder

qwen = CrossEncoder("Qwen/Qwen3-Reranker-0.6B")

def rerank_qwen(query, rows, top_k=10):
    scores = qwen.predict([(query, r[2]) for r in rows])
    order = sorted(range(len(rows)), key=lambda i: scores[i], reverse=True)
    return [rows[i] for i in order[:top_k]]


# Hosteado: API v2 de Cohere Rerank (el cliente lee la API key del entorno)
import cohere

co = cohere.ClientV2()

def rerank_cohere(query, rows, top_k=10):
    resp = co.rerank(
        model="rerank-v4.0-pro",  # o rerank-v4.0-fast / rerank-v3.5
        query=query,
        documents=[r[2] for r in rows],
        top_n=top_k,
    )
    return [rows[r.index] for r in resp.results]


# Hosteado: Voyage rerank (usa la variable de entorno VOYAGE_API_KEY)
import voyageai

vo = voyageai.Client()

def rerank_voyage(query, rows, top_k=10):
    out = vo.rerank(query, [r[2] for r in rows], model="rerank-3", top_k=top_k)
    return [rows[r.index] for r in out.results]

6. Paso 3 — Medí recall@k Antes y Después

Sin este paso todo lo anterior es sensación. Escribí entre 50 y 100 consultas reales (de logs de búsqueda, tickets de soporte o de la gente que conoce el corpus) y, para cada una, listá los doc_ids que realmente la responden. La guía de chunking en los artículos relacionados muestra cómo armar un set así; acá es solo un archivo JSONL.

gold.jsonl — una consulta etiquetada por línea (formato)

{"query": "error E1042 on checkout", "relevant": ["doc-0172"]}
{"query": "how do I rotate refresh tokens?", "relevant": ["doc-0031", "doc-0032"]}

Python — eval.py: cuatro estrategias, mismas consultas

import json
import statistics
import time

from retrieval import conn, embedder, hybrid, rerank

N = 50  # candidatos por pata y largo de la lista fusionada
KS = (5, 10, N)  # recall@N es el techo de candidatos

DENSE_SQL = """
SELECT id, doc_id, content, 0.0 AS score FROM chunks
ORDER BY embedding <=> %(embedding)s LIMIT %(n)s
"""
LEXICAL_SQL = """
SELECT id, doc_id, content, ts_rank_cd(tsv, q) AS score
FROM chunks, websearch_to_tsquery('english', %(query)s) AS q
WHERE tsv @@ q ORDER BY score DESC LIMIT %(n)s
"""


def dense(q):
    return conn.execute(DENSE_SQL, {"embedding": embedder.encode(q), "n": N}).fetchall()


def lexical(q):
    return conn.execute(LEXICAL_SQL, {"query": q, "n": N}).fetchall()


STRATEGIES = {
    "dense": dense,
    "lexical": lexical,
    "hybrid RRF": lambda q: hybrid(q, n=N, limit=N),
    "hybrid + rerank": lambda q: rerank(q, hybrid(q, n=N, limit=N), top_k=N),
}


def doc_order(rows):  # chunks -> doc_ids únicos en orden de rank
    seen, out = set(), []
    for _, doc_id, _, _ in rows:
        if doc_id not in seen:
            seen.add(doc_id)
            out.append(doc_id)
    return out


gold = [json.loads(line) for line in open("gold.jsonl", encoding="utf-8")]
hybrid(gold[0]["query"])  # warm-up: la carga de modelos y las cachés no deben contar

for name, fn in STRATEGIES.items():
    recall, rr, lat = {k: 0.0 for k in KS}, 0.0, []
    for ex in gold:
        t0 = time.perf_counter()
        docs = doc_order(fn(ex["query"]))
        lat.append((time.perf_counter() - t0) * 1000)
        rel = set(ex["relevant"])
        for k in KS:
            recall[k] += len(rel & set(docs[:k])) / len(rel)
        first = next((i for i, d in enumerate(docs, 1) if d in rel), None)
        rr += 1.0 / first if first else 0.0
    n = len(gold)
    p95 = statistics.quantiles(lat, n=20)[18]  # requiere al menos 2 consultas
    cols = " ".join(f"recall@{k}={recall[k] / n:.3f}" for k in KS)
    print(f"{name:16} {cols} MRR={rr / n:.3f} p50={statistics.median(lat):.0f}ms p95={p95:.0f}ms")

Corrélo una vez ahora para obtener tu baseline solo-denso, y de nuevo después de cada cambio. Esta es la forma de salida que deberías esperar. Dejo los números como placeholders a propósito: cualquier cifra que imprimiera acá sería inventada, y las tuyas dependen de tu corpus, tus chunks, tu embedder y tu hardware.

Forma de la salida esperada (placeholders, no resultados)

dense            recall@5=?.??? recall@10=?.??? recall@50=?.??? MRR=?.??? p50=??ms p95=??ms
lexical          recall@5=?.??? recall@10=?.??? recall@50=?.??? MRR=?.??? p50=??ms p95=??ms
hybrid RRF       recall@5=?.??? recall@10=?.??? recall@50=?.??? MRR=?.??? p50=??ms p95=??ms
hybrid + rerank  recall@5=?.??? recall@10=?.??? recall@50=?.??? MRR=?.??? p50=??ms p95=??ms

7. Operarlo: Latencia, Filtros e Higiene de Índices

El camino de la query es la parte fácil. Esta es la rutina que lo mantiene honesto cuando llegan tráfico real y cambios de datos reales:

8. Errores Comunes (Todos Arreglables en una Tarde)

La mayoría de las decepciones con búsqueda híbrida se explican por uno de estos baldes. La columna izquierda es lo que hacen los stacks que funcionan; la derecha es lo que empeora el retrieval en silencio.

Conclusión

Ya tenés el loop completo dentro de Postgres: una pata léxica (tsvector nativo, o BM25 con pg_textsearch o pg_search), una pata de pgvector, Reciprocal Rank Fusion con k = 60 en una sola sentencia SQL, un rerank con cross-encoder que es un cambio de una función entre modelos locales Apache-2.0 y Cohere o Voyage hosteados, y un harness que convierte ’siento que mejora’ en recall@k y MRR.

Esta semana: escribí 50 consultas etiquetadas, corré eval.py sobre el retrieval solo-denso de hoy para tener el baseline, y después sumá una cosa por vez (pata léxica, fusión, reranker) quedándote solo con lo que los números justifiquen. Una última nota de honestidad: no corrí benchmarks para este artículo, así que toda afirmación sobre calidad es algo que tu propio harness tiene que confirmar.

Fuentes

• pgvector — README (búsqueda híbrida, HNSW, iterative index scans, filtrado)
• pgvector-python — Búsqueda híbrida con Reciprocal Rank Fusion (ejemplo)
• Documentación de PostgreSQL — Text search: ranking de resultados (ts_rank, ts_rank_cd, websearch_to_tsquery)
• Documentación de PostgreSQL — Text search: tablas e índices (columna tsvector generada, GIN)
• Cormack, Clarke, Büttcher — Reciprocal Rank Fusion outperforms Condorcet and individual rank learning methods (SIGIR 2009)
• pg_textsearch — README (índice BM25, operador <@>, limitaciones, historial de versiones)
• Tiger Data — pg_textsearch en Google Cloud AlloyDB y Cloud SQL (comunicado, 21 de septiembre de 2026)
• ParadeDB — Reciprocal Rank Fusion (forma de la query pg_search + pgvector, k, pesos, límite por rama)
• ParadeDB — Crear un índice (USING paradedb, alias bm25)
• ParadeDB — Instalación de la extensión en PostgreSQL self-hosted (versiones, shared_preload_libraries, pgvector)
• Documentación de Neon — retiro de pg_search y reemplazo lakebase_text
• BAAI/bge-reranker-v2-m3 — model card de Hugging Face (Apache-2.0, uso de FlagReranker)
• Qwen3-Reranker-0.6B — model card de Hugging Face (Apache-2.0, contexto 32k, uso con CrossEncoder)
• Cohere — Modelos y referencia de la API de Rerank (v2)
• Voyage AI — Rerankers (modelos, límites, API de Python)