Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Indeksér et dokumentkorpus

Lektion 7 af 22 Opdateret 29. juli 2026 Udvikler
På denne side
  1. Mål
  2. Arkitekturen for et semantisk indeks
  3. Indekseringspipeline
  4. Inkrementelle opdateringer
  5. End-to-end brug
  6. Vigtige pointer

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