Ricerca ibrida (semantica + lessicale)
In questa pagina
Obiettivi
- Capire perché combinare ricerca semantica e lessicale è fondamentale
- Implementare la ricerca ibrida usando la Reciprocal Rank Fusion
- Utilizzare la ricerca ibrida nei database vettoriali
Il problema: nessun approccio è perfetto da solo
La ricerca semantica eccelle nella gestione dei sinonimi, ma può perdere termini tecnici precisi; la ricerca lessicale fa esattamente l’opposto. Prendi la query di un amministratore di sistema, «nginx error 503», e osserva come si comportano entrambi i motori rispetto a una base di documentazione tecnica.
# 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 ✅
La ricerca semantica capisce che si tratta di un incidente server e propone articoli generali, ma il numero 503 le sfugge: per un modello di embedding, 503 e 504 sono solo due numeri a tre cifre, semanticamente vicini anche se indicano guasti diversi. La ricerca lessicale recupera il codice esatto, ma perde l’articolo sui timeout del reverse proxy, che spesso descrive la causa radice. Da soli, nessuno dei due metodi restituisce la pagina giusta; la loro unione sì.
Ricerca lessicale con BM25
BM25 è l’algoritmo standard per la ricerca per parole chiave. Pesa ogni termine in base alla sua rarità nel corpus e alla sua frequenza nel documento, facendo emergere naturalmente termini discriminanti come «503» o «nginx». Devi però fornirgli token puliti: la funzione di tokenizzazione converte il testo in minuscolo, estrae le parole e rimuove le stop word, che non aggiungono alcun segnale di rilevanza.
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)
Ora devi combinare le due classifiche, operazione più delicata di quanto sembri: un punteggio cosine vive tra 0 e 1, mentre un punteggio BM25 non ha limite superiore. Sommarli direttamente permetterebbe a BM25 di sovrastare il segnale semantico. La RRF aggira il problema ignorando i punteggi grezzi e mantenendo solo le posizioni: ogni documento riceve 1 / (k + rank) in ciascuna lista, e tu sommi questi contributi. Un documento ben posizionato ovunque batte così un documento eccellente in una sola 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
)
La costante k, convenzionalmente impostata a 60 secondo la letteratura, smorza il divario tra le prime posizioni: senza di essa, la prima posizione peserebbe il doppio della seconda, rendendo la fusione troppo sensibile a piccole differenze di classifica.
Pipeline ibrida completa
La classe seguente mantiene entrambi gli indici in parallelo sullo stesso corpus, esegue entrambe le ricerche per ogni query e fonde le classifiche. Restituisce anche i punteggi individuali, un dettaglio prezioso durante la messa a punto, poiché il loro confronto mostra quale motore ha trainato un dato risultato.
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']}")
Su questo corpus di quattro documenti, l’articolo «nginx error 503» domina la classifica lessicale, mentre «web server issues» domina quella semantica; la fusione porta entrambi nei primi tre, risultato che nessun metodo avrebbe raggiunto da solo.
Ricerca ibrida nativa in Weaviate
Se usi già Weaviate, non devi scrivere tutto questo: il database integra la fusione e la espone in un’unica query, con un parametro alpha che bilancia i due motori: 0 per puramente lessicale, 1 per puramente semantico.
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']}")
Un alpha di 0,7 è un punto di partenza ragionevole, ma non è universale: un corpus ricco di riferimenti tecnici e codici di errore beneficia di una discesa verso 0,5, mentre una knowledge base scritta in linguaggio naturale può gestire 0,8. Regola questo cursore solo con un set di valutazione davanti a te: è esattamente l’argomento della prossima lezione.
Punti chiave
- La ricerca ibrida combina semantica (significato) e lessicale (parole esatte)
- La Reciprocal Rank Fusion (RRF) fonde efficacemente le classifiche
- Il parametro
alphacontrolla l’equilibrio tra i due approcci - Weaviate offre la ricerca ibrida nativamente