Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Indexeren van een documentencorpus

Les 7 van 22 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Doelstellingen
  2. Architectuur van een semantische index
  3. Indexeringspijplijn
  4. Incrementele updates
  5. End-to-end gebruik
  6. Belangrijkste punten

Doelstellingen

  • Een volledige semantische zoekindex opbouwen
  • Verschillende documentformaten verwerken (tekst, PDF, Markdown)
  • De index incrementeel bijwerken

Architectuur van een semantische index

Een semantische index berust op drie elementen die synchroon moeten blijven: de originele documenten opgeslagen met hun metadata, de embeddings berekend op basis van de tekst, en de koppeling die elke vector verbindt met het brondocument. Dit derde onderdeel is het meest kwetsbaar; hier raken indexen bijna altijd beschadigd, bijvoorbeeld wanneer een verwijdering de indices aan de ene kant verschuift maar niet aan de andere.

De onderstaande Document-klasse voegt een MD5-hash toe die automatisch bij het aanmaken wordt berekend. We gebruiken deze later om te detecteren wat al geïndexeerd is.

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

Indexeringspijplijn

Stap 1: Documenten laden

Het laden hangt af van het formaat, en het formaat bepaalt de granulariteit. Een plat tekstbestand wordt één document; een Markdown-bestand bevat daarentegen vaak meerdere verschillende onderwerpen, en het als één blok indexeren zou elk onderwerp verdrinken in het gemiddelde van de anderen. De tweede lader splitst daarom op koppen van niveau 2 en voegt de sectietitel opnieuw toe aan de geïndexeerde tekst; dit is de verrijkingstechniek die aan bod kwam in les 3.

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

Stap 2: De index opbouwen

De klasse IndexSemantique brengt batchconstructie, zoeken op basis van een drempelwaarde en persistentie op schijf samen. De parameter seuil (drempelwaarde) in de methode rechercher verdient aandacht: zonder deze parameter retourneert een query die naast het onderwerp ligt toch de vijf minst slechte documenten, met scores rond de 0,15 die een naïeve aanroeper als geldige antwoorden zal behandelen. Alles filteren wat onder een minimumscore valt, stelt u in staat om eerlijk te antwoorden: “Ik heb niets gevonden.”

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
        ]

De methoden sauvegarder en charger schrijven twee bestanden die hetzelfde voorvoegsel delen. Beschouw ze als een ondeelbaar paar: het kopiëren van het ene zonder het andere, of het herstellen van een gedeeltelijke back-up, produceert een index waarbij de vectoren niet langer overeenkomen met de documenten; een stille fout die zich pas zal manifesteren als absurde resultaten.

Incrementele updates

Een corpus evolueert: drie documenten gewijzigd op maandag, tien toegevoegd op woensdag. Het opnieuw berekenen van vijftienduizend vectoren voor elke wijziging is tijd- en geldverspilling. Hier komt de MD5-hash van pas: deze identificeert de inhoud, niet het bestand, zodat een hernoemd maar ongewijzigd document niet opnieuw wordt geïndexeerd, terwijl een gewijzigd document een andere hash produceert.

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

De np.vstack stapelt de nieuwe vectoren onder de oude in dezelfde volgorde als de extend op de documentenlijst: deze symmetrie behoudt de koppeling. Merk echter de beperking van deze implementatie op: deze voegt toe, maar verwijdert of vervangt niet. Een gewijzigd document staat daardoor twee keer in de index, in zijn oude en nieuwe versie. Het afhandelen van verwijderingen vereist het verwijderen van de overeenkomstige rij uit de matrix, een dure operatie in NumPy, en dit is een van de redenen waarom teams worden geduwd naar een echte vector database.

End-to-end gebruik

Van begin tot eind kost het opbouwen van een index over documentatie slechts een paar regels code.

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

Voer dit uit op uw eigen documentatie en stel drie vragen waarvan u de antwoorden kent. Als het juiste document niet als eerste wordt gerangschikt, ligt de oorzaak bijna altijd bij de chunking (secties die te lang zijn of titels die niet opnieuw zijn ingevoegd) en niet bij het embedding-model.

Belangrijkste punten

  • Een semantische index koppelt documenten, embeddings en metadata
  • Laad documenten uit verschillende formaten (tekst, Markdown, enz.)
  • Bouw de index in batches op om grote corpusssen te verwerken
  • Sla op en werk incrementeel bij om herberekening van alles te voorkomen