Indexovanie korpusu dokumentov
Na tejto strane
Ciele
- Vytvoriť kompletný index pre sémantické vyhľadávanie
- Spracovať rôzne formáty dokumentov (text, PDF, Markdown)
- Prírastkovo aktualizovať index
Architektúra sémantického indexu
Sémantický index stojí na troch pilieroch, ktoré musia zostať v synchronizácii: pôvodné dokumenty uložené spolu s metadátami, vektory (embeddings) vypočítané z ich textu a mapovanie, ktoré spája každý vektor so zdrojovým dokumentom. Práve táto tretia zložka je najkrehkejšia – tu sa indexy najčastejšie poškodia, keď napríklad vymazanie posunie indexy na jednej strane, ale nie na druhej.
Nižšie uvedená trieda Document pridáva MD5 hash, ktorý sa automaticky vypočíta pri vytvorení. Neskôr ho využijeme na detekciu toho, čo už bolo indexované.
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()
Pipeline indexovania
Krok 1: Načítanie dokumentov
Načítanie závisí od formátu a formát určuje granularitu. Obyčajný textový súbor sa stane jedným dokumentom; súbor Markdown však často obsahuje niekoľko odlišných tém a jeho indexovanie ako jedného bloku by utopilo každú tému v priemere ostatných. Druhý načítavač preto rozdeľuje obsah podľa nadpisov úrovne 2 a vracia názov sekcie späť do indexovaného textu – toto je technika obohatenia, ktorú sme prebrali v lekcii 3.
from pathlib import Path
def charger_fichiers_texte(dossier: str) -> list[Document]:
"""Načíta všetky textové súbory z priečinka."""
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]:
"""Načíta súbory Markdown a rozdelí ich podľa sekcií."""
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
Krok 2: Vytvorenie indexu
Trieda IndexSemantique spája dávkové vytváranie, vyhľadávanie na základe prahu a ukladanie na disk. Parameter seuil (prah) v metóde rechercher si zaslúži pozornosť: bez neho by dotaz mimo témy stále vrátil päť „najmenej zlých“ dokumentov so skóre okolo 0,15, ktoré by naivný volajúci považoval za platné odpovede. Odfiltrovanie všetkého pod určitou hranicou ti umožní úprimne odpovedať: „Nenašiel som nič.“
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):
"""Vytvorí index zo zoznamu dokumentov."""
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]:
"""Vyhľadá k najrelevantnejších dokumentov."""
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):
"""Uloží index 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):
"""Načíta index z disku."""
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
]
Metódy sauvegarder a charger zapisujú dva súbory zdieľajúce rovnakú predponu. Ber ich ako neoddeliteľný pár: skopírovanie jedného bez druhého alebo obnovenie čiastočnej zálohy vytvorí index, kde vektory už nezodpovedajú dokumentom – tichá chyba, ktorá sa prejaví až absurdnými výsledkami.
Prírastkové aktualizácie
Korpus sa vyvíja: tri dokumenty upravené v pondelok, desať pridaných v stredu. Prepočítavanie pätnástich tisíc vektorov pri každej zmene plytvá časom aj peniazmi. Tu prichádza na rad MD5 hash: identifikuje obsah, nie súbor, takže premenovaný, ale nezmenený dokument sa nebude znovu indexovať, zatiaľ čo upravený dokument vyprodukuje iný hash.
def mettre_a_jour(self, nouveaux_docs: list[Document]):
"""Pridá dokumenty do existujúceho indexu."""
# Odfiltruje už indexované dokumenty
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)}")
Funkcia np.vstack uloží nové vektory pod staré v rovnakom poradí, ako extend pracuje so zoznamom dokumentov: táto symetria zachováva mapovanie. Všimni si však obmedzenie tejto implementácie – pridáva, ale nemaže ani nenahrádza. Upravený dokument sa tak v indexe objaví dvakrát, v starej aj novej verzii. Riešenie vymazania vyžaduje odstránenie zodpovedajúceho riadku z matice, čo je v NumPy nákladná operácia, a to je jeden z dôvodov, prečo tímy smerujú k použitiu skutočnej vektorovej databázy.
Kompletné použitie
Od začiatku do konca trvá vytvorenie indexu nad dokumentáciou len niekoľko riadkov.
# Vytvorenie a naplnenie indexu
index = IndexSemantique()
docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")
index.construire(docs)
index.sauvegarder("mon_index")
# Vyhľadávanie
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]}...")
Spusť to na vlastnej dokumentácii a polož tri otázky, ktorých odpovede poznáš. Ak správny dokument nie je na prvom mieste, vinníkom je takmer vždy chunking (rozkuskovanie) – sekcie príliš dlhé alebo názvy neboli vrátené späť – skôr než samotný model embeddings.
Kľúčové poznatky
- Sémantický index prepája dokumenty, vektory (embeddings) a metadáta
- Načítavaj dokumenty z rôznych formátov (text, Markdown atď.)
- Buduj index v dávkach, aby si zvládol veľké korpusy
- Ukladaj a aktualizuj prírastkovo, aby sa predišlo prepočítavaniu všetkého