L'idea
Il RAG (Retrieval-Augmented Generation) di solito si usa su documenti: manuali, FAQ, articoli. Qui l'ho applicato a un caso più difficile, il codice sorgente. Il codice non si legge come un testo: conta in quale file sta una funzione, a che riga, cosa chiama e da chi viene chiamata. Per questo ogni risposta mostra i pezzi di codice usati, con file e righe, così si vede che l'assistente non sta inventando.
Come base ho scelto il codice di questo stesso sito: puoi chiedere come funziona una cosa che hai appena visto e leggere il codice che la fa funzionare.
Come funziona
- Indicizzazione notturna. Ogni notte un workflow n8n legge il repository da GitHub, tiene solo i file di codice (JavaScript, CSS, SQL, script di build, workflow) e scarta articoli e immagini.
- Blocchi con le righe. Ogni file viene diviso in blocchi di circa 60 righe che si sovrappongono un po', e ogni blocco porta con sé il percorso del file e i numeri di riga.
- Vettori su Supabase. Ogni blocco viene trasformato in un vettore con gli embedding di OpenAI e salvato in Postgres con pgvector. Il vecchio indice si cancella solo dopo che il nuovo è stato salvato, così la ricerca non resta mai vuota.
- Ricerca. Quando fai una domanda, il sito la invia a un webhook n8n che cerca gli 8 blocchi di codice più vicini alla domanda.
- Risposta con le fonti. Claude legge quei blocchi e risponde in italiano indicando quali ha usato davvero. Il sito mostra solo quelli, con l'evidenziazione della sintassi.
Scelte tecniche
Blocchi per righe, non per caratteri. Dividere il codice ogni N caratteri spezza funzioni e righe a metà. Dividerlo per righe, con una sovrapposizione, mantiene il codice leggibile e permette di citare intervalli di righe precisi.
Fonti dichiarate dal modello. Il modello deve restituire una risposta strutturata con gli identificativi dei blocchi che ha usato. Così mostro solo il codice pertinente, non tutto quello che la ricerca ha trovato.
Sicurezza. L'indice è leggibile solo da n8n: dal sito non si può interrogare il database direttamente. Nel repository non ci sono chiavi o password, quindi l'assistente non può rivelarle, e il modello ha l'istruzione di ignorare qualsiasi testo dentro il codice che provi a dargli ordini.
Conversazione. Il sito invia insieme alla domanda le ultime battute della conversazione, così puoi fare domande di approfondimento senza ripetere il contesto. Chi ha fatto l'accesso ritrova le conversazioni nella cronologia.
Cosa ho imparato
Su un RAG sul codice la qualità dipende più dalla preparazione dei dati che dal modello: quali file includere, come dividerli e quali metadati salvare. Mostrare le fonti cambia anche il rapporto con le risposte: invece di fidarti, puoi controllare. È lo stesso principio che serve in azienda quando un assistente AI deve lavorare su documentazione interna o su un codice esistente.