Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Indexera en dokumentsamling

Lektion 7 av 22 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Mål
  2. Arkitektur för ett semantiskt index
  3. Indexeringspipeline
  4. Inkrementella uppdateringar
  5. Användning från början till slut
  6. Viktiga punkter

Mål

  • Bygga ett komplett index för semantisk sökning
  • Hantera olika dokumentformat (text, PDF, Markdown)
  • Uppdatera indexet inkrementellt

Arkitektur för ett semantiskt index

Ett semantiskt index vilar på tre element som måste hållas synkroniserade: originaldokumenten lagrade med sin metadata, de inbäddningar (embeddings) som beräknats från deras text, och mappningen som länkar varje vektor till sitt källdokument. Den tredje delen är den mest ömtåliga – det är nästan alltid här index korrumperas, när en borttagning förskjuter index på ena sidan men inte på den andra.

Klassen Document nedan lägger till en MD5-hash som beräknas automatiskt vid skapandet. Vi kommer att använda den senare för att upptäcka vad som redan har indexerats.

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

Indexeringspipeline

Steg 1: Ladda dokument

Inläsningen beror på formatet, och formatet bestämmer granulariteten. En vanlig textfil blir ett enda dokument; en Markdown-fil innehåller dock ofta flera distinkta ämnen, och att indexera den som ett enda block skulle dränka varje ämne i genomsnittet av de andra. Den andra laddaren delar därför vid rubriker på nivå 2 och injicerar om avsnittstiteln i den indexerade texten – detta är den berikningsteknik som behandlades i lektion 3.

from pathlib import Path

def charger_fichiers_texte(dossier: str) -> list[Document]:
    """Ladda alla textfiler från en mapp."""
    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]:
    """Ladda Markdown-filer, uppdelade efter avsnitt."""
    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

Steg 2: Bygg indexet

Klassen IndexSemantique sammanför batch-konstruktion, tröskelbaserad sökning och persistens till disk. Parametern seuil (tröskel) i metoden rechercher förtjänar uppmärksamhet: utan den returnerar en fråga som är helt vid sidan av ämnet ändå de fem minst dåliga dokumenten, med poäng runt 0,15 som en naiv anropare kommer att behandla som giltiga svar. Att filtrera bort allt under en golvpoäng låter dig ärligt svara: “Jag hittade inget.”

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):
        """Bygg indexet från en lista med dokument."""
        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ök efter de k mest relevanta dokumenten."""
        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):
        """Spara indexet till 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):
        """Ladda ett index från 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
        ]

Metoderna sauvegarder och charger skriver två filer som delar samma prefix. Behandla dem som ett oskiljaktigt par: att kopiera den ena utan den andra, eller att återställa en partiell säkerhetskopia, producerar ett index där vektorerna inte längre matchar dokumenten – ett tyst fel som bara visar sig som absurda resultat.

Inkrementella uppdateringar

En dokumentsamling utvecklas: tre dokument modifierades på måndagen, tio lades till på onsdagen. Att beräkna om femtontusen vektorer för varje ändring slösar tid och pengar. Här kommer MD5-hashen in i bilden: den identifierar innehåll, inte filen, så ett dokument som bytt namn men är oförändrat kommer inte att indexeras om, medan ett modifierat dokument kommer att producera en annan hash.

def mettre_a_jour(self, nouveaux_docs: list[Document]):
    """Lägg till dokument i det befintliga indexet."""
    # Filtrera bort redan indexerade dokument
    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 staplar de nya vektorerna under de gamla i samma ordning som extend på dokumentlistan: denna symmetri bevarar mappningen. Notera dock begränsningen i denna implementation – den lägger till, men tar inte bort eller ersätter. Ett modifierat dokument hamnar därför närvarande två gånger, i sin gamla och nya version. Att hantera borttagningar kräver att motsvarande rad tas bort från matrisen, en dyr operation i NumPy, och detta är en av anledningarna som får team att gå över till en riktig vektordatabas.

Användning från början till slut

Från början till slut tar det bara några få rader att bygga ett index över dokumentation.

# Skapa och fyll indexet
index = IndexSemantique()

docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")

index.construire(docs)
index.sauvegarder("mon_index")

# Sök
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 och ställ tre frågor vars svar du redan känner till. Om rätt dokument inte rankas först är boven nästan alltid chunkingen – avsnitt som är för långa eller titlar som inte injicerats om – snarare än inbäddningsmodellen.

Viktiga punkter

  • Ett semantiskt index länkar dokument, inbäddningar och metadata
  • Ladda dokument från olika format (text, Markdown, etc.)
  • Bygg indexet i batchar för att hantera stora samlingar
  • Spara och uppdatera inkrementellt för att undvika att beräkna om allt