Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Hakuhaku: hybridi (semanttinen + leksikaalinen)

Oppitunti 9 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Ongelma: mikään yksittäinen lähestymistapa ei ole täydellinen
  3. Leksikaalinen haku BM25:llä
  4. Käänteinen arvojoukkosulautuma (RRF)
  5. Täydellinen hybridi-putki
  6. Natiivi hybridi-haku Weaviatessa
  7. Keskeiset asiat

Tavoitteet

  • Ymmärrä, miksi semanttisen ja leksikaalisen haun yhdistäminen on tärkeää
  • Toteuta hybridi-haku käyttämällä käänteistä arvojoukkosulautumaa (Reciprocal Rank Fusion)
  • Käytä hybridi-hakua vektoritietokannoissa

Ongelma: mikään yksittäinen lähestymistapa ei ole täydellinen

Semanttinen haku loistaa synonyymien käsittelyssä, mutta voi missata tarkat tekniset termit; leksikaalinen haku toimii täysin päinvastoin. Tarkastellaan järjestelmänvalvojan kyselyä “nginx error 503” ja havainnoidaan, miten molemmat moottorit käyttäytyvät teknistä dokumentaatiota vasten.

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

Semanttinen haku ymmärtää, että kyseessä on palvelinincidentti, ja nostaa esiin yleisiä artikkeleita, mutta numero 503 karkaa siltä: upotusmallille 503 ja 504 ovat vain kaksi kolminumeroista lukua, semanttisesti lähellä toisiaan, vaikka ne tarkoittavatkin eri katkoja. Leksikaalinen haku löytää tarkan koodin, mutta missaa artikkelin käänteisen välityspalvelimen aikakatkaisuista (reverse proxy timeouts), jotka usein kuvaavat perussyytä. Kumpikaan menetelmä yksinään ei palauta oikeaa tulossivua; niiden yhdistelmä tekee sen.

Leksikaalinen haku BM25:llä

BM25 on vakioalgoritmi avainsanahakuun. Se painottaa jokaista termiä sen harvinaisuuden perusteella kokoelmassa ja sen esiintymistiheyden perusteella dokumentissa, tuoden luonnostaan esiin erottavia termejä kuten “503” tai “nginx”. Sinun on kuitenkin syötettävä sille siistejä tokeneita: tokenointifunktio muuttaa tekstin pienkirjaimiksi, erottaa sanat ja poistaa ranskankieliset stop-sanat, jotka eivät lisää relevanssisignaalia.

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

Käänteinen arvojoukkosulautuma (RRF)

Nyt sinun on yhdistettävä nämä kaksi sijoituslistaa, mikä on hankalampaa kuin miltä näyttää: kosinuspisteet ovat välillä 0–1, kun taas BM25-pisteillä ei ole ylärajaa. Niiden suora yhteenlasku antaisi BM25:n tukahduttaa semanttisen signaalin. RRF kiertää tämän jättämällä raakapisteet huomiotta ja säilyttämällä vain sijoitukset: jokainen dokumentti saa arvoksi 1 / (k + rank) kummassakin listassa, ja nämä osuudet lasketaan yhteen. Dokumentti, joka sijoittuu hyvin kaikkialla, voittaa siten dokumentin, joka loistaa vain yhdessä listassa.

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
    )

Vakio k, joka kirjallisuuden perusteella asetetaan conventionaalisesti arvoon 60, vaimentaa eroa kärkisijoitusten välillä: ilman sitä ensimmäinen sijoitus painaisi kaksi kertaa niin paljon kuin toinen, mikä tekisi sulautumisesta liian herkän pienille sijoituseroille.

Täydellinen hybridi-putki

Alla oleva luokka ylläpitää molempia indeksejä rinnakkain samalle kokoelmalle, suorittaa molemmat haut jokaiselle kyselylle ja sulauttaa sijoituslistat. Se palauttaa myös yksittäiset pisteet – arvokas yksityiskohta viritysvaiheessa, sillä niiden vertailu näyttää, kumpi moottori kantoi tietyn tuloksen.

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

Tässä neljän dokumentin kokoelmassa artikkeli “nginx error 503” dominoi leksikaalista sijoituslistaa, kun taas “web server issues” dominoi semanttista listaa; sulautuma tuo molemmat kolmen parhaan joukkoon, mitä kumpikaan menetelmä ei saavuttaisi yksinään.

Natiivi hybridi-haku Weaviatessa

Jos käytät jo Weaveatea, sinun ei tarvitse kirjoittaa kaikkea tätä: tietokanta integroi sulautuman ja tarjoaa sen yhdellä kyselyllä, käyttäen alpha-parametria, joka tasapainottaa kahta moottoria – 0 puhtaasti leksikaaliselle ja 1 puhtaasti semanttiselle haulle.

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

Arvo alpha = 0,7 on kohtuullinen lähtökohta, mutta se ei ole universaali: kokoelma, jossa on runsaasti teknisiä viittauksia ja virhekoodeja, hyötyy arvon laskemisesta kohti 0,5:ttä, kun taas selkeällä kielellä kirjoitettu tietopankki kestää arvon 0,8. Virittä tätä liukusäädintä vain arviointiaineiston edessä – tämä on juuri seuraavan oppitunnin aihe.

Keskeiset asiat

  • Hybridi-haku yhdistää semanttisen (merkitys) ja leksikaalisen (tarkat sanat) haun
  • Käänteinen arvojoukkosulautuma (RRF) yhdistää sijoituslistat tehokkaasti
  • Parametri alpha ohjaa tasapainoa kahden lähestymistavan välillä
  • Weaviate tarjoaa hybridi-haun natiivisti