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.
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:
- Incorporar la consulta con un modelo como
text-embedding-3-small. - Ejecutar una búsqueda por coseno en un almacén de vectores como pgvector, Pinecone o Weaviate.
- Tomar los fragmentos de los K mejores.
- 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 yavgdles 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
- Búsqueda Semántica en PostgreSQL con pgvector y .NET: Una Configuración Práctica — Almacene embeddings junto a los datos relacionales, cree índices HNSW o IVFFlat, filtre y combine rangos híbridos, y determine cuándo pgvector es suficiente para su aplicación.
- GraphRAG vs Vector RAG: Por Qué la Búsqueda Vectorial Falla a Gran Escala — Vector RAG tiene dificultades con el aislamiento de fragmentos, el razonamiento entre documentos y la escalabilidad. Vea cómo GraphRAG crea comunidades y resúmenes para solucionarlo, y cuándo elegir cada uno.