Egy dokumentumkorpusz indexelése
Ezen az oldalon
Célok
- Teljes szemantikus keresési index felépítése
- Különböző dokumentumformátumok kezelése (szöveg, PDF, Markdown)
- Az index inkrementális frissítése
Egy szemantikus index architektúrája
Egy szemantikus index három elemen alapul, amelyeknek szinkronban kell maradniuk: az eredeti dokumentumok tárolása metaadatokkal, a szövegeikből számított beágyazások (embeddings), valamint a leképezés, amely minden vektort a forrásdokumentumához köt. Ez a harmadik elem a legkényesebb – szinte mindig itt sérülnek meg az indexek, amikor egy törlés eltolja az indexeket az egyik oldalon, de a másikon nem.
Az alábbi Document osztály egy MD5-hash-t ad hozzá, amely automatikusan számítódik létrehozáskor. Később ezt használjuk annak észlelésére, mit indexeltünk már.
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()
Indexelési folyamat
1. lépés: Dokumentumok betöltése
A betöltés a formátumtól függ, a formátum pedig meghatározza a szemcsézettséget. Egy egyszerű szövegfájl egyetlen dokumentummá válik; egy Markdown-fájl viszont gyakran több különálló témát tartalmaz, és egyben történő indexelésük elmosná az egyes témákat a többi átlagában. A második betöltő ezért a 2. szintű címsorok szerint darabolja fel a fájlt, és visszailleszti a szakasz címét az indexelt szövegbe – ez az enrichment technika, amelyet a 3. leckében tárgyaltunk.
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. lépés: Az index felépítése
Az IndexSemantique osztály egyesíti a kötegelt felépítést, a küszöbértéken alapuló keresést és a lemezen történő tartósítást. A rechercher metódus seuil (küszöbérték) paramétere figyelmet érdemel: enélkül egy témán kívüli lekérdezés is visszaadja az öt legkevésbé rossz dokumentumot, körülbelül 0,15-ös pontszámokkal, amelyeket egy naív hívó érvényes válaszként kezel. A küszöbérték alatti találatok kiszűrése lehetővé teszi, hogy őszintén azt válaszd: „Nem találtam semmit.“
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
]
A sauvegarder és charger metódusok két, azonos előtaggal rendelkező fájlt írnak. Kezeld őket elválaszthatatlan párként: ha csak az egyiket másolod le, vagy hiányos biztonsági másolatot állítasz helyre, olyan indexet kapsz, ahol a vektorok már nem egyeznek a dokumentumokkal – ez egy csendes hiba, amely csak abszurd eredményekben mutatkozik meg.
Inkrementális frissítések
Egy korpusz fejlődik: hétfőn három dokumentum módosul, szerdán tíz új kerül hozzá. Minden egyes változásnál tizenötezer vektor újraszámítása idő- és pénzpazarlás. Itt jön képbe az MD5-hash: ez a tartalmat azonosítja, nem a fájlt, így egy átnevezett, de változatlan dokumentum nem kerül újraindexelésre, míg egy módosított dokumentum más hash-t generál.
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)}")
A np.vstack az új vektorokat a régiek alá illeszti, ugyanabban a sorrendben, ahogy a dokumentumlista extend metódusa működik: ez a szimmetria őrzi meg a leképezést. Vegyél azonban tudomást ennek a megvalósításnak a korlátjáról – csak hozzáad, de nem töröl vagy cserél le. Egy módosított dokumentum így kétszer lesz jelen: a régi és az új verziójában is. A törlések kezelése megköveteli a megfelelő sor eltávolítását a mátrixból, ami NumPy-ban költséges művelet, és ez az egyik oka annak, amiért a csapatok megfelelő vektoradatbázis felé mozdulnak.
End-to-end használat
Végigvezetve az egész folyamatot, egy dokumentáció feletti index felépítése mindössze néhány sorba kerül.
# 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]}...")
Futtasd le a saját dokumentációdon, és tegyél fel három kérdést, amelyekre ismered a választ. Ha a helyes dokumentum nem az első helyen szerepel, az bűnös szinte mindig a darabolás (chunking) – túl hosszú szakaszok vagy be nem illesztett címek –, nem pedig a beágyazási modell.
Főbb megállapítások
- Egy szemantikus index összeköti a dokumentumokat, a beágyazásokat és a metaadatokat
- Dokumentumok betöltése különböző formátumokból (szöveg, Markdown stb.)
- Az index kötegekben történő felépítése nagy korpuszok kezeléséhez
- Mentés és inkrementális frissítés a mindent újra kiszámítás elkerülése érdekében