Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Indicizzare un corpus di documenti

Lezione 7 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Architettura di un indice semantico
  3. Pipeline di indicizzazione
  4. Aggiornamenti incrementali
  5. Utilizzo end-to-end
  6. Punti chiave

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