Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Hübriidotsing (semantiline + leksikaalne)

Õppetund 9 / 22 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Eesmärgid
  2. Probleem: ükski lähenemine pole täiuslik
  3. Leksikaalne otsing BM25-ga
  4. Vastastikune auastme liitmine (RRF)
  5. Täielik hübriidtorustik
  6. Native hübriidotsing Weaviates
  7. Peamised punktid

Eesmärgid

  • Mõista, miks on oluline kombineerida semantilist ja leksikaalset otsingut
  • Rakendada hübriidotsingut, kasutades vastastikuse auastme liitmist (Reciprocal Rank Fusion)
  • Kasutada hübriidotsingut vektorandmebaasides

Probleem: ükski lähenemine pole täiuslik

Semantiline otsing tuleb suurepäraselt toime sünonüümidega, kuid võib mööda vaadata täpseid tehnilisi termineid; leksikaalne otsing teeb täpselt vastupidist. Vaatle süsteemiadministraatori päringut „nginx error 503“ ja jälgi, kuidas mõlemad mootorid käituvad tehnilise dokumentatsiooni baasi vastu.

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

Semantiline otsing mõistab, et tegemist on serveri intsidentiga, ja toob esile üldised artiklid, kuid number 503 jääb tal märkamata: manustamismudeli jaoks on 503 ja 504 lihtsalt kaks kolmekohalist numbrit, mis on semantiliselt lähedased, kuigi tähistavad erinevaid katkestusi. Leksikaalne otsing toob täpse koodi, kuid jätab kõrvale artikli pöördproksi aegumiste kohta, mis kirjeldab sageli algpõhjust. Kumbki meetod üksi ei tagasta õiget tulemuste lehte; nende ühendus aga jah.

Leksikaalne otsing BM25-ga

BM25 on märksõnaotsingu standardne algoritm. See kaalub iga terminit lähtuvalt selle haruldusest korpuses ja sagedusest dokumendis, tuues loomulikult esile eristavad terminid nagu „503“ või „nginx“. Siiski pead sellele sisendama puhtaid tokeneid: tokeniseerimisfunktsioon teisendab teksti väiketähtedeks, eraldab sõnad ja eemaldab prantsuse keele stoppsõnad, mis ei lisa asjakohasussignaali.

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

Vastastikune auastme liitmine (RRF)

Nüüd pead need kaks järjestust ühendama, mis on keerulisem, kui esmapilgul tundub: koosinusskoor jääb vahemikku 0–1, samas kui BM25 skooril ei ole ülemist piiri. Nende otsene liitmine võimaldaks BM25-l semantilise signaali üle kaaluda. RRF lahendab selle, ignoreerides toorskoore ja hoides alles ainult auastmeid: iga dokument saab igas nimekirjas väärtuse 1 / (k + rank) ja need panused liidetakse. Dokument, mis on kõikjal hästi järjestatud, lööb seega dokumendi, mis paistab silma vaid ühes nimekirjas.

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
    )

Konstant k, mis on kirjanduse põhjal tavapäraselt seatud väärtusele 60, vähendab tipppositsioonide vahelist lõhet: ilma selleta kaaluks esimene auaste teist korda rohkem kui teine, muutes liitmise liiga tundlikuks väikeste järjestuserinevuste suhtes.

Täielik hübriidtorustik

Allpool olev klass haldab mõlemat indeksit paralleelselt sama korpuse üle, käivitab iga päringu korral mõlemad otsingud ja liidab järjestused. See tagastab ka individuaalsed skoorid – väärtuslik detail häälestamisel, kuna nende võrdlemine näitab, milline mootor konkreetse tulemuse tõi.

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

Selles nelja dokumendi korpuses domineerib artikkel „nginx error 503“ leksikaalses järjestuses, samas kui „web server issues“ domineerib semantilises; liitmine toob mõlemad esikolmikusse, mida kumbki meetod üksi ei saavutaks.

Native hübriidotsing Weaviates

Kui kasutad juba Weaviat, ei pea sa kõike seda ise kirjutama: andmebaas integreerib liitmise ja exposeerib seda ühes päringus, kasutades parameetrit alpha, mis tasakaalustab kahte mootorit – 0 tähendab puhast leksikaalset ja 1 puhast semantilist otsingut.

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

Väärtus alpha = 0,7 on mõistlik alguspunkt, kuid see ei ole universaalne: korpuse puhul, mis on rikas tehniliste viidete ja veakoodide poolest, tasub liikuda pigem 0,5 poole, samas kui lihtsas keeles kirjutatud teadmiste baas talub väärtust 0,8. Häälesta seda liugurit ainult siis, kui sul on ees hindamiskomplekt – see on täpselt järgmise tunni teema.

Peamised punktid

  • Hübriidotsing ühendab semantilise (tähendus) ja leksikaalse (täpsed sõnad) lähenemise
  • Vastastikune auastme liitmine (RRF) ühendab järjestused tõhusalt
  • Parameeter alpha kontrollib kahe lähenemise vahelist tasakaalu
  • Weaviate pakub hübriidotsingut loomupäraselt