Inicio / Artículos

BM25 Plus pgvector con fusión de rangos recíprocos: búsqueda híbrida para RAG en Python

Búsqueda híbrida para RAG en Python: por qué la recuperación densa omite términos exactos, cómo BM25 y la búsqueda por coseno de pgvector se complementan entre sí, fusionados con RRF en Postgres.

Editor: REACTAPP.TOP8 min de lectura1906 palabras

Fuentes: Why BM25 + pgvector Hybrid Search Beats Naive RAG — A Deep Technical Breakdown

Los vectores densos por sí solos omiten palabras clave exactas, términos raros y jerga del dominio. Combinar un clasificador léxico con un índice vectorial corrige esa deficiencia, y todo esto encaja en una pila de Python centrada en Postgres. A continuación se explican las matemáticas, la arquitectura y el código.

Qué falla con el RAG simple

Un pipeline básico de recuperación mejorada es breve:

  1. Incorporar la consulta con un modelo como text-embedding-3-small.
  2. Ejecutar una búsqueda por coseno en un almacén de vectores como pgvector, Pinecone o Weaviate.
  3. Tomar los fragmentos de los K mejores.
  4. Insertarlos en el prompt del LLM.

Esto funciona hasta que una consulta se basa en una cadena literal. Supongamos que un usuario pregunta cómo un proyecto utiliza BM25 para el ranking. El embedding de la consulta termina cerca de vectores relacionados con el ranking, los algoritmos de búsqueda y la puntuación de relevancia, por lo que un documento que contenga el token literal BM25 puede perder frente a una página más vaga sobre modelos de recuperación de información. Ese es el problema de la incompatibilidad de vocabulario, del cual los investigadores en recuperación de información son conscientes desde la década de 1990.

Los embeddings comprimen el significado en un espacio continuo, y en el proceso difuminan las coincidencias exactas. La similitud entre “infarto de miocardio” y “ataque al corazón” es deseable. Sin embargo, la similitud entre BM25 y Okapi ranking representa una desventaja cuando la consulta es específica.

BM25 en resumen

BM25, abreviatura de Best Match 25, es una función de ponderación de términos probabilística perteneciente a la familia de modelos de recuperación Okapi. Para un documento d y una consulta q, suma los términos de la consulta:

score(q, d) = Σ IDF(tᵢ) · [f(tᵢ, d) · (k₁ + 1)] / [f(tᵢ, d) + k₁ · (1 - b + b · |d| / avgdl)]

Los símbolos significan lo siguiente:

  • tᵢ es uno de los términos de la consulta.
  • f(tᵢ, d) cuenta cuántas veces aparece ese término en el documento.
  • |d| es la longitud del documento en tokens y avgdl es la longitud promedio en todo el corpus.
  • k₁, que suele estar entre 1.2 y 2.0, determina la rapidez con la que se satura la frecuencia de términos; por lo tanto, un valor más alto otorga más importancia a la frecuencia.
  • b, que está entre 0 y 1, controla la normalización de la longitud, siendo 0 que no hay normalización y 1 que la hay completa.
  • IDF(tᵢ) es el logaritmo de la relación entre los documentos que no contienen el término y los que sí lo contienen (cada uno desplazado medio documento), más uno. Aquí N cuenta todos los documentos y n(tᵢ) cuenta aquellos que contienen el término.

Tres intuiciones explican por qué funciona bien. La frecuencia de términos se satura, por lo que mencionar BM25 diez veces no genera diez veces la puntuación de una mención sola, y k₁ da forma a esa curva. La normalización de longitud evita que los documentos sean penalizados por un conteo bruto bajo, mientras que b escala según la longitud promedio. Además, la frecuencia inversa de documentos favorece a los términos raros: “BM25” en un corpus de texto de aprendizaje automático general tiene un peso alto, mientras que “the” casi no tiene ninguno.

Todo esto hace que BM25 sea excelente para consultas de coincidencia exacta, términos raros y consultas con muchas palabras clave, que es el ámbito en el que los embeddings densos tienen dificultades.

pgvector y recuperación densa

pgvector es una extensión de PostgreSQL que almacena embeddings y permite realizar búsquedas de vecinos más cercanos de forma aproximada mediante gráficos HNSW o índices IVFFlat. La similitud entre un vector de consulta y un vector de documento se mide mediante el coseno:

cosine_sim(q, dᵢ) = (q · dᵢ) / (‖q‖ · ‖dᵢ‖)

Las consultas HNSW tardan aproximadamente un tiempo logarítmico, con una memoria proporcional a N veces M, donde M es la cantidad de enlaces bidireccionales que se conservan por nodo. Esto permite realizar búsquedas en menos de un milisegundo incluso con millones de vectores. La búsqueda densa destaca en la correspondencia semántica, como las paráfrasis, las variaciones lingüísticas y la similitud a nivel conceptual. No indexa cadenas exactas por la razón mencionada anteriormente.

Combinar los dos métodos con Fusión de Rangos Recíprocos

Existen dos listas ordenadas: una proveniente de BM25 y otra de pgvector. La Fusión de Rangos Recíprocos las combina asignando a cada documento una puntuación según su posición en cada lista:

RRF(d) = Σᵢ 1 / (k + rankᵢ(d))

La constante k es 60. Su función es atenuar el efecto de los rangos muy altos, y ha demostrado ser eficaz en numerosas tareas. La suma se aplica a ambos recuperadores.

¿Por qué preferir RRF a un combinador aprendido? No se necesita datos de relevancia etiquetados. Funciona con rangos y no con puntuaciones, lo que evita la discrepancia entre los valores de BM25, que no tienen límite, y los valores de coseno, que están entre -1 y 1. Además, Cormack y sus colegas demostraron en 2009 que RRF iguala o supera a una combinación lineal ponderada sin necesidad de ajustes. Una mezcla simple como α · bm25_score + β · cosine_score es menos fiable, ya que las cifras brutas se encuentran en escalas incompatibles.

Evidencia de pruebas de rendimiento

En el benchmark BEIR, un conjunto mixto que abarca corpora biomédicos, de noticias y técnicos, combinando BM25 con recuperación densa tiende a superar a cada enfoque por separado. TREC-COVID es un caso ilustrativo: allí BM25 supera al modelo denso, ya que las consultas biomédicas como “SARS-CoV-2 spike protein ACE2 binding” están repletas de términos altamente específicos que los embeddings difuminan. El híbrido mantiene las ventajas de ambos.

Implementación en Python

Configuración

Todo se encuentra en un único esquema de Postgres. Primero instale las dependencias:

# requirements: psycopg2, pgvector, rank-bm25, openai, numpy

Luego configure la conexión, el tipo de vector y las bibliotecas:

import psycopg2
from pgvector.psycopg2 import register_vector
from rank_bm25 import BM25Okapi
import openai
import numpy as np
from typing import List, Tuple# ── DB setup ──────────────────────────────────────────────────────────────
conn = psycopg2.connect("postgresql://user:pass@localhost/ragdb")
register_vector(conn)with conn.cursor() as cur:
    cur.execute("CREATE EXTENSION IF NOT EXISTS vector;")
    cur.execute("""
        CREATE TABLE IF NOT EXISTS documents (
            id        SERIAL PRIMARY KEY,
            content   TEXT NOT NULL,
            embedding vector(1536)       -- text-embedding-3-small dim
        );
    """)
    # HNSW index: m=16 (edges/node), ef_construction=64 (build-time beam width)
    cur.execute("""
        CREATE INDEX IF NOT EXISTS doc_hnsw_idx
        ON documents USING hnsw (embedding vector_cosine_ops)
        WITH (m = 16, ef_construction = 64);
    """)
    conn.commit()

Indexación

Un ayudante envuelve la llamada a la API de embedding:

def embed(texts: List[str]) -> List[List[float]]:
    resp = openai.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [r.embedding for r in resp.data]

Y la función de indexación almacena cada documento junto con su representación vectorial:

def index_documents(docs: List[str]) -> None:
    embeddings = embed(docs)
    with conn.cursor() as cur:
        for doc, emb in zip(docs, embeddings):
            cur.execute(
                "INSERT INTO documents (content, embedding) VALUES (%s, %s)",
                (doc, emb)
            )
        conn.commit()

Recuperación híbrida

La búsqueda léxica clasifica el corpus con BM25Okapi:

def bm25_search(
    corpus: List[str],
    query: str,
    top_k: int = 20
) -> List[Tuple[int, float]]:
    """Returns [(doc_idx, bm25_score), ...] sorted descending."""
    tokenized = [doc.lower().split() for doc in corpus]
    bm25 = BM25Okapi(tokenized, k1=1.5, b=0.75)
    scores = bm25.get_scores(query.lower().split())
    ranked = sorted(enumerate(scores), key=lambda x: x[1], reverse=True)
    return ranked[:top_k]

Las consultas de búsqueda densas de pgvector y el paso de fusión aplican entonces RRF:

def dense_search(
    query: str,
    top_k: int = 20
) -> List[Tuple[int, float]]:
    """Returns [(doc_id, cosine_sim), ...] sorted descending."""
    q_emb = embed([query])[0]
    with conn.cursor() as cur:
        cur.execute("""
            SELECT id, 1 - (embedding <=> %s::vector) AS cosine_sim
            FROM documents
            ORDER BY embedding <=> %s::vector
            LIMIT %s;
        """, (q_emb, q_emb, top_k))
        return [(row[0], row[1]) for row in cur.fetchall()]
def reciprocal_rank_fusion(
    *ranked_lists: List[Tuple[int, float]],
    k: int = 60
) -> List[Tuple[int, float]]:
    """
    RRF(d) = Σᵢ 1 / (k + rankᵢ(d))
    k=60 is the standard constant from Cormack et al. 2009.
    """
    scores: dict[int, float] = {}
    for ranked in ranked_lists:
        for rank, (doc_id, _) in enumerate(ranked, start=1):
            scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
    return sorted(scores.items(), key=lambda x: x[1], reverse=True)
def hybrid_retrieve(
    corpus: List[str],
    doc_ids: List[int],        # DB IDs aligned with corpus
    query: str,
    top_k: int = 5
) -> List[dict]:
    """
    Full hybrid pipeline:
      1. BM25 sparse search
      2. pgvector dense ANN search
      3. RRF fusion
      4. Return top-K merged results
    """
    bm25_results  = bm25_search(corpus, query, top_k=20)
    # Map corpus index → DB id for BM25
    bm25_db = [(doc_ids[idx], score) for idx, score in bm25_results]    dense_results = dense_search(query, top_k=20)    fused = reciprocal_rank_fusion(bm25_db, dense_results, k=60)    # Fetch content for top-K
    top_ids = [doc_id for doc_id, _ in fused[:top_k]]
    with conn.cursor() as cur:
        cur.execute(
            "SELECT id, content FROM documents WHERE id = ANY(%s)",
            (top_ids,)
        )
        rows = {row[0]: row[1] for row in cur.fetchall()}    return [
        {"id": doc_id, "rrf_score": score, "content": rows.get(doc_id, "")}
        for doc_id, score in fused[:top_k]
    ]

Generación de respuestas

La etapa final obtiene los mejores resultados y construye el contexto:

def rag_answer(query: str, corpus: List[str], doc_ids: List[int]) -> str:
    results = hybrid_retrieve(corpus, doc_ids, query, top_k=5)
    context = "\n\n---\n\n".join(r["content"] for r in results)

Una instrucción restrictiva mantiene al modelo centrado en lo que fue recuperado:

    prompt = f"""You are a precise technical assistant.
Use only the provided context to answer the question.
If the context doesn't contain the answer, say so.Context:
{context}Question: {query}
Answer:"""    resp = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
        temperature=0
    )
    return resp.choices[0].message.content

Parámetros que vale la pena ajustar

En BM25, el valor por defecto de k₁ es 1.5; un valor más alto otorga más peso a los términos repetidos, lo cual es adecuado para consultas extensas. El valor por defecto de b en BM25 es 0.75, y aumentarlo refuerza la penalización por longitud. En HNSW, el valor por defecto de m es 16, ya que más aristas significan una mejor recuperación a costa de la memoria, mientras que el valor por defecto de ef_construction es 64; un valor mayor mejora la calidad del índice pero ralentiza su creación. El valor de k en RRF, que es 60, puede ser menor si se desea que el resultado mejor clasificado tenga mayor influencia. Obtener 20 candidatos por recuperador es un valor por defecto razonable, y en general, más candidatos mejoran la fusión de resultados.

En corpus con muchos términos específicos de un dominio, como los médicos, legales o de código, reduzca b a 0.5 para atenuar la penalización en documentos técnicos largos, y aumente k₁ a 2.0 para recompensar los términos técnicos repetidos.

Elegir el recuperador adecuado

Las palabras clave exactas, los códigos de producto y los nombres de API favorecen a BM25. Las consultas conceptuales, parafraseadas o multilingües favorecen a la búsqueda densa. La mayoría de las consultas reales son una combinación de ambas, lo que hace que la opción híbrida con RRF sea la mejor, y el jerga técnica en medicina, derecho o programación funciona mejor con BM25 o la opción híbrida.

Conclusión

Naive RAG ofrece una buena línea de base, pero deja de lado la capacidad de recuperación en consultas con muchas palabras clave o de carácter especializado. La solución es sencilla desde el punto de vista arquitectónico: ejecutar BM25 sobre el mismo corpus junto con la búsqueda de pgvector, fusionar las dos listas ordenadas con RRF utilizando k=60, y enviar las mejores entradas fusionadas al LLM. El sistema de recuperación resultante maneja igualmente bien preguntas semánticas como “¿qué es el aprendizaje automático?” y preguntas léxicas como “muéstrame cómo se maneja el parámetro k1 en BM25Okapi”, sin necesidad de entrenar un modelo adicional y con solo un procesamiento adicional de orden de microsegundos para BM25.

pgvector viene incluido en Postgres, BM25 se instala mediante rank-bm25, y RRF ocupa unas pocas líneas de código. Hay pocos obstáculos para incorporar una búsqueda híbrida en un sistema RAG en producción.

Leer más

  • Diseño de búsquedas semánticas portátiles multi-inquilino en Kubernetes y Qdrant — Cómo una plataforma de búsqueda semántica utiliza Kubernetes para lograr portabilidad y enrutamiento sensible al inquilino, a fin de mantener su base de datos vectorial reemplazable y sus cargas de trabajo aisladas.
  • Más allá del RAG naïf: costos de memoria de HNSW, búsqueda híbrida y contexto largo — Por qué los índices vectoriales en memoria chocan con limitaciones a gran escala, donde falla la recuperación de coincidencias exactas, y cómo los híbridos BM25, RRF y PostgreSQL se adaptan a un mundo de contexto largo.
  • RAG autohospedado para preguntas y respuestas sobre documentos: LangChain, pgvector y LLMs intercambiables — Cómo una aplicación RAG de código abierto convierte archivos PDF y DOCX en respuestas: fragmentación, pgvector, un cambio de configuración entre OpenAI y Claude, y lecciones obtenidas al desarrollar con presupuesto limitado.