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

Indekseeri dokumentide kogu

Õppetund 7 / 22 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Eesmärgid
  2. Semantilise indeksi arhitektuur
  3. Indekseerimise torustik
  4. Inkrementaalsed uuendused
  5. Kasutamine otsast otsani
  6. Peamised punktid

Eesmärgid

  • Ehita terviklik semantiline otsinguindeks
  • Käitle erinevaid dokumendivorminguid (tekst, PDF, Markdown)
  • Uuenda indeksit inkrementaalselt

Semantilise indeksi arhitektuur

Semantiline indeks tugineb kolmele elemendile, mis peavad jääma sünkrooni: algupärased dokumendid koos oma metaandmetega, nende tekstist arvutatud manused (embeddings) ja seos, mis ühendab iga vektori selle allikadokumendiga. See kolmas osa on kõige habras – just siin lähevad indeksid kõige sagedamini katki, kui kustutamine nihutab indekseid ühel pool, kuid mitte teisel.

Allpool olev Document klass lisab MD5 räsi, mis arvutatakse loomisel automaatselt. Kasutame seda hiljem tuvastamaks, mis on juba indekseeritud.

from dataclasses import dataclass, field
from openai import OpenAI
import numpy as np
import json
import hashlib

@dataclass
class Document:
    id: str
    texte: str
    metadata: dict = field(default_factory=dict)
    hash: str = ""

    def __post_init__(self):
        self.hash = hashlib.md5(self.texte.encode()).hexdigest()

Indekseerimise torustik

1. samm: laadi dokumendid

Laadimine sõltub vormingust ja vorming määrab granulaarsuse. Lihtne tekstifail muutub üheks dokumendiks; Markdown-fail sisaldab aga sageli mitut erinevat teemat ja selle indekseerimine ühe plokina uputaks iga teema teiste keskmisesse. Teine laadija jagab faili seetõttu teise taseme pealkirjade järgi ja süstib jaotise pealkirja indekseeritavasse teksti tagasi – see on rikastamise tehnika, mida käsitlesime 3. tunnis.

from pathlib import Path

def charger_fichiers_texte(dossier: str) -> list[Document]:
    """Load all text files from a folder."""
    documents = []
    for fichier in Path(dossier).rglob("*.txt"):
        contenu = fichier.read_text(encoding="utf-8").strip()
        if contenu:
            documents.append(Document(
                id=fichier.stem,
                texte=contenu,
                metadata={
                    "fichier": str(fichier),
                    "type": "txt",
                    "taille": len(contenu)
                }
            ))
    return documents

def charger_fichiers_markdown(dossier: str) -> list[Document]:
    """Load Markdown files, splitting by sections."""
    documents = []
    for fichier in Path(dossier).rglob("*.md"):
        contenu = fichier.read_text(encoding="utf-8")
        sections = contenu.split("\n## ")

        for i, section in enumerate(sections):
            if not section.strip():
                continue
            titre = section.split("\n")[0].strip("# ")
            corps = "\n".join(section.split("\n")[1:]).strip()
            if corps:
                documents.append(Document(
                    id=f"{fichier.stem}_section_{i}",
                    texte=f"{titre}\n\n{corps}",
                    metadata={
                        "fichier": str(fichier),
                        "section": titre,
                        "type": "markdown"
                    }
                ))
    return documents

2. samm: ehita indeks

Klass IndexSemantique ühendab partiihaaval ehitamise, lävendipõhise otsingu ja püsiva salvestamise kettale. Meetodi rechercher parameeter seuil (lävend) väärib tähelepanu: ilma selleta tagastab teemaväline päring ikkagi viis kõige vähem halba dokumenti, skooridega umbes 0,15, mida naiivne kasutaja käsitleb kehtivate vastustena. Kõigi alla miinimumskoori jäävate tulemuste filtreerimine võimaldab sul ausalt vastata: „Ma ei leidnud midagi.“

class IndexSemantique:
    def __init__(self, model: str = "text-embedding-3-large"):
        self.client = OpenAI()
        self.model = model
        self.documents: list[Document] = []
        self.embeddings: np.ndarray | None = None

    def construire(self, documents: list[Document], batch_size: int = 100):
        """Build the index from a list of documents."""
        self.documents = documents
        textes = [d.texte for d in documents]
        tous_embeddings = []

        for i in range(0, len(textes), batch_size):
            batch = textes[i:i + batch_size]
            response = self.client.embeddings.create(
                input=batch,
                model=self.model
            )
            batch_sorted = sorted(response.data, key=lambda x: x.index)
            tous_embeddings.extend([e.embedding for e in batch_sorted])
            print(f"  Batch {i // batch_size + 1} processed "
                  f"({min(i + batch_size, len(textes))}/{len(textes)})")

        self.embeddings = np.array(tous_embeddings, dtype=np.float32)
        print(f"Index built: {len(self.documents)} documents, "
              f"{self.embeddings.shape[1]} dimensions")

    def rechercher(self, requete: str, k: int = 5,
                   seuil: float = 0.0) -> list[dict]:
        """Search for the k most relevant documents."""
        query_emb = self.client.embeddings.create(
            input=requete,
            model=self.model
        ).data[0].embedding

        scores = self.embeddings @ np.array(query_emb)
        top_indices = np.argsort(scores)[-k:][::-1]

        resultats = []
        for idx in top_indices:
            score = float(scores[idx])
            if score >= seuil:
                doc = self.documents[idx]
                resultats.append({
                    "id": doc.id,
                    "texte": doc.texte[:200],
                    "score": score,
                    "metadata": doc.metadata
                })
        return resultats

    def sauvegarder(self, chemin: str):
        """Save the index to disk."""
        np.save(f"{chemin}_embeddings.npy", self.embeddings)
        docs_serialisables = [
            {"id": d.id, "texte": d.texte,
             "metadata": d.metadata, "hash": d.hash}
            for d in self.documents
        ]
        with open(f"{chemin}_documents.json", "w") as f:
            json.dump(docs_serialisables, f, ensure_ascii=False)

    def charger(self, chemin: str):
        """Load an index from disk."""
        self.embeddings = np.load(f"{chemin}_embeddings.npy")
        with open(f"{chemin}_documents.json") as f:
            docs = json.load(f)
        self.documents = [
            Document(id=d["id"], texte=d["texte"],
                     metadata=d["metadata"])
            for d in docs
        ]

Meetodid sauvegarder ja charger kirjutavad kaks faili, millel on sama eesliide. Kohtle neid lahutamatu paarina: ühe kopieerimine ilma teiseta või osalise varukoopia taastamine tekitab indeksi, kus vektorid ei vasta enam dokumentidele – see on vaikne tõrge, mis avaldub alles absurdsete tulemustena.

Inkrementaalsed uuendused

Dokumentide kogu areneb: kolm dokumenti muudeti esmaspäeval, kümme lisati kolmapäeval. Viieteistkümne tuhande vektori ümberarvutamine iga muudatuse jaoks raiskab aega ja raha. Siin tulebki mängu MD5 räsi: see tuvastab sisu, mitte faili, nii et ümber nimetatud, kuid muutumata dokumenti ei indekseerita uuesti, samas muudetud dokument annab erineva räsi.

def mettre_a_jour(self, nouveaux_docs: list[Document]):
    """Add documents to the existing index."""
    # Filter out already indexed documents
    hashes_existants = {d.hash for d in self.documents}
    docs_a_ajouter = [
        d for d in nouveaux_docs if d.hash not in hashes_existants
    ]

    if not docs_a_ajouter:
        print("No new documents to index")
        return

    textes = [d.texte for d in docs_a_ajouter]
    response = self.client.embeddings.create(
        input=textes,
        model=self.model
    )

    nouveaux_vecteurs = np.array(
        [e.embedding for e in sorted(response.data, key=lambda x: x.index)],
        dtype=np.float32
    )

    self.documents.extend(docs_a_ajouter)
    self.embeddings = np.vstack([self.embeddings, nouveaux_vecteurs])
    print(f"{len(docs_a_ajouter)} documents added. "
          f"Total: {len(self.documents)}")

np.vstack asetab uued vektorid vanade alla samas järjekorras, nagu dokumentide loendis toimub extend: see sümmeetria säilitab vastavuse. Pane tähele aga selle teostuse piirangut – see ainult lisab, kuid ei kustuta ega asenda. Muudetud dokument lõpeb seega topelt: nii vanas kui ka uues versioonis. Kustutamiste käsitlemine nõuab vastava rea eemaldamist maatriksist, mis on NumPys kulukas operatsioon, ja see on üks põhjusi, miks meeskonnad liiguvad korraliku vektorandmebaasi poole.

Kasutamine otsast otsani

Otsast otsani võtab dokumentatsiooni üle indeksi loomine vaid mõned read.

# Create and populate the index
index = IndexSemantique()

docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")

index.construire(docs)
index.sauvegarder("mon_index")

# Search
resultats = index.rechercher("how to configure authentication", k=3)
for r in resultats:
    print(f"[{r['score']:.3f}] {r['id']}")
    print(f"  {r['texte'][:100]}...")

Käivita see oma dokumentatsioonil ja esita kolm küsimust, mille vastuseid sa tead. Kui õige dokument ei ole esikohal, on süüdlane peaaegu alati tükeldamine – jaotised on liiga pikad või pealkirju ei süstitud tagasi – mitte manuste mudel.

Peamised punktid

  • Semantiline indeks seob omavahel dokumendid, manused ja metaandmed
  • Laadi dokumente erinevatest vormingutest (tekst, Markdown jne)
  • Ehita indeks partiihaaval, et hallata suuri kogusid
  • Salvesta ja uuenda inkrementaalselt, et vältida kõige ümberarvutamist