Un RAG specializzato, in locale: il knowledge bot su dodici libri

La lezione precedente ha costruito la pipeline pezzo per pezzo. Questa la guarda funzionare su un caso vero: un assistente che risponde solo a partire da una dozzina di libri di game design, con le citazioni, senza mandare niente fuori dalla macchina. Il punto non è il game design: è che lo stesso schema vale per qualsiasi corpus chiuso, dai contratti di uno studio ai manuali di un’azienda.

Il problema: un modello che tira a indovinare

Fate una domanda precisa a un assistente AI. Sapete che la risposta è in un libro che avete sullo scaffale. Il modello risponde comunque, con sicurezza, e la risposta è plausibile e sbagliata. Non è cattiva volontà: il modello non ha mai letto quel libro, e quando manca il pezzo lo riempie con la cosa più probabile. Si chiama allucinazione, ed è il motivo per cui “sa un po’ di tutto” e “sa di cosa parla” sono due cose diverse.

La soluzione è cambiare le regole dell’esame: da interrogazione a memoria a esame a libro aperto. Prima si danno al modello le pagine giuste, poi gli si chiede di rispondere usando solo quelle.

a memoria                          a libro aperto (RAG)
domanda → modello → risposta       domanda → cerca nei documenti → passaggi
                                              → modello + passaggi → risposta citata

Due specialisti invece di un tuttofare

L’idea architetturale che rende il sistema leggero è non chiedere a un solo modello di fare tutto. Ci sono due ruoli, e due modelli diversi che li ricoprono.

Ruolo	Modello	Cosa fa	Quando lavora
Il bibliotecario	nomic-embed-text (274 MB)	Trasforma testo in vettori e trova i passaggi più simili alla domanda	Sempre: è il motore di ricerca
Il sintetizzatore	qwen3 da 8 o 14 miliardi di parametri	Legge i passaggi trovati e scrive una risposta discorsiva, con le fonti	Solo quando si chiede una risposta generata

Il bibliotecario è piccolo, veloce e fa una cosa sola. Il sintetizzatore è più grande e più lento, ma entra in gioco solo alla fine e riceve un contesto già selezionato. Separare i due ruoli ha una conseguenza pratica: la ricerca è istantanea anche senza generazione, e si può usare da sola quando basta trovare il passaggio.

Il flusso completo, dai libri alla risposta:

12 libri (PDF/EPUB)
   → estrazione del testo      232 capitoli in testo semplice
   → chunking + embedding      5.234 pezzi da ~800 token, vettorizzati
   → archivio vettoriale       ChromaDB, distanza coseno
   → domanda                   il bibliotecario recupera i 5 pezzi più vicini
   → (opzionale) generazione   il sintetizzatore risponde citando

Ogni pezzo porta con sé i suoi metadati: libro, autore, capitolo, pagine. È quello che permette al sistema di dire da dove viene una frase, e a chi legge di andare a controllare.

Tre modi di interrogarlo

Uno strumento potente e scomodo non si usa. Il sistema espone tre interfacce sullo stesso indice, per tre abitudini diverse.

Interfaccia web. Una pagina nel browser con due pulsanti: Search restituisce i passaggi più rilevanti in un istante; Generate aggiunge la risposta scritta dal sintetizzatore. Dal menu si sceglie il modello, quanti passaggi recuperare e la modalità di prompt. È la via consigliata per chi non vuole il terminale.

Riga di comando. Una chat nel terminale, con colori e formattazione, che dà accesso a tutte le opzioni: modello, numero di risultati, modalità, domanda singola non interattiva.

# solo ricerca, istantanea
python3 query.py -q "What are feedback loops?"

# ricerca + risposta generata, con analisi strutturata
python3 query.py --mode mechanics --top 10 --model qwen3:14b

Nessuna installazione. I capitoli estratti sono file di testo con un’intestazione di metadati. Un editor di codice assistito, come Claude Code, può cercarci dentro e leggere i passaggi senza indice vettoriale e senza modelli locali: una ricerca testuale al volo, che non sostituisce il RAG ma copre bene le domande “dove ne parlano”.

Quattro modalità esperte: cambia il prompt, non i documenti

Qui sta la parte più interessante. Lo stesso strumento offre quattro modalità di domanda, e la differenza fra una e l’altra non è nei documenti recuperati, che sono sempre gli stessi: è nell’istruzione data al sintetizzatore.

Modalità	Quando	Cosa impone al modello
general	Domanda classica	Rispondi solo dal contesto, cita le fonti
mechanics	Analisi di una meccanica	Identifica → confronta → compromessi → suggerisci varianti
codesign	Stai progettando il tuo gioco	Proponi meccaniche concrete, spiega perché funzionano, cita la teoria
compare	Confronto fra due approcci	Panoramica → somiglianze → differenze → contesto → verdetto

Il prompt di sistema della modalità mechanics, in sostanza, dice:

1. IDENTIFY   quali fonti nel contesto parlano di questa meccanica
2. COMPARE    come ciascuna la descrive
3. TRADE-OFFS pro e contro di ogni approccio
4. SUGGEST    due o tre variazioni concrete da provare

Non è una domanda, è uno schema di ragionamento. La risposta esce strutturata e citata invece che come un muro di testo, e il costo di aggiungere una modalità nuova è scrivere un paragrafo di istruzioni, non reindicizzare niente. È la stessa leva vista nel system prompt, applicata a un contesto già filtrato.

Su misura o generico?

Esistono strumenti pronti che fanno RAG su documenti caricati al volo, come Open WebUI. Perché costruirne uno specifico?

	Strumento su misura	Strumento generico
Scopo	Cercare in quei dodici libri	Chat generale, RAG su richiesta
Indice	Già pronto, 5.234 pezzi	I documenti si caricano ogni volta
Requisiti	Solo il motore dei modelli locali	Motore + container, più memoria
Modalità esperte	Sì, nel prompt	Da ricreare a mano ogni volta
Storico chat, immagini	No	Sì

La regola pratica è semplice: per un campo specifico, interrogato spesso, con lo stesso corpus, lo strumento su misura è più leggero e più comodo, perché ha già tutto indicizzato e sa come rispondere. Per tutto il resto, il generico. Non sono in competizione: coprono domande diverse.

Far crescere il corpus senza rifare tutto

Un indice vettoriale non è un blocco unico: ogni pezzo porta l’identificativo del libro da cui viene, e questo permette di lavorare per parti. Aggiungere un tredicesimo libro è una sequenza corta.

1. mettere il file nella cartella dei sorgenti
2. registrarlo nell'elenco dei libri (titolo, autore, identificativo)
3. estrarre il testo solo di quel libro
4. vettorizzare solo quel libro e aggiungerlo all'archivio

L’indicizzazione completa dei dodici libri richiede un quarto d’ora su un portatile; quella di un libro solo, un minuto. La stessa logica vale al contrario: un libro da togliere o da rifare si cancella per identificativo, senza toccare gli altri. È il motivo per cui conviene decidere i metadati prima di indicizzare: un pezzo senza identificativo del libro si può solo buttare via insieme a tutto il resto.

I limiti, e gli errori tipici

• Il bibliotecario decide la qualità. Se i passaggi recuperati sono sbagliati, il sintetizzatore scrive una risposta ben fatta su un contesto sbagliato. Quando una risposta è storta, si guarda prima cosa è stato recuperato e solo dopo il modello.
• La lingua dell’indice conta. Con libri in inglese, le domande in inglese recuperano meglio: l’embedding confronta testi, e la vicinanza fra lingue diverse è più debole.
• Quanti pezzi passare. Cinque è un buon punto di partenza; dieci servono per le analisi comparative e chiedono un modello con contesto più lungo. Quindici distraggono.
• La generazione è lenta. Con un modello da 8 miliardi una risposta richiede decine di secondi su un portatile; con il 14 miliardi anche più. La ricerca da sola resta istantanea, ed è spesso sufficiente.
• Un file corrotto in ingresso sparisce in silenzio. Un EPUB che in realtà è una pagina HTML produce zero capitoli e nessun errore: dopo l’estrazione si conta cosa è uscito.
• Non è un tuttofare. Sulle domande che non riguardano il corpus il RAG non aiuta, e il contesto irrilevante peggiora la risposta.

In sintesi

Concetto	In una riga
Il problema	Il modello non ha letto i vostri documenti e riempie i buchi
La soluzione	Esame a libro aperto: prima i passaggi giusti, poi la risposta
Due modelli	Un bibliotecario piccolo per cercare, un sintetizzatore per scrivere
Le dimensioni	12 libri, 232 capitoli, 5.234 pezzi indicizzati, tutto offline
Tre interfacce	Web, riga di comando, ricerca testuale senza installare niente
Le modalità	Cambiano il prompt di sistema, non i documenti
Su misura vs generico	Corpus fisso e domande frequenti: su misura. Il resto: generico
Se sbaglia	Controllare prima il recupero, poi il modello