Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Hybride zoekopdracht (semantisch + lexicaal)

Les 9 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Doelstellingen
  2. Het probleem: geen enkele aanpak is perfect
  3. Lexicaal zoeken met BM25
  4. Reciprocal Rank Fusion (RRF)
  5. Volledige hybride pipeline
  6. Native hybride zoekopdracht in Weaviate
  7. Belangrijkste punten

Doelstellingen

  • Begrijpen waarom het combineren van semantisch en lexicaal zoeken belangrijk is
  • Hybride zoeken implementeren met Reciprocal Rank Fusion
  • Hybride zoeken toepassen in vector databases

Het probleem: geen enkele aanpak is perfect

Semantisch zoeken blinkt uit in het vinden van synoniemen, maar mist soms specifieke technische termen; lexicaal zoeken doet precies het omgekeerde. Beschouw de query van een systeembeheerder: “nginx error 503”, en observeer hoe beide engines reageren op een technische documentatiebasis.

# 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 ✅

Semantisch zoeken begrijpt dat dit verwijst naar een serverincident en toont algemene artikelen, maar het nummer 503 ontgaat het model: voor een embedding-model zijn 503 en 504 slechts twee getallen van drie cijfers, semantisch dicht bij elkaar, ook al duiden ze op verschillende storingen. Lexicaal zoeken haalt de exacte code op, maar mist het artikel over time-outs van reverse proxies, wat vaak de oorzaak beschrijft. Geen enkele methode levert alleen de juiste resultatenpagina; hun combinatie wel.

Lexicaal zoeken met BM25

BM25 is het standaardalgoritme voor trefwoordzoeken. Het weegt elke term op basis van de zeldzaamheid in de corpus en de frequentie in het document, waardoor discriminerende termen zoals “503” of “nginx” natuurlijk naar boven komen. U moet het echter voeden met schone tokens: de tokenisatiefunctie zet tekst om in kleine letters, haalt woorden eruit en verwijdert Franse stopwoorden, die geen relevantiesignaal toevoegen.

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)

Nu moet u de twee ranglijsten combineren, wat lastiger is dan het lijkt: een cosinus-score ligt tussen 0 en 1, terwijl een BM25-score geen bovengrens heeft. Ze direct optellen zou ervoor zorgen dat BM25 het semantische signaal overstemt. RRF omzeilt dit door ruwe scores te negeren en alleen rangen te behouden: elk document ontvangt 1 / (k + rank) in elke lijst, en u telt deze bijdragen op. Een document dat overal goed scoort, verslaat zo een document dat slechts in één lijst uitblinkt.

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
    )

De constante k, conventioneel ingesteld op 60 op basis van literatuur, dempt het verschil tussen de bovenste posities: zonder deze zou de eerste rang tweemaal zo veel wegen als de tweede, waardoor de fusie te gevoelig wordt voor kleine rangverschillen.

Volledige hybride pipeline

De onderstaande klasse onderhoudt beide indexen parallel op dezelfde corpus, voert bij elke query beide zoekopdrachten uit en fuseert de ranglijsten. Het retourneert ook individuele scores – een waardevol detail tijdens het afstemmen, omdat vergelijken laat zien welke engine een bepaald resultaat heeft gedragen.

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']}")

Op deze corpus van vier documenten domineert het artikel “nginx error 503” de lexicale ranglijst, terwijl “web server issues” de semantische domineert; fusie brengt beide in de top drie, iets wat geen enkele methode alleen zou bereiken.

Native hybride zoekopdracht in Weaviate

Als u Weaviate al gebruikt, hoeft u dit niet allemaal zelf te schrijven: de database integreert fusie en stelt dit bloot in één enkele query, met een alpha-parameter die de twee engines balanceert – 0 voor puur lexicaal, 1 voor puur semantisch.

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']}")

Een alpha van 0,7 is een redelijk startpunt, maar dit is niet universeel: een corpus rijk aan technische referenties en foutcodes heeft baat bij een verlaging naar 0,5, terwijl een kennisbank in heldere taal 0,8 aankan. Stem deze schuifregelaar alleen af met een evaluatieset voor u – dat is precies het onderwerp van de volgende les.

Belangrijkste punten

  • Hybride zoeken combineert semantisch (betekenis) en lexicaal (exacte woorden)
  • Reciprocal Rank Fusion (RRF) voegt ranglijsten effectief samen
  • De alpha-parameter regelt de balans tussen de twee benaderingen
  • Weaviate biedt hybride zoeken native aan