AI e ingegneria della conoscenza
RAG per la documentazione tecnica: progettare fonti, versioni e permessi
Un gruppo software accumula manuali, decisioni architetturali, procedure di rilascio e note sulle integrazioni. Cercare una risposta in questo patrimonio può richiedere tempo, soprattutto quando convivono versioni diverse dello stesso sistema. Un assistente basato su retrieval-augmented generation, o RAG, può recuperare passaggi documentali e usarli come contesto per generare una risposta. La parte decisiva del progetto riguarda però la qualità del collegamento tra domanda, documenti e autorizzazioni: una spiegazione scorrevole resta poco utile se descrive la versione sbagliata o rivela informazioni non accessibili al richiedente.
Definire il compito e il confine della conoscenza
La documentazione Microsoft descrive la RAG come un modello che collega la generazione del linguaggio al recupero di contenuti pertinenti. Questo non equivale a trasferire automaticamente tutte le conoscenze dell’organizzazione dentro un assistente. Il progetto deve stabilire a quali domande rispondere, quali raccolte utilizzare e quali comportamenti escludere. Per un primo impiego nella documentazione tecnica può essere ragionevole aiutare a trovare procedure e spiegare passaggi, mantenendo separata qualsiasi esecuzione di comandi o modifica degli ambienti.
Consideriamo un esempio interamente illustrativo: un gruppo vuole consultare le istruzioni per distribuire due versioni di un’applicazione. Alcuni componenti vengono gestiti internamente, altri da un fornitore. Prima di scegliere l’indice o il modello, serve sapere chi mantiene le procedure, quali siano approvate e chi possa leggerle. Una raccolta che mescola bozze e istruzioni operative senza distinguerle introduce un’ambiguità a monte della ricerca. Il sistema deve poter riconoscere un’informazione mancante e indirizzare alla fonte responsabile, senza colmare il vuoto con una procedura plausibile.
Conservare identità e validità delle fonti
Ogni documento dovrebbe avere un’identità stabile, una versione e un contesto di applicazione. Nel caso illustrativo, un passaggio valido per la versione precedente non diventa una risposta corretta soltanto perché contiene parole simili alla domanda. Conviene distinguere versione del documento, versione del software descritta e stato di approvazione. Una data recente può riferirsi a una correzione editoriale, mentre una procedura più vecchia potrebbe restare quella valida per un ambiente ancora in uso. Il recupero deve disporre di questi metadati per selezionare il perimetro pertinente.
Il ciclo di aggiornamento richiede anche gestione delle rimozioni. Se una procedura viene ritirata, le sue copie indicizzate, le risposte memorizzate e i riferimenti derivati devono essere riesaminati. È utile registrare quando la fonte è stata acquisita e quale sua revisione abbia prodotto ciascun passaggio. Nel nostro esempio, la sostituzione di un’istruzione di rilascio dovrebbe diventare un caso di collaudo: dopo l’aggiornamento, l’assistente deve usare la nuova procedura per il contesto previsto e mantenere quella precedente soltanto dove resta esplicitamente applicabile.
Dividere i documenti senza perdere le condizioni operative
Il recupero lavora spesso su porzioni di testo, ma una divisione puramente meccanica può separare un’istruzione dalla condizione che la rende valida. Una procedura potrebbe descrivere un comando e indicare nel paragrafo precedente che debba essere eseguito solo su un ambiente di prova. Se il contesto viene perso, il passaggio recuperato risulta incompleto. Titoli, prerequisiti, avvertenze e riferimenti alle sezioni successive dovrebbero quindi accompagnare le unità informative necessarie a comprenderne il significato.
La dimensione dei passaggi va verificata sulle domande del progetto. Porzioni molto ampie possono includere informazioni irrilevanti; porzioni troppo brevi possono rendere invisibili le dipendenze. Nell’esempio delle due versioni applicative, è utile preparare domande simili che differiscano soltanto per versione o ambiente e osservare quali testi vengano recuperati. Il confronto deve avvenire prima della generazione della risposta: se il passaggio corretto non entra nel contesto, cambiare soltanto le istruzioni del modello difficilmente risolverà il problema di selezione.
Applicare i permessi prima di fornire il contesto al modello
La somiglianza semantica non rappresenta un’autorizzazione. L’identità del richiedente deve determinare quali fonti siano recuperabili, con controlli applicati dal sistema. La guida Microsoft include il controllo degli accessi tra le difficoltà centrali di un’architettura RAG. È insufficiente recuperare tutti i documenti e chiedere poi al modello di non mostrare quelli riservati: l’informazione sarebbe già entrata nel suo contesto. I permessi devono accompagnare l’indicizzazione e la ricerca secondo il modello di sicurezza adottato.
Nel caso illustrativo, un fornitore potrebbe consultare istruzioni su un componente senza poter leggere le note degli altri progetti. Il collaudo deve provare utenti con ruoli diversi e una modifica dei privilegi nel tempo. Anche una risposta memorizzata può diventare una fonte di esposizione se viene riutilizzata per un’identità diversa o dopo una revoca. Il progetto deve definire come separare queste memorie, come invalidarle e quali informazioni conservare nei log. I controlli vanno verificati sul percorso completo, comprese anteprime, titoli dei documenti e collegamenti restituiti.
Trattare i documenti recuperati come dati, non come istruzioni fidate
Un documento può contenere testo che tenta di indirizzare il comportamento del modello, anche quando viene recuperato da una raccolta apparentemente pertinente. OWASP descrive la prompt injection indiretta attraverso contenuti esterni e chiarisce che la RAG non elimina questo rischio. Nel progetto occorre quindi separare le regole dell’assistente dal materiale consultato e limitare le capacità disponibili. Un servizio pensato per spiegare documentazione non dovrebbe acquisire implicitamente il potere di eseguire azioni perché una pagina gli suggerisce di farlo.
Il caso illustrativo permette una prova concreta: inserire in una fonte di collaudo una frase che chieda di ignorare il compito e rivelare un contenuto non autorizzato. Il risultato atteso riguarda sia la risposta sia l’assenza di accessi o azioni improprie. Filtri e istruzioni possono contribuire alla difesa, ma vanno affiancati da confini applicativi e privilegi minimi. Se in futuro vengono aggiunte funzioni operative, ciascuna richiede autorizzazioni e verifiche proprie, indipendenti dal testo generato. La documentazione recuperata non deve trasformarsi in un canale per modificare tali regole.
Verificare citazioni, lacune e domande ambigue
La presenza di una citazione non dimostra che la risposta sia sostenuta dalla fonte. Il controllo deve accertare che il passaggio citato supporti l’affermazione e che appartenga alla versione corretta. Per una procedura di rilascio, una risposta che unisce istruzioni di due versioni potrebbe apparire completa pur descrivendo una sequenza mai approvata. È utile richiedere che le condizioni mancanti vengano rese esplicite. Quando non è chiaro quale ambiente interessi all’utente, una domanda di chiarimento può essere più corretta di una risposta immediata.
La raccolta di valutazione dovrebbe contenere richieste ordinarie, domande senza risposta nelle fonti e casi con documenti in conflitto. Nell’esempio, il risultato corretto per una procedura non ancora pubblicata è segnalare il limite e indicare il referente previsto, senza inventare i passaggi mancanti. Le verifiche possono distinguere qualità del recupero, aderenza della risposta e utilità per il compito. Un unico giudizio complessivo rischia di nascondere se l’errore dipenda da una fonte assente, da una selezione sbagliata o da una sintesi non supportata.
Introdurre il servizio con un ciclo di manutenzione definito
Un pilota utile può concentrarsi su una raccolta limitata, con proprietari identificati e domande revisionate da chi conosce le procedure. Per ogni modifica a documenti, indice o modello si ripetono i casi più importanti, conservando configurazione ed esiti. Vanno osservati anche tempi di risposta, costi e frequenza dei chiarimenti richiesti. Una risposta rapida ma non verificabile non risolve il problema iniziale; una risposta corretta che arriva troppo tardi può invece richiedere una diversa organizzazione del recupero o un perimetro più circoscritto.
Il tema qui trattato riguarda l’ingegneria della conoscenza usata dai gruppi tecnici. Sul versante applicativo, l’approfondimento di Gestionale sul Web sull’evoluzione dei software gestionali con l’AI presenta un contesto distinto. Nel progetto documentale, la maturità si riconosce dalla capacità di mantenere fonti, accessi e verifiche quando il patrimonio cambia. L’assistente diventa utile se rende più semplice trovare e comprendere informazioni attendibili, lasciando visibili provenienza, condizioni di validità e limiti della risposta.
Riferimenti tecnici
Per approfondire i temi tecnici trattati:
- Microsoft: architetture RAG e controllo degli accessi alle fonti
- OWASP Gen AI: prompt injection diretta e indiretta
Analisi metodologica originale. Il gruppo e le procedure di rilascio descritti sono illustrativi; non rappresentano clienti, progetti realizzati o funzionalità dichiarate di Gestionale sul Web.
A cura della redazione tecnica SoftJob. Pubblicato il .