Indeksiranje korpusa dokumentov
Na tej strani
Cilji
- Izgradi celoten indeks za semantično iskanje
- Obdelaj različne formate dokumentov (besedilo, PDF, Markdown)
- Posodobi indeks prirastno
Arhitektura semantičnega indeksa
Semantični indeks temelji na treh elementih, ki morajo ostati usklajeni: izvirni dokumenti, shranjeni s svojimi metapodatki, vdelave (embeddings), izračunane iz njihovega besedila, in preslikava, ki povezuje vsak vektor z njegovim izvornim dokumentom. Tretji del je najbolj krhek – prav tu se indeksi najpogosteje pokvarijo, ko brisanje premakne indekse na eni strani, na drugi pa ne.
Razred Document spodaj samodejno izračuna MD5 hash ob ustvarjanju. Uporabili ga bomo kasneje za zaznavanje tega, kar je že indeksirano.
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()
Cevovod za indeksiranje
1. korak: Naloži dokumente
Nalaganje je odvisno od formata, format pa določa zrnatost. Navadna besedilna datoteka postane en sam dokument; datoteka Markdown pa pogosto vsebuje več različnih tem in njeno indeksiranje kot enega samega bloka bi utopilo vsako temo v povprečju ostalih. Drugi nalagalnik zato razdeli besedilo na naslove ravni 2 in ponovno vstavi naslov odseka v indeksirano besedilo – to je tehnika obogatitve, obravnavana v lekciji 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
2. korak: Izgradi indeks
Razred IndexSemantique združuje gradnjo v serijah, iskanje na podlagi praga in trajnostno shranjevanje na disk. Parameter seuil (prag) v metodi rechercher si zasluži posebno pozornost: brez njega poizvedba, ki ni relevantna za temo, še vedno vrne pet najmanj slabih dokumentov z rezultati okoli 0,15, ki jih bo naivni klicatelj obravnaval kot veljavne odgovore. Filtriranje vsega, kar je pod določeno mejno vrednostjo, ti omogoča iskren odgovor: „Ničesar nisem našel.”
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
]
Metodi sauvegarder in charger zapišeta dve datoteki z isto predpono. Obravnavaj ju kot neločljiv par: kopiranje ene brez druge ali obnovitev delne varnostne kopije ustvari indeks, kjer vektorji ne ustrezajo več dokumentom – to je tiha napaka, ki se bo pokazala šele kot absurdni rezultati.
Prirastne posodobitve
Korpus se spreminja: trije dokumenti so bili spremenjeni v ponedeljek, deset dodanih v sredo. Ponovni izračun petnajstih tisoč vektorjev za vsako spremembo zapravlja čas in denar. Tu pride prav MD5 hash: identificira vsebino, ne datoteke, zato preimenovan, a nespremenjen dokument ne bo ponovno indeksiran, medtem ko bo spremenjen dokument ustvaril drugačen hash.
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)}")
np.vstack zloži nove vektorje pod stare v istem vrstnem redu, kot ga uporablja extend na seznamu dokumentov: ta simetrija ohranja preslikavo. Vendar bodi pozoren na omejitev te implementacije – dodaja, ne briše ali zamenjuje. Spremenjen dokument se tako konča dvakrat, v svoji stari in novi različici. Obdelava brisanj zahteva odstranitev ustrezne vrstice iz matrike, kar je v NumPyju draga operacija, in to je eden od razlogov, zakaj se ekipe odločajo za pravo vektorsko bazo podatkov.
Uporaba od začetka do konca
Celoten proces izgradnje indeksa nad dokumentacijo traja le nekaj vrstic kode.
# 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]}...")
Zaženi to na svoji dokumentaciji in postavi tri vprašanja, katerih odgovore že poznaš. Če pravi dokument ni na prvem mestu, je krivec skoraj vedno razdeljevanje na dele (chunking) – odseki so predolgi ali naslovi niso bili ponovno vstavljeni – in ne model vdelav.
Ključne ugotovitve
- Semantični indeks povezuje dokumente, vdelave in metapodatke
- Naloži dokumente iz različnih formatov (besedilo, Markdown itd.)
- Izgradi indeks v serijah za obdelavo velikih korpusov
- Shrani in posodobi prirastno, da se izogneš ponovnemu izračunu vsega