Indexarea unui corpus de documente
Pe această pagină
Obiective
- Construirea unui index de căutare semantică complet
- Gestionarea diferitelor formate de documente (text, PDF, Markdown)
- Actualizarea incrementală a indexului
Arhitectura unui index semantic
Un index semantic se bazează pe trei elemente care trebuie să rămână sincronizate: documentele originale stocate împreună cu metadatele lor, embedding-urile calculate din textul acestora și maparea care leagă fiecare vector de documentul sursă corespunzător. Această a treia componentă este cea mai fragilă; aici apar aproape întotdeauna coruperile indexului, atunci când o ștergere deplasează indicii într-o parte, dar nu și în cealaltă.
Clasa Document de mai jos adaugă un hash MD5 calculat automat la creare. Îl vom folosi ulterior pentru a detecta ce a fost deja indexat.
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()
Fluxul de indexare
Pasul 1: Încărcarea documentelor
Încărcarea depinde de format, iar formatul determină granularitatea. Un fișier text simplu devine un singur document; un fișier Markdown, însă, conține adesea mai multe subiecte distincte, iar indexarea lui ca un singur bloc ar dilua fiecare subiect în media celorlalte. Al doilea loader divizează therefore la nivelul titlurilor de nivel 2 și reinjectează titlul secțiunii în textul indexat – aceasta este tehnica de îmbogățire abordată în lecția 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
Pasul 2: Construirea indexului
Clasa IndexSemantique reunește construcția pe loturi, căutarea bazată pe prag și persistența pe disc. Parametrul seuil (prag) din metoda rechercher merită atenție: fără el, o interogare fără legătură cu subiectul va returna totuși cele cinci documente „cel mai puțin rele“, cu scoruri în jur de 0,15, pe care un apelant naiv le va trata ca răspunsuri valide. Filtrarea oricărui rezultat sub un scor minim vă permite să răspundeți onest: „Nu am găsit nimic“.
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
]
Metodele sauvegarder și charger scriu două fișiere care partajează același prefix. Tratați-le ca pe o pereche inseparabilă: copierea unuia fără celălalt sau restaurarea unei copii de rezervă parțiale produce un index în care vectorii nu mai corespund documentelor – o eroare silențioasă care se va manifesta doar prin rezultate absurde.
Actualizări incrementale
Un corpus evoluează: trei documente modificate luni, zece adăugate miercuri. Recalcularea a cincisprezece mii de vectori pentru fiecare schimbare risipește timp și bani. Aici intervine hash-ul MD5: acesta identifică conținutul, nu fișierul, astfel încât un document redenumit, dar neschimbat, nu va fi reindexat, în timp ce un document modificat va produce un hash diferit.
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)}")
Funcția np.vstack stivuește noii vectori sub cei vechi, în aceeași ordine ca operația extend asupra listei de documente: această simetrie păstrează maparea. Rețineți totuși limita acestei implementări: aceasta adaugă, dar nu șterge și nu înlocuiește. Un document modificat va ajunge astfel prezent de două ori, în versiunea sa veche și în cea nouă. Gestionarea ștergerilor necesită eliminarea rândului corespunzător din matrice, o operație costisitoare în NumPy, iar acesta este unul dintre motivele care împing echipele către o bază de date vectorială propriu-zisă.
Utilizare end-to-end
De la capăt la capăt, construirea unui index peste documentație necesită doar câteva linii de cod.
# 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]}...")
Rulați acest cod pe propria documentație și puneți trei întrebări ale căror răspunsuri le cunoașteți. Dacă documentul corect nu se clasează pe primul loc, vinovatul este aproape întotdeauna fragmentarea (chunking) – secțiuni prea lungi sau titluri ne-reinjectate – și nu modelul de embedding.
Puncte cheie
- Un index semantic leagă documentele, embedding-urile și metadatele
- Încărcați documente din diferite formate (text, Markdown etc.)
- Construiți indexul pe loturi pentru a gestiona corpusuri mari
- Salvați și actualizați incremental pentru a evita recalcularea tuturor datelor