Indeksiranje korpusa dokumenata
Na ovoj stranici
Ciljevi
- Izgradi kompletan indeks za semantičko pretraživanje
- Upravljaj različitim formatima dokumenata (tekst, PDF, Markdown)
- Inkrementalno ažuriraj indeks
Arhitektura semantičkog indeksa
Semantički indeks oslanja se na tri elementa koja moraju ostati usklađena: izvorne dokumente pohranjene sa svojim metapodacima, ugradnje (embeddings) izračunate iz njihova teksta i mapiranje koje povezuje svaki vektor s njegovim izvornim dokumentom. Taj je treći dio najkrhkiji – upravo se tu indeksi najčešće kvare, kada brisanje pomakne indekse na jednoj strani, a ne i na drugoj.
Klasa Document u nastavku automatski dodaje MD5 hash pri stvaranju. Iskoristit ćemo ga kasnije za otkrivanje onoga što je već 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()
Cjevovod indeksiranja
Korak 1: Učitavanje dokumenata
Učitavanje ovisi o formatu, a format određuje granuliranost. Obična tekstualna datoteka postaje jedan dokument; Markdown datoteka, međutim, često sadrži nekoliko različitih tema, a njezino indeksiranje kao jednog bloka utopilo bi svaku temu u prosjeku ostalih. Drugo učitavanje stoga dijeli sadržaj na naslove razine 2 i ponovno ubacuje naslov odlomka u indeksirani tekst – to je tehnika obogaćivanja obrađena u lekciji 3.
from pathlib import Path
def charger_fichiers_texte(dossier: str) -> list[Document]:
"""Učitaj sve tekstualne datoteke iz mape."""
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]:
"""Učitaj Markdown datoteke, dijeleći ih po odlomcima."""
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
Korak 2: Izgradnja indeksa
Klasa IndexSemantique objedinjuje grupnu izgradnju, pretraživanje temeljeno na pragu i trajnost na disku. Parametar seuil (prag) u metodi rechercher zaslužuje pozornost: bez njega, upit izvan teme i dalje vraća pet najmanje loših dokumenata, s rezultatima oko 0,15 koje će naivni pozivatelj tretirati kao valjane odgovore. Filtriranje svega ispod donje granice rezultata omogućuje ti da iskreno odgovoriš: „Ništa nisam pronašao.“
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):
"""Izgradi indeks iz popisa dokumenata."""
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]:
"""Pretraži k najrelevantnijih dokumenata."""
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):
"""Spremi indeks na 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):
"""Učitaj indeks s diska."""
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
]
Metode sauvegarder i charger zapisuju dvije datoteke koje dijele isti prefiks. Tretiraj ih kao nerazdvojiv par: kopiranje jedne bez druge ili obnavljanje djelomične sigurnosne kopije stvara indeks u kojem vektori više ne odgovaraju dokumentima – tihi kvar koji će se pokazati samo kao apsurdni rezultati.
Inkrementalna ažuriranja
Korpus se mijenja: tri dokumenta izmijenjena u ponedjeljak, deset dodanih u srijedu. Ponovno izračunavanje petnaest tisuća vektora za svaku promjenu gubi vrijeme i novac. Ovdje na scenu stupa MD5 hash: on identificira sadržaj, a ne datoteku, pa preimenovani, ali nepromijenjeni dokument neće biti ponovno indeksiran, dok će izmijenjeni dokument proizvesti drugačiji hash.
def mettre_a_jour(self, nouveaux_docs: list[Document]):
"""Dodaj dokumente u postojeći indeks."""
# Filtriraj već indeksirane dokumente
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 slaže nove vektore ispod starih istim redoslijedom kao i extend na popisu dokumenata: ta simetrija čuva mapiranje. Ipak, imaj na umu ograničenje ove implementacije – ona dodaje, ali ne briše niti zamjenjuje. Izmijenjeni dokument stoga završava prisutan dvaput, u svojoj staroj i novoj verziji. Rukovanje brisanjima zahtijeva uklanjanje odgovarajućeg retka iz matrice, što je skupa operacija u NumPyju, i to je jedan od razloga koji timove gura prema pravoj vektorskoj bazi podataka.
Korištenje od početka do kraja
Od početka do kraja, izgradnja indeksa nad dokumentacijom zahtijeva samo nekoliko redaka koda.
# Stvori i popuni indeks
index = IndexSemantique()
docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")
index.construire(docs)
index.sauvegarder("mon_index")
# Pretraživanje
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]}...")
Pokreni to na vlastitoj dokumentaciji i postavi tri pitanja na koja znaš odgovore. Ako ispravan dokument nije na prvom mjestu, krivac je gotovo uvijek chunking – odlomci predugi ili naslovi nisu ponovno ubačeni – a ne model ugradnje.
Ključne točke
- Semantički indeks povezuje dokumente, ugradnje i metapodatke
- Učitaj dokumente iz različitih formata (tekst, Markdown itd.)
- Izgradi indeks u serijama za rukovanje velikim korpusima
- Spremi i ažuriraj inkrementalno kako bi izbjegao ponovno izračunavanje svega