Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Egy dokumentumkorpusz indexelése

7. lecke 22 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Célok
  2. Egy szemantikus index architektúrája
  3. Indexelési folyamat
  4. Inkrementális frissítések
  5. End-to-end használat
  6. Főbb megállapítások

Célok

  • Teljes szemantikus keresési index felépítése
  • Különböző dokumentumformátumok kezelése (szöveg, PDF, Markdown)
  • Az index inkrementális frissítése

Egy szemantikus index architektúrája

Egy szemantikus index három elemen alapul, amelyeknek szinkronban kell maradniuk: az eredeti dokumentumok tárolása metaadatokkal, a szövegeikből számított beágyazások (embeddings), valamint a leképezés, amely minden vektort a forrásdokumentumához köt. Ez a harmadik elem a legkényesebb – szinte mindig itt sérülnek meg az indexek, amikor egy törlés eltolja az indexeket az egyik oldalon, de a másikon nem.

Az alábbi Document osztály egy MD5-hash-t ad hozzá, amely automatikusan számítódik létrehozáskor. Később ezt használjuk annak észlelésére, mit indexeltünk már.

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

Indexelési folyamat

1. lépés: Dokumentumok betöltése

A betöltés a formátumtól függ, a formátum pedig meghatározza a szemcsézettséget. Egy egyszerű szövegfájl egyetlen dokumentummá válik; egy Markdown-fájl viszont gyakran több különálló témát tartalmaz, és egyben történő indexelésük elmosná az egyes témákat a többi átlagában. A második betöltő ezért a 2. szintű címsorok szerint darabolja fel a fájlt, és visszailleszti a szakasz címét az indexelt szövegbe – ez az enrichment technika, amelyet a 3. leckében tárgyaltunk.

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. lépés: Az index felépítése

Az IndexSemantique osztály egyesíti a kötegelt felépítést, a küszöbértéken alapuló keresést és a lemezen történő tartósítást. A rechercher metódus seuil (küszöbérték) paramétere figyelmet érdemel: enélkül egy témán kívüli lekérdezés is visszaadja az öt legkevésbé rossz dokumentumot, körülbelül 0,15-ös pontszámokkal, amelyeket egy naív hívó érvényes válaszként kezel. A küszöbérték alatti találatok kiszűrése lehetővé teszi, hogy őszintén azt válaszd: „Nem találtam semmit.“

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
        ]

A sauvegarder és charger metódusok két, azonos előtaggal rendelkező fájlt írnak. Kezeld őket elválaszthatatlan párként: ha csak az egyiket másolod le, vagy hiányos biztonsági másolatot állítasz helyre, olyan indexet kapsz, ahol a vektorok már nem egyeznek a dokumentumokkal – ez egy csendes hiba, amely csak abszurd eredményekben mutatkozik meg.

Inkrementális frissítések

Egy korpusz fejlődik: hétfőn három dokumentum módosul, szerdán tíz új kerül hozzá. Minden egyes változásnál tizenötezer vektor újraszámítása idő- és pénzpazarlás. Itt jön képbe az MD5-hash: ez a tartalmat azonosítja, nem a fájlt, így egy átnevezett, de változatlan dokumentum nem kerül újraindexelésre, míg egy módosított dokumentum más hash-t generál.

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

A np.vstack az új vektorokat a régiek alá illeszti, ugyanabban a sorrendben, ahogy a dokumentumlista extend metódusa működik: ez a szimmetria őrzi meg a leképezést. Vegyél azonban tudomást ennek a megvalósításnak a korlátjáról – csak hozzáad, de nem töröl vagy cserél le. Egy módosított dokumentum így kétszer lesz jelen: a régi és az új verziójában is. A törlések kezelése megköveteli a megfelelő sor eltávolítását a mátrixból, ami NumPy-ban költséges művelet, és ez az egyik oka annak, amiért a csapatok megfelelő vektoradatbázis felé mozdulnak.

End-to-end használat

Végigvezetve az egész folyamatot, egy dokumentáció feletti index felépítése mindössze néhány sorba kerül.

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

Futtasd le a saját dokumentációdon, és tegyél fel három kérdést, amelyekre ismered a választ. Ha a helyes dokumentum nem az első helyen szerepel, az bűnös szinte mindig a darabolás (chunking) – túl hosszú szakaszok vagy be nem illesztett címek –, nem pedig a beágyazási modell.

Főbb megállapítások

  • Egy szemantikus index összeköti a dokumentumokat, a beágyazásokat és a metaadatokat
  • Dokumentumok betöltése különböző formátumokból (szöveg, Markdown stb.)
  • Az index kötegekben történő felépítése nagy korpuszok kezeléséhez
  • Mentés és inkrementális frissítés a mindent újra kiszámítás elkerülése érdekében