Assistente AI sui documenti interni: architettura RAG, permessi e limiti reali

Un assistente che risponde sui documenti interni (contratti, procedure, manuali, verbali) è oggi uno dei progetti di intelligenza artificiale con il rapporto più chiaro tra costo e beneficio. È anche uno dei più facili da fare male: la demo funziona in un pomeriggio, la versione affidabile richiede scelte precise su come si prepara il testo, come si cerca, chi può vedere cosa e come si misura la qualità.

L'architettura: RAG, non addestramento

Il modello linguistico non «impara» i documenti. A ogni domanda il sistema cerca i passaggi pertinenti e li passa al modello insieme alla domanda, con l'istruzione di rispondere solo su quelli e di citarli. È la tecnica chiamata RAG (Retrieval-Augmented Generation). Ha due vantaggi decisivi: i documenti si aggiornano senza riaddestrare nulla, e ogni risposta è verificabile sulla fonte.

Il lavoro vero non è nel modello, ma nelle tre fasi intorno: preparazione, ricerca, generazione controllata.

Preparazione: dove si decide la qualità

Estrazione

PDF nativi, PDF scansionati, documenti Word, fogli di calcolo, pagine web interne. Ognuno richiede un estrattore diverso. Le tabelle sono il punto critico: estratte male diventano sequenze di numeri senza intestazioni, e il modello risponde con sicurezza su dati che ha frainteso.

Suddivisione

I documenti si dividono in porzioni (chunk). Dividerli ogni N caratteri è il metodo più rapido e il peggiore. Funziona meglio rispettare la struttura: sezioni, articoli di un contratto, passi di una procedura, con un po' di sovrapposizione e con il titolo della sezione ripetuto nel testo della porzione. Ogni porzione porta con sé metadati: documento, versione, data, sezione, ruoli autorizzati.

Versioni

Se due versioni della stessa procedura sono entrambe indicizzate, l'assistente può citare quella superata. Serve un criterio esplicito: solo l'ultima versione, oppure tutte ma con la data in evidenza e la preferenza per la più recente.

Ricerca: ibrida, non solo semantica

La ricerca per similarità semantica (embedding) trova passaggi con parole diverse ma significato simile. Da sola però sbaglia su codici prodotto, numeri di articolo, nomi propri, sigle. La combinazione che uso di solito:

• ricerca ibrida: semantica più ricerca testuale classica (BM25), fuse in un'unica classifica;
• filtri sui metadati prima della ricerca: lingua, tipo di documento, e soprattutto permessi;
• riordinamento dei primi risultati con un modello dedicato, che migliora molto la pertinenza dei passaggi passati al modello.

Generazione controllata

Le istruzioni al modello impongono di rispondere solo dai passaggi forniti, di citare documento e sezione, e di dichiarare quando l'informazione non c'è. Sotto una soglia di pertinenza, l'assistente non prova a rispondere: dice che non ha trovato nulla e indica a chi rivolgersi. È meglio un «non lo so» che una risposta plausibile e sbagliata su una clausola contrattuale.

Permessi: il punto che si scopre tardi

Un assistente che ha letto tutto può rivelare tutto. I permessi vanno applicati in fase di ricerca, filtrando i passaggi in base ai ruoli dell'utente, non dopo la generazione. Se il passaggio riservato non arriva al modello, il modello non può citarlo. Servono inoltre un registro delle domande e delle fonti consultate, regole di conservazione dei log e una valutazione GDPR quando nei documenti ci sono dati personali.

Misurare la qualità

Prima del rilascio si costruisce un insieme di domande reali, con la risposta attesa e la fonte corretta, scritto da chi conosce i documenti. Lo si riesegue a ogni modifica di suddivisione, ricerca o istruzioni. Si misurano due cose separate: se la ricerca ha trovato il passaggio giusto, e se la risposta è fedele a quel passaggio. Senza questo insieme di prova, ogni cambiamento è un'impressione.

Limiti da dichiarare

• Su domande che richiedono di combinare molti documenti, la qualità cala.
• Calcoli e confronti numerici vanno delegati a codice, non al modello.
• L'assistente supporta il giudizio, non lo sostituisce, soprattutto su temi legali e contrattuali.
• La qualità dipende dai documenti: se sono contraddittori, lo saranno anche le risposte.

Costi e manutenzione nel tempo

Un assistente sui documenti non si consegna una volta. I documenti cambiano, e l'indice va aggiornato: idealmente in modo incrementale, rielaborando solo i file modificati, con la cancellazione delle porzioni di quelli rimossi. Se si cambia il modello di embedding, l'indice va ricostruito per intero, perché vettori di modelli diversi non sono confrontabili.

I costi d'uso hanno tre componenti: indicizzazione (una tantum e a ogni aggiornamento), ricerca (minima) e generazione (proporzionale a domande, passaggi inviati e lunghezza delle risposte). Si tengono sotto controllo passando al modello solo i passaggi davvero pertinenti, con risposte brevi per impostazione e un modello proporzionato al compito.

La fonte di miglioramento più preziosa sono i registri: le domande a cui l'assistente non ha saputo rispondere indicano documenti mancanti o scritti male. Rivederle ogni mese con chi cura i contenuti migliora l'assistente più di qualunque cambio di modello.

Come la vedo io

Credo negli assistenti stretti: poche fonti, ben curate, e il coraggio di rispondere «non lo so». È lo stesso principio della chat di questo sito, che risponde solo su un unico file di conoscenza scritto a mano e rifiuta tutto il resto. Ed è il principio del Capitano di Fix and Sail, l'assistente che risponde sulla base dei manuali degli accessori installati su quella specifica barca, non in modo generico.

Diffido dei progetti che partono dal modello più potente e da «carichiamo tutto». L'intelligenza artificiale qui è la parte facile. La parte che fa la differenza è la cura dei documenti, la ricerca e i permessi: lavoro da sviluppatore, non da prompt.

Perché affidarlo a me

Programmo dal 1999, ho consegnato più di 300 progetti e lavoro come sviluppatore esterno con circa 30 agenzie, da Roma e da remoto. Progetto assistenti RAG con ricerca ibrida, citazioni, permessi per ruolo e un insieme di prova per misurarne la qualità.

Se vuoi capire se i tuoi documenti si prestano a un assistente, scrivimi: in una chiacchierata di circa 20 minuti guardiamo fonti, utenti e rischi. Il servizio è in Intelligenza artificiale per le attività.