Indeksér et dokumentkorpus
På denne side
Mål
- Opbyg et komplet semantisk søgeindeks
- Håndtér forskellige dokumentformater (tekst, PDF, Markdown)
- Opdater indekset inkrementelt
Arkitekturen for et semantisk indeks
Et semantisk indeks hviler på tre elementer, der skal holdes synkroniserede: de originale dokumenter gemt med deres metadata, de embeddings beregnet ud fra deres tekst, og det mapping, der forbinder hver vektor med dens kildedokument. Dette tredje led er det mest skrøbelige – det er næsten altid her, indeks bliver korrupte, når en sletning flytter indekser på den ene side, men ikke den anden.
Klassen Document nedenfor tilføjer et MD5-hash, der beregnes automatisk ved oprettelse. Vi bruger det senere til at opdage, hvad der allerede er blevet indekséret.
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()
Indekseringspipeline
Trin 1: Indlæs dokumenter
Indlæsningen afhænger af formatet, og formatet bestemmer granulariteten. En almindelig tekstfil bliver til ét enkelt dokument; en Markdown-fil indeholder derimod ofte flere forskellige emner, og at indeksere den som én blok ville drukne hvert emne i gennemsnittet af de andre. Den anden loader splitter derfor på overskrifter på niveau 2 og injicerer afsnittets titel tilbage i den indeksérede tekst – dette er berigelsesteknikken, der blev dækket i lektion 3.
from pathlib import Path
def charger_fichiers_texte(dossier: str) -> list[Document]:
"""Indlæs alle tekstfiler fra en mappe."""
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]:
"""Indlæs Markdown-filer, opdelt efter sektioner."""
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
Trin 2: Opbyg indekset
Klassen IndexSemantique samler batch-konstruktion, søgning baseret på tærskelværdier og persistens på disk. Parameteren seuil (tærskel) i metoden rechercher fortjener opmærksomhed: uden den vil en forespørgsel, der er irrelevant, stadig returnere de fem mindst dårlige dokumenter med scorer omkring 0,15, som en naiv caller vil behandle som gyldige svar. Ved at filtrere alt under en bundgrænse kan du ærligt svare: „Jeg fandt intet.”
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):
"""Opbyg indekset fra en liste over dokumenter."""
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]:
"""Søg efter de k mest relevante dokumenter."""
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):
"""Gem indekset på 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):
"""Indlæs et indeks fra 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
]
Metoderne sauvegarder og charger skriver to filer, der deler samme præfiks. Behandl dem som et uadskilleligt par: at kopiere den ene uden den anden eller gendanne en delvis backup producerer et indeks, hvor vektorerne ikke længere matcher dokumenterne – en stille fejl, der kun viser sig som absurde resultater.
Inkrementelle opdateringer
Et korpus udvikler sig: tre dokumenter ændret om mandagen, ti tilføjet om onsdagen. At genberegne femten tusind vektorer for hver ændring spilder tid og penge. Her kommer MD5-hashet ind i billedet: det identificerer indholdet, ikke filen, så et omdøbt, men uændret dokument bliver ikke genindekseret, mens et ændret dokument vil producere et andet hash.
def mettre_a_jour(self, nouveaux_docs: list[Document]):
"""Tilføj dokumenter til det eksisterende indeks."""
# Filtrer allerede indeksérede dokumenter fra
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 stabler de nye vektorer under de gamle i samme rækkefølge som extend på dokumentlisten: denne symmetri bevarer mappinget. Bemærk dog begrænsningen ved denne implementering – den tilføjer, men sletter eller erstatter ikke. Et ændret dokument ender derfor med at være til stede to gange, i sin gamle og nye version. Håndtering af sletninger kræver fjernelse af den tilsvarende række fra matricen, en dyr operation i NumPy, og dette er en af grundene til, at teams presses mod en egentlig vektordatabase.
End-to-end brug
End-to-end tager opbygning af et indeks over dokumentation kun få linjer.
# Opret og udfyld indekset
index = IndexSemantique()
docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")
index.construire(docs)
index.sauvegarder("mon_index")
# Søg
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ør det på din egen dokumentation og stil tre spørgsmål, hvis svar du kender. Hvis det rigtige dokument ikke rangerer som nummer ét, er synderen næsten altid chunking – sektioner der er for lange, eller titler der ikke er genindsat – snarere end embedding-modellen.
Vigtige pointer
- Et semantisk indeks forbinder dokumenter, embeddings og metadata
- Indlæs dokumenter fra forskellige formater (tekst, Markdown osv.)
- Opbyg indekset i batches for at håndtere store korpusser
- Gem og opdater inkrementelt for at undgå at genberegne alt