Indicizzare un corpus di documenti
In questa pagina
Obiettivi
- Costruire un indice di ricerca semantica completo
- Gestire diversi formati di documenti (testo, PDF, Markdown)
- Aggiornare l’indice in modo incrementale
Architettura di un indice semantico
Un indice semantico si basa su tre elementi che devono rimanere sincronizzati: i documenti originali archiviati con i loro metadati, gli embedding calcolati dal loro testo e la mappatura che collega ogni vettore al documento sorgente. Questo terzo elemento è il più fragile: è quasi sempre qui che gli indici si corrompono, quando una cancellazione sposta gli indici da una parte ma non dall’altra.
La classe Document qui sotto aggiunge un hash MD5 calcolato automaticamente alla creazione. Lo useremo più tardi per rilevare cosa è già stato indicizzato.
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 di indicizzazione
Passo 1: Caricare i documenti
Il caricamento dipende dal formato, e il formato determina la granularità. Un file di testo semplice diventa un singolo documento; un file Markdown, invece, contiene spesso diversi argomenti distinti e indicizzarlo come un unico blocco annegherebbe ogni argomento nella media degli altri. Il secondo loader quindi divide sulle intestazioni di livello 2 e reinietta il titolo della sezione nel testo indicizzato: questa è la tecnica di arricchimento trattata nella lezione 3.
from pathlib import Path
def charger_fichiers_texte(dossier: str) -> list[Document]:
"""Carica tutti i file di testo da una cartella."""
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]:
"""Carica i file Markdown, dividendo per sezioni."""
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
Passo 2: Costruire l’indice
La classe IndexSemantique riunisce la costruzione in batch, la ricerca basata su soglia e la persistenza su disco. Il parametro seuil (soglia) nel metodo rechercher merita attenzione: senza di esso, una query fuori tema restituisce comunque i cinque documenti “meno peggiori”, con punteggi intorno a 0,15 che un chiamante ingenuo tratterà come risposte valide. Filtrare tutto ciò che sta sotto un punteggio minimo ti permette di rispondere onestamente: “Non ho trovato nulla”.
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):
"""Costruisce l'indice da una lista di documenti."""
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]:
"""Cerca i k documenti più rilevanti."""
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):
"""Salva l'indice su disco."""
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):
"""Carica un indice da disco."""
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
]
I metodi sauvegarder e charger scrivono due file che condividono lo stesso prefisso. Trattali come una coppia inseparabile: copiarne uno senza l’altro, o ripristinare un backup parziale, produce un indice in cui i vettori non corrispondono più ai documenti: un fallimento silenzioso che si manifesterà solo con risultati assurdi.
Aggiornamenti incrementali
Un corpus evolve: tre documenti modificati lunedì, dieci aggiunti mercoledì. Ricalcolare quindicimila vettori per ogni cambiamento spreca tempo e denaro. È qui che entra in gioco l’hash MD5: identifica il contenuto, non il file, quindi un documento rinominato ma immutato non verrà reindicizzato, mentre un documento modificato produrrà un hash diverso.
def mettre_a_jour(self, nouveaux_docs: list[Document]):
"""Aggiunge documenti all'indice esistente."""
# Filtra i documenti già indicizzati
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)}")
Il np.vstack impila i nuovi vettori sotto quelli vecchi nello stesso ordine dell’extend sulla lista dei documenti: questa simmetria preserva la mappatura. Nota tuttavia il limite di questa implementazione: aggiunge, ma non cancella né sostituisce. Un documento modificato finisce quindi per essere presente due volte, nella sua versione vecchia e in quella nuova. Gestire le cancellazioni richiede la rimozione della riga corrispondente dalla matrice, un’operazione costosa in NumPy, ed è uno dei motivi che spingono i team verso un vero database vettoriale.
Utilizzo end-to-end
Da capo a fondo, costruire un indice sulla documentazione richiede solo poche righe.
# Crea e popola l'indice
index = IndexSemantique()
docs = charger_fichiers_markdown("./documentation/")
print(f"{len(docs)} sections loaded")
index.construire(docs)
index.sauvegarder("mon_index")
# Cerca
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]}...")
Eseguilo sulla tua documentazione e poni tre domande di cui conosci le risposte. Se il documento giusto non risulta al primo posto, il colpevole è quasi sempre il chunking (sezioni troppo lunghe o titoli non reiniettati), piuttosto che il modello di embedding.
Punti chiave
- Un indice semantico collega documenti, embedding e metadati
- Carica documenti da diversi formati (testo, Markdown, ecc.)
- Costruisci l’indice in batch per gestire grandi corpus
- Salva e aggiorna in modo incrementale per evitare di ricalcolare tutto