Indexeren van een documentencorpus
Op deze pagina
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