Búsqueda híbrida (semántica + léxica)
En esta página
Objetivos
- Comprender por qué es importante combinar la búsqueda semántica y la léxica
- Implementar la búsqueda híbrida mediante Reciprocal Rank Fusion (RRF)
- Utilizar la búsqueda híbrida en bases de datos vectoriales
El problema: ningún enfoque es perfecto por sí solo
La búsqueda semántica destaca gestionando sinónimos, pero puede pasar por alto términos técnicos precisos; la búsqueda léxica hace exactamente lo contrario. Considera la consulta de un administrador de sistemas, «nginx error 503», y observa cómo se comportan ambos motores frente a una base de documentación técnica.
# Consulta: "nginx error 503"
# Semántica → encuentra "problemas del servidor web" (bien) pero pierde "código 503" (falla)
# Léxica → encuentra "nginx error 503" exactamente (bien) pero pierde "timeout del proxy inverso" (falla)
# Híbrida → encuentra ambas ✅
La búsqueda semántica entiende que esto se refiere a un incidente de servidor y muestra artículos generales, pero el número 503 se le escapa: para un modelo de embeddings, 503 y 504 son solo dos números de tres cifras, semánticamente cercanos aunque denoten caídas diferentes. La búsqueda léxica recupera el código exacto, pero pierde el artículo sobre timeouts del proxy inverso, que a menudo describe la causa raíz. Ningún método por separado devuelve la página de resultados correcta; su unión sí lo hace.
Búsqueda léxica con BM25
BM25 es el algoritmo estándar para la búsqueda por palabras clave. Pondera cada término basándose en su rareza en el corpus y su frecuencia en el documento, sacando a la superficie de forma natural términos discriminativos como «503» o «nginx». Sin embargo, debes alimentarlo con tokens limpios: la función de tokenización convierte el texto a minúsculas, extrae las palabras y elimina las palabras vacías (stop words) en francés, que no aportan señal de relevancia.
from rank_bm25 import BM25Okapi
import re
def tokenize(text: str) -> list[str]:
"""Tokenización simple para francés."""
text = text.lower()
tokens = re.findall(r"\b\w+\b", text)
# Eliminar palabras vacías comunes
stop_words = {"le", "la", "les", "de", "du", "des", "un", "une",
"et", "ou", "est", "dans", "pour", "avec", "sur"}
return [t for t in tokens if t not in stop_words]
documents = [
"Comment résoudre l'erreur 503 dans nginx",
"Configuration du reverse proxy avec timeout",
"Guide d'installation de nginx sur Ubuntu",
"Les bases de la cuisine française",
]
# Indexar con BM25
tokenized_corpus = [tokenize(doc) for doc in documents]
bm25 = BM25Okapi(tokenized_corpus)
# Buscar
query_tokens = tokenize("erreur 503 nginx")
bm25_scores = bm25.get_scores(query_tokens)
for i, score in enumerate(bm25_scores):
print(f"BM25 {score:.3f} | {documents[i]}")
Reciprocal Rank Fusion (RRF)
Ahora necesitas combinar las dos clasificaciones, algo más complicado de lo que parece: una puntuación de coseno vive entre 0 y 1, mientras que una puntuación BM25 no tiene límite superior. Sumarlas directamente haría que BM25 aplastara la señal semántica. RRF evita esto ignorando las puntuaciones brutas y manteniendo solo las posiciones: cada documento recibe 1 / (k + rank) en cada lista, y sumas estas contribuciones. Un documento que se posiciona bien en todas partes vence así a un documento que sobresale solo en una lista.
def reciprocal_rank_fusion(
result_lists: list[list[tuple[int, float]]],
k: int = 60
) -> list[tuple[int, float]]:
"""Fusiona múltiples listas de resultados usando RRF.
Args:
result_lists: lista de listas de (doc_id, score)
k: constante RRF (60 es el estándar)
"""
fused_scores: dict[int, float] = {}
for results in result_lists:
for rank, (doc_id, _) in enumerate(results):
if doc_id not in fused_scores:
fused_scores[doc_id] = 0.0
fused_scores[doc_id] += 1.0 / (k + rank + 1)
# Ordenar por puntuación descendente
return sorted(
fused_scores.items(),
key=lambda x: x[1],
reverse=True
)
La constante k, convencionalmente fijada en 60 según la literatura, amortigua la brecha entre las primeras posiciones: sin ella, la primera posición pesaría el doble que la segunda, haciendo que la fusión fuera demasiado sensible a pequeñas diferencias de clasificación.
Canalización híbrida completa
La clase siguiente mantiene ambos índices en paralelo sobre el mismo corpus, ejecuta ambas búsquedas en cada consulta y fusiona las clasificaciones. También devuelve las puntuaciones individuales, un detalle valioso durante el ajuste, ya que compararlas muestra qué motor ha arrastrado un resultado dado.
from openai import OpenAI
from rank_bm25 import BM25Okapi
import numpy as np
class HybridSearch:
def __init__(self, model: str = "text-embedding-3-large"):
self.client = OpenAI()
self.model = model
self.documents: list[str] = []
self.embeddings: np.ndarray | None = None
self.bm25: BM25Okapi | None = None
def index(self, documents: list[str]):
self.documents = documents
# Índice semántico
response = self.client.embeddings.create(
input=documents, model=self.model
)
vectors = sorted(response.data, key=lambda x: x.index)
self.embeddings = np.array(
[v.embedding for v in vectors], dtype=np.float32
)
# Índice BM25
tokenized_corpus = [tokenize(d) for d in documents]
self.bm25 = BM25Okapi(tokenized_corpus)
def search(
self, query: str, k: int = 5,
semantic_weight: float = 0.7,
lexical_weight: float = 0.3
) -> list[dict]:
# Búsqueda semántica
query_emb = self.client.embeddings.create(
input=query, model=self.model
).data[0].embedding
sem_scores = self.embeddings @ np.array(query_emb)
sem_ranking = [
(i, float(sem_scores[i]))
for i in np.argsort(sem_scores)[::-1]
]
# Búsqueda léxica
query_tokens = tokenize(query)
lex_scores = self.bm25.get_scores(query_tokens)
lex_ranking = [
(i, float(lex_scores[i]))
for i in np.argsort(lex_scores)[::-1]
]
# Fusión RRF
fused = reciprocal_rank_fusion(
[sem_ranking, lex_ranking]
)
return [
{
"text": self.documents[doc_id],
"rrf_score": score,
"sem_score": float(sem_scores[doc_id]),
"lex_score": float(lex_scores[doc_id]),
}
for doc_id, score in fused[:k]
]
# Uso
engine = HybridSearch()
engine.index([
"Comment résoudre l'erreur 503 dans nginx",
"Timeout et configuration du reverse proxy",
"Guide d'installation nginx sur Ubuntu",
"Diagnostiquer les problèmes de serveur web",
])
results = engine.search("erreur 503 nginx")
for r in results:
print(f"RRF: {r['rrf_score']:.4f} | "
f"Sem: {r['sem_score']:.3f} | "
f"Lex: {r['lex_score']:.3f} | "
f"{r['text']}")
En este corpus de cuatro documentos, el artículo «nginx error 503» domina la clasificación léxica, mientras que «problemas del servidor web» domina la semántica; la fusión introduce a ambos en el top tres, algo que ningún método lograría por separado.
Búsqueda híbrida nativa en Weaviate
Si ya utilizas Weaviate, no necesitas escribir todo esto: la base de datos integra la fusión y la expone en una única consulta, con un parámetro alpha que equilibra los dos motores: 0 para puramente léxico, 1 para puramente semántico.
import weaviate
wclient = weaviate.connect_to_local()
collection = wclient.collections.get("Document")
# Búsqueda híbrida nativa
results = collection.query.hybrid(
query="erreur 503 nginx",
alpha=0.7, # 0 = puramente léxico, 1 = puramente semántico
limit=5
)
for obj in results.objects:
print(f"[{obj.metadata.score:.3f}] {obj.properties['texte']}")
Un alpha de 0,7 es un punto de partida razonable, pero no es universal: un corpus rico en referencias técnicas y códigos de error se beneficia bajando hacia 0,5, mientras que una base de conocimientos redactada en lenguaje llano puede manejar 0,8. Solo debes ajustar este deslizador con un conjunto de evaluación delante: ese es precisamente el tema de la siguiente lección.
Resumen
- La búsqueda híbrida combina semántica (significado) y léxica (palabras exactas)
- Reciprocal Rank Fusion (RRF) fusiona clasificaciones de forma eficaz
- El parámetro
alphacontrola el equilibrio entre los dos enfoques - Weaviate ofrece búsqueda híbrida de forma nativa