Pesquisa híbrida (semântica + lexical)
Nesta página
Objetivos
- Compreender por que é importante combinar pesquisa semântica e lexical
- Implementar pesquisa híbrida usando Reciprocal Rank Fusion (Fusão de Classificação Recíproca)
- Utilizar pesquisa híbrida em bases de dados vetoriais
O problema: nenhuma abordagem isolada é perfeita
A pesquisa semântica destaca-se no tratamento de sinónimos, mas pode falhar na deteção de termos técnicos precisos; a pesquisa lexical faz exatamente o oposto. Considere a consulta de um administrador de sistemas, “nginx error 503”, e observe como ambos os motores se comportam face a uma base de documentação técnica.
# Query: "nginx error 503"
# Semantic → finds "web server issues" (good) but misses "code 503" (missed)
# Lexical → finds "nginx error 503" exactly (good) but misses "reverse proxy timeout" (missed)
# Hybrid → finds both ✅
A pesquisa semântica entende que isto se refere a um incidente de servidor e apresenta artigos gerais, mas o número 503 escapa-lhe: para um modelo de incorporação (embedding), 503 e 504 são apenas dois números de três dígitos, semanticamente próximos, embora denotem indisponibilidades diferentes. A pesquisa lexical recupera o código exato, mas perde o artigo sobre tempos limite (timeouts) de proxy reverso, que muitas vezes descreve a causa raiz. Nenhum método isolado devolve a página de resultados correta; a união de ambos sim.
Pesquisa lexical com BM25
O BM25 é o algoritmo padrão para pesquisa por palavras-chave. Pondera cada termo com base na sua raridade no corpus e na sua frequência no documento, destacando naturalmente termos discriminativos como “503” ou “nginx”. No entanto, deve fornecer-lhe tokens limpos: a função de tokenização coloca o texto em minúsculas, extrai as palavras e remove as palavras de parada (stop words) em francês, que não acrescentam sinal de relevância.
from rank_bm25 import BM25Okapi
import re
def tokenize(text: str) -> list[str]:
"""Simple tokenization for French."""
text = text.lower()
tokens = re.findall(r"\b\w+\b", text)
# Remove common stop words
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",
]
# Index with BM25
tokenized_corpus = [tokenize(doc) for doc in documents]
bm25 = BM25Okapi(tokenized_corpus)
# Search
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)
Agora precisa de combinar as duas classificações, o que é mais complicado do que parece: uma pontuação de cosseno situa-se entre 0 e 1, enquanto uma pontuação BM25 não tem limite superior. Somá-las diretamente faria com que o BM25 sufocasse o sinal semântico. O RRF contorna este problema ignorando as pontuações brutas e mantendo apenas as classificações: cada documento recebe 1 / (k + rank) em cada lista, e soma-se estas contribuições. Um documento bem classificado em todo o lado supera assim um documento que se destaca apenas numa lista.
def reciprocal_rank_fusion(
result_lists: list[list[tuple[int, float]]],
k: int = 60
) -> list[tuple[int, float]]:
"""Fuses multiple result lists using RRF.
Args:
result_lists: list of lists of (doc_id, score)
k: RRF constant (60 is standard)
"""
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)
# Sort by score descending
return sorted(
fused_scores.items(),
key=lambda x: x[1],
reverse=True
)
A constante k, convencionalmente definida como 60 com base na literatura, atenua a diferença entre as primeiras posições: sem ela, a primeira classificação pesaria o dobro da segunda, tornando a fusão demasiado sensível a pequenas diferenças de classificação.
Pipeline híbrido completo
A classe abaixo mantém ambos os índices em paralelo sobre o mesmo corpus, executa ambas as pesquisas em cada consulta e funde as classificações. Devolve também as pontuações individuais — um detalhe valioso durante o ajuste (tuning), pois compará-las mostra qual motor sustentou um determinado resultado.
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
# Semantic index
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
)
# BM25 index
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]:
# Semantic search
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]
]
# Lexical search
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]
]
# RRF Fusion
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]
]
# Usage
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']}")
Neste corpus de quatro documentos, o artigo “nginx error 503” domina a classificação lexical, enquanto “web server issues” domina a semântica; a fusão traz ambos para o top três, algo que nenhum método conseguiria alcançar isoladamente.
Pesquisa híbrida nativa no Weaviate
Se já utiliza o Weaviate, não precisa de escrever tudo isto: a base de dados integra a fusão e expõe-na numa única consulta, com um parâmetro alpha que equilibra os dois motores — 0 para pesquisa puramente lexical, 1 para puramente semântica.
import weaviate
wclient = weaviate.connect_to_local()
collection = wclient.collections.get("Document")
# Native hybrid search
results = collection.query.hybrid(
query="erreur 503 nginx",
alpha=0.7, # 0 = pure lexical, 1 = pure semantic
limit=5
)
for obj in results.objects:
print(f"[{obj.metadata.score:.3f}] {obj.properties['texte']}")
Um alpha de 0,7 é um ponto de partida razoável, mas não é universal: um corpus rico em referências técnicas e códigos de erro beneficia de descer para 0,5, enquanto uma base de conhecimento escrita em linguagem corrente pode suportar 0,8. Ajuste este controlo apenas com um conjunto de avaliação à sua frente — esse é precisamente o tema da próxima lição.
Pontos-chave
- A pesquisa híbrida combina semântica (significado) e lexical (palavras exatas)
- O Reciprocal Rank Fusion (RRF) funde classificações de forma eficaz
- O parâmetro
alphacontrola o equilíbrio entre as duas abordagens - O Weaviate oferece pesquisa híbrida nativamente