Indicizzazione: incorporare e memorizzare i chunk

Dopo aver caricato e suddiviso i documenti in chunk, si raggiunge la fase di indicizzazione: la conversione dei chunk di testo in embedding vettoriali e la loro memorizzazione in un database vettoriale consultabile. Questo è l'ultimo passaggio offline prima di poter rispondere alle query. La qualità degli embedding e l'efficienza della strategia di archiviazione e indicizzazione determinano direttamente la velocità e l'accuratezza del sistema RAG al momento della query.

L'approccio più comune consiste nel chiamare l'API degli embedding di OpenAI con il testo del chunk. Il modello text-embedding-3-small produce vettori di 1536 dimensioni e costa $0.02 per milione di token: un prezzo estremamente contenuto per la maggior parte dei carichi di lavoro. Invii più testi in una singola chiamata API (fino a 2048 input) per massimizzare il throughput. La risposta contiene un vettore di embedding per ogni testo di input, nello stesso ordine.

Quando indicizza migliaia di chunk, l'efficienza è importante. Elabori i chunk in batch da 100-500 per bilanciare throughput e utilizzo della memoria. Tenga traccia della posizione, così potrà riprendere l'elaborazione dopo un errore senza creare nuovamente gli embedding dei chunk già elaborati. Registri regolarmente l'avanzamento. Per 100.000 chunk elaborati in batch da 500, effettuerà 200 chiamate API: in genere l'operazione si completa in pochi minuti.

L'API degli embedding di OpenAI applica limiti di frequenza misurati in token al minuto (TPM). I processi di indicizzazione di grandi dimensioni raggiungono questi limiti e ricevono RateLimitError. Implementi un backoff esponenziale con jitter: quando si verifica un errore di limite di frequenza, attenda un breve intervallo casuale prima di riprovare, raddoppiando l'attesa a ogni errore successivo. In questo modo distribuisce i nuovi tentativi nel tempo e impedisce a tutti i worker paralleli di sovraccaricare l'API nello stesso momento.

Dopo aver generato gli embedding, esegua l'upsert nel vector store. Upsert significa inserire nuovi vettori o aggiornare quelli esistenti se è già presente lo stesso ID: per progettazione, l'operazione è idempotente. In Pinecone, ogni record sottoposto a upsert contiene l'ID del vettore, i valori dell'embedding e un dizionario di metadati con i campi che desidera filtrare o visualizzare in seguito. Esegua l'upsert in batch di massimo 100 record per chiamata, per ottenere il throughput ottimale.

Con pgvector, inserisca gli embedding direttamente in una tabella PostgreSQL utilizzando SQL standard. Il tipo di dati vector accetta una lista Python di float serializzata come stringa. Dopo aver inserito tutte le righe, crei un indice HNSW per velocizzare le query di ricerca approssimata dei vicini più prossimi. L'indicizzazione di una tabella esistente con milioni di righe può richiedere diversi minuti; per questo, crei l'indice dopo l'inserimento massivo anziché prima.

HNSW (Hierarchical Navigable Small World) è il tipo di indice che consente una ricerca rapida e approssimata dei vicini più prossimi. A differenza della ricerca a forza bruta, che confronta il vettore della query con ogni vettore memorizzato, HNSW crea una struttura a grafo multilivello che riduce lo spazio di ricerca. Il parametro m controlla il numero di connessioni di ogni nodo (un valore più alto migliora il recall ma richiede più memoria), mentre ef_construction controlla la qualità dell'indice durante la fase di creazione.

I metadati memorizzati insieme a ogni vettore consentono un potente recupero filtrato. Progetti lo schema dei metadati prima dell'indicizzazione: l'aggiunta di nuovi campi in seguito richiede una nuova indicizzazione. Includa i campi su cui applicherà i filtri (department, doc_type, intervallo di date), quelli che visualizzerà nelle citazioni (title, page, author) e quelli utili per il debugging (chunk_index, total_chunks, indexed_at). Mantenga semplici i valori dei metadati: stringhe, numeri e valori booleani vengono indicizzati e filtrati in modo efficiente, mentre gli oggetti annidati no.

L'indicizzazione di un corpus di grandi dimensioni può richiedere ore. Un arresto anomalo a metà processo farebbe perdere tutti i progressi. Implementi un file di checkpoint che registri quali chunk sono stati indicizzati correttamente. Al riavvio, salti i chunk già indicizzati e riprenda dal punto in cui si era interrotto. In questo modo il processo di indicizzazione è idempotente e può essere ripreso in sicurezza. Memorizzi il checkpoint come insieme di ID dei chunk elaborati in un file JSON o in una tabella del database.

Dopo l'indicizzazione, verifichi che tutti i chunk siano stati inseriti nel vector store. Confronti il numero di chunk prodotti dal proprio splitter con il numero di vettori indicato dall'indice. Interroghi l'indice utilizzando il testo di un documento noto e confermi che il risultato atteso compaia tra i primi 5. Esegua alcune query note del proprio golden test set e verifichi che la precisione raggiunga il livello previsto. Non dia mai per scontato che l'indice sia completo senza averlo verificato.

Per i dati sensibili dal punto di vista della privacy che non possono lasciare la propria infrastruttura, utilizzi modelli di embedding ospitati localmente. La libreria sentence-transformers fornisce modelli di alta qualità come all-MiniLM-L6-v2 (384 dimensioni, 22 MB, molto veloce) e bge-large-en-v1.5 (1024 dimensioni, qualità superiore). Li esegua sulla CPU per carichi di lavoro moderati o sulla GPU per processi di indicizzazione di grandi dimensioni. I modelli locali eliminano i costi delle API e l'uscita dei dati dall'infrastruttura, ma richiedono la gestione dei file dei modelli e delle risorse di calcolo.

In questa lezione ha imparato a: generare embedding in batch con l'API OpenAI e gestire i limiti di frequenza con l'exponential backoff, eseguire l'upsert dei vettori in Pinecone e pgvector con i metadati, creare indici HNSW per una ricerca rapida e approssimata dei vicini più prossimi e applicare le best practice per la produzione, tra cui la ripresa basata su checkpoint, la progettazione dello schema dei metadati e la verifica della completezza dell'indice. Nel prossimo capitolo creeremo la pipeline di query che recupera i chunk e genera risposte basate sulle fonti.