Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Indexovanie korpusu dokumentov

Lekcia 7 z 22 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Ciele
  2. Architektúra sémantického indexu
  3. Pipeline indexovania
  4. Prírastkové aktualizácie
  5. Kompletné použitie
  6. Kľúčové poznatky

Ciele

  • Vytvoriť kompletný index pre sémantické vyhľadávanie
  • Spracovať rôzne formáty dokumentov (text, PDF, Markdown)
  • Prírastkovo aktualizovať index

Architektúra sémantického indexu

Sémantický index stojí na troch pilieroch, ktoré musia zostať v synchronizácii: pôvodné dokumenty uložené spolu s metadátami, vektory (embeddings) vypočítané z ich textu a mapovanie, ktoré spája každý vektor so zdrojovým dokumentom. Práve táto tretia zložka je najkrehkejšia – tu sa indexy najčastejšie poškodia, keď napríklad vymazanie posunie indexy na jednej strane, ale nie na druhej.

Nižšie uvedená trieda Document pridáva MD5 hash, ktorý sa automaticky vypočíta pri vytvorení. Neskôr ho využijeme na detekciu toho, čo už bolo indexované.

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()

Pipeline indexovania

Krok 1: Načítanie dokumentov

Načítanie závisí od formátu a formát určuje granularitu. Obyčajný textový súbor sa stane jedným dokumentom; súbor Markdown však často obsahuje niekoľko odlišných tém a jeho indexovanie ako jedného bloku by utopilo každú tému v priemere ostatných. Druhý načítavač preto rozdeľuje obsah podľa nadpisov úrovne 2 a vracia názov sekcie späť do indexovaného textu – toto je technika obohatenia, ktorú sme prebrali v lekcii 3.

from pathlib import Path

def charger_fichiers_texte(dossier: str) -> list[Document]:
    """Načíta všetky textové súbory z priečinka."""
    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]:
    """Načíta súbory Markdown a rozdelí ich podľa sekcií."""
    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

Krok 2: Vytvorenie indexu

Trieda IndexSemantique spája dávkové vytváranie, vyhľadávanie na základe prahu a ukladanie na disk. Parameter seuil (prah) v metóde rechercher si zaslúži pozornosť: bez neho by dotaz mimo témy stále vrátil päť „najmenej zlých“ dokumentov so skóre okolo 0,15, ktoré by naivný volajúci považoval za platné odpovede. Odfiltrovanie všetkého pod určitou hranicou ti umožní úprimne odpovedať: „Nenašiel som nič.“

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):
        """Vytvorí index zo zoznamu dokumentov."""
        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]:
        """Vyhľadá k najrelevantnejších dokumentov."""
        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):
        """Uloží index na 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):
        """Načíta index z disku."""
        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
        ]

Metódy sauvegarder a charger zapisujú dva súbory zdieľajúce rovnakú predponu. Ber ich ako neoddeliteľný pár: skopírovanie jedného bez druhého alebo obnovenie čiastočnej zálohy vytvorí index, kde vektory už nezodpovedajú dokumentom – tichá chyba, ktorá sa prejaví až absurdnými výsledkami.

Prírastkové aktualizácie

Korpus sa vyvíja: tri dokumenty upravené v pondelok, desať pridaných v stredu. Prepočítavanie pätnástich tisíc vektorov pri každej zmene plytvá časom aj peniazmi. Tu prichádza na rad MD5 hash: identifikuje obsah, nie súbor, takže premenovaný, ale nezmenený dokument sa nebude znovu indexovať, zatiaľ čo upravený dokument vyprodukuje iný hash.

def mettre_a_jour(self, nouveaux_docs: list[Document]):
    """Pridá dokumenty do existujúceho indexu."""
    # Odfiltruje už indexované dokumenty
    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)}")

Funkcia np.vstack uloží nové vektory pod staré v rovnakom poradí, ako extend pracuje so zoznamom dokumentov: táto symetria zachováva mapovanie. Všimni si však obmedzenie tejto implementácie – pridáva, ale nemaže ani nenahrádza. Upravený dokument sa tak v indexe objaví dvakrát, v starej aj novej verzii. Riešenie vymazania vyžaduje odstránenie zodpovedajúceho riadku z matice, čo je v NumPy nákladná operácia, a to je jeden z dôvodov, prečo tímy smerujú k použitiu skutočnej vektorovej databázy.

Kompletné použitie

Od začiatku do konca trvá vytvorenie indexu nad dokumentáciou len niekoľko riadkov.

# Vytvorenie a naplnenie indexu
index = IndexSemantique()

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

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

# Vyhľadávanie
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]}...")

Spusť to na vlastnej dokumentácii a polož tri otázky, ktorých odpovede poznáš. Ak správny dokument nie je na prvom mieste, vinníkom je takmer vždy chunking (rozkuskovanie) – sekcie príliš dlhé alebo názvy neboli vrátené späť – skôr než samotný model embeddings.

Kľúčové poznatky

  • Sémantický index prepája dokumenty, vektory (embeddings) a metadáta
  • Načítavaj dokumenty z rôznych formátov (text, Markdown atď.)
  • Buduj index v dávkach, aby si zvládol veľké korpusy
  • Ukladaj a aktualizuj prírastkovo, aby sa predišlo prepočítavaniu všetkého