Knowledge Graph con Graphology
Una delle difficoltà più sottovalutate nei sistemi AI che lavorano su molti documenti non è soltanto “leggere i file”.
Il vero problema arriva dopo.
Quando i documenti diventano decine, poi centinaia, la tentazione più naturale è prendere tutto, impacchettarlo in un unico grande prompt e chiedere al modello linguistico di ragionare sull’intero blocco.
Sembra una soluzione semplice. In realtà è quasi sempre il modo più rapido per creare un collo di bottiglia.
Il prompt cresce. Il contesto diventa rumoroso. La collection recupera troppi frammenti. I file lunghi schiacciano quelli più importanti. Il modello riceve testo ridondante, informazioni non verificate e dati che non hanno ancora una gerarchia.
La soluzione più elegante, in questo caso, non è stata aumentare ancora la finestra di contesto. È stata cambiare completamente il modo di rappresentare la conoscenza.
Il punto centrale è questo: non passare centinaia di documenti all’LLM come un blocco unico, ma trasformarli prima in una mappa navigabile di fatti, evidenze, documenti e requisiti.
Questa mappa è una Knowledge Graph costruita con Graphology, mantenuta in RAM durante la sessione e usata per decidere cosa può davvero entrare nel contesto del modello.
Il limite del “prompt gigante”
Un sistema RAG tradizionale funziona così: prende una domanda, cerca i frammenti più simili in una base dati e li passa al modello.
Questo approccio funziona bene quando la risposta è contenuta in pochi passaggi. Ma in un corpus documentale ampio il problema cambia natura.
Non basta più trovare il testo simile. Bisogna capire:
- quale documento è più autorevole;
- quale dato è davvero provato;
- quale informazione è solo dichiarata;
- quali importi o valori derivano da altri valori;
- quali elementi sono in conflitto;
- quali requisiti sono completi e quali no;
- quali evidenze vanno portate nel prompt e quali devono restare fuori.
Se tutto questo viene lasciato all’LLM dentro un unico prompt enorme, il modello deve fare troppe cose insieme: leggere, selezionare, verificare, collegare, calcolare, scartare rumore e poi scrivere.
È qui che il sistema rischia di intasarsi.
La Knowledge Graph risolve il problema spostando una parte fondamentale del lavoro prima della generazione.
L’idea: leggere i documenti una volta, poi lavorare sul grafo
La logica è molto semplice da spiegare.
I documenti vengono letti una sola volta. Durante questa fase il sistema non si limita a creare un riassunto. Estrae elementi atomici e li collega tra loro.
Invece di conservare solo testo, costruisce nodi e relazioni.
Un documento non è più soltanto un file. Diventa un nodo Document.
Un dato rilevante diventa un nodo Fact.
Un estratto utile diventa un nodo Evidence, con fonte, polarità e confidenza.
Un controllo da soddisfare diventa un nodo Requirement.
Un problema, una contraddizione o una mancanza diventa un nodo Conflict o ValidationIssue.
A quel punto il sistema non deve più chiedersi: “quali centinaia di pagine devo passare al modello?”.
Può chiedersi una cosa molto più intelligente: quali percorsi del grafo sono completi, affidabili e utili per questa specifica richiesta?
Perché Graphology è una scelta brillante
Graphology è una libreria JavaScript per creare, interrogare e manipolare grafi in modo efficiente.
In questa architettura viene usato un MultiDirectedGraph: un grafo diretto, capace di gestire più relazioni tra gli stessi nodi.
Questa scelta è importante perché nel mondo reale due elementi possono essere collegati in modi diversi.
Un fatto può essere collegato a un documento perché è supportato da una fonte. Lo stesso fatto può essere collegato anche a un’evidenza testuale. Un valore può derivare da altri valori. Un requisito può essere soddisfatto da un fatto solo se quel fatto ha una prova collegata.
Il grafo diretto permette di rappresentare tutto questo in modo naturale.
Esempio semplificato:
Requirement → Fact → Evidence → Document
Questo percorso dice una cosa precisa: il requisito non è soddisfatto perché “il testo lo sembra dire”, ma perché esiste un fatto, quel fatto è supportato da un’evidenza, e quell’evidenza proviene da un documento leggibile.
È una differenza enorme.
Dal testo alla conoscenza strutturata
Il flusso funziona in più passaggi.
Prima il sistema riceve i file: possono essere file singoli oppure intere cartelle con sottocartelle.
Poi entra in gioco un primo filtro di qualità. I documenti vengono controllati per leggibilità, completezza e coerenza minima. Se qualcosa non va, il sistema non prova comunque a generare una risposta forzata: chiede integrazione, OCR migliore o documento mancante.
Quando il materiale è utilizzabile, parte il parsing. I file vengono trasformati in testo e classificati. Da qui vengono estratti dati, importi, prove e informazioni strutturate.
Il passaggio decisivo arriva subito dopo: questi elementi non vengono buttati in un prompt, ma inseriti nel grafo.
Il grafo diventa quindi una memoria operativa della sessione.
Non una memoria generica. Non un archivio permanente dei documenti. Ma una struttura volatile, costruita per ragionare in modo controllato sul corpus appena caricato.
Il grafo volatile in RAM
Uno degli aspetti più interessanti è la scelta della volatilità.
Il grafo contenente i dati del corpus vive in RAM, dentro una sessione temporanea. Ha una scadenza, un limite massimo di sessioni attive e una cancellazione esplicita.
Quando la sessione viene eliminata, il sistema non si limita a rimuovere un riferimento. Prima sovrascrive i campi sensibili presenti nei nodi, poi svuota il grafo.
Questa scelta ha due vantaggi.
Il primo è tecnico: il grafo è veloce da consultare perché resta in memoria.
Il secondo è architetturale: la base persistente rimane separata dai dati del corpus caricato. Le fonti esterne vengono recuperate in sola lettura, mentre il contenuto della sessione non viene scritto nella collection.
In altre parole: la conoscenza generale resta persistente, il corpus specifico resta volatile.
È una separazione pulita, facile da auditare e molto utile quando si lavora con documenti sensibili.
Il traversal: il cuore della riduzione del contesto
Il vero salto di qualità non è soltanto avere un grafo.
È attraversarlo nel modo giusto.
Il sistema usa percorsi tipizzati. Per esempio:
Requirement → SATISFIED_BY → Fact
Fact → SUPPORTED_BY → Evidence
Evidence → EXTRACTED_FROM → Document
Ogni arco ha un significato. Non è un collegamento generico.
Il traversal verifica se il percorso è completo e assegna un peso alle relazioni. Una prova diretta pesa più di un collegamento debole. Un estratto con alta confidenza pesa più di un’informazione incerta. Un documento con bassa qualità di parsing può ridurre l’affidabilità del percorso.
Questo permette al sistema di costruire un contesto molto più piccolo, ma molto più denso.
Il modello non riceve più “tutti i file”. Riceve una selezione ragionata:
- fatti canonici;
- prove collegate;
- estratti rilevanti;
- documenti sorgente;
- avvisi e blocchi;
- percorsi probatori completi o incompleti.
È qui che il collo di bottiglia si scioglie.
Non serve più mandare al modello centinaia di documenti. Basta passargli la parte del grafo che serve davvero.
Controlli deterministici prima dell’LLM
Un altro elemento brillante è l’uso dei controlli deterministici.
Molti sistemi AI chiedono al modello linguistico di verificare tutto: coerenza, somme, contraddizioni, provenienza dei dati, requisiti mancanti.
Qui invece una parte importante dei controlli viene fatta senza chiamare l’LLM.
Il grafo permette di rispondere a domande strutturali:
- questo fatto ha almeno una prova collegata?
- questa prova proviene davvero da un documento?
- questo requisito ha un percorso completo?
- questo valore è diretto o derivato?
- un totale deriva da addendi espliciti?
- ci sono conflitti che devono bloccare la generazione?
Queste verifiche non richiedono creatività. Richiedono struttura.
E un grafo è perfetto per questo.
Il modello linguistico entra solo dopo, quando il contesto è già stato pulito, ordinato e vincolato.
Importi, valori e provenienza atomica
Nei corpus complessi, i valori numerici sono spesso una fonte enorme di errori.
Un importo può essere presente in un documento. Un totale può essere calcolato. Un valore può essere non additivo. Un numero può comparire in una tabella ma non essere utilizzabile per la sintesi finale.
La soluzione adottata è trasformare ogni valore rilevante in un fatto autonomo.
Un valore diretto viene collegato alla sua evidenza. Un valore derivato viene collegato agli addendi. Un valore non provato resta escluso.
Questo evita un errore molto comune nei sistemi basati su LLM: il modello vede tanti numeri nel prompt e prova a interpretarli da solo.
Nel grafo, invece, un numero non è “solo testo”. È un nodo con provenienza, stato, relazione e regole di utilizzo.
Qdrant resta utile, ma non fa tutto
La base di ricerca rimane fondamentale.
Qdrant viene usato per recuperare fonti esterne pertinenti. Ma non viene confuso con il grafo.
Qdrant è ottimo per trovare frammenti simili a una query. Il grafo è ottimo per capire come i fatti del corpus sono collegati tra loro.
Sono due livelli diversi.
Il sistema recupera poche fonti esterne pertinenti, le ordina con un reranking ibrido e le combina con il contesto costruito dal grafo.
Anche qui c’è una scelta importante: il reranking può migliorare l’ordine dei candidati, ma non può trasformare un fatto non provato in un fatto valido.
La ricerca aiuta. Il grafo decide cosa è radicato.
Reranking ibrido: pertinenza, qualità e requisiti
La selezione delle fonti non è lasciata al caso.
Il reranking combina più criteri:
- pertinenza semantica;
- coerenza con il workflow selezionato;
- autorevolezza della fonte;
- collegamento con i requisiti ancora mancanti nel grafo;
- qualità e recenza del contenuto.
Questo è molto più solido di un semplice “prendo i primi risultati”.
La cosa interessante è che il grafo influenza anche il recupero: se alcuni requisiti sono incompleti, la query può essere orientata verso le fonti più utili per colmare proprio quelle lacune.
La ricerca non è più cieca. È guidata dallo stato reale del grafo.
Il ruolo dell’LLM: meno testo, più responsabilità
Alla fine il modello linguistico viene comunque usato.
Ma arriva in un momento diverso.
Non deve più leggere tutto il corpus e capire da solo cosa conta. Riceve un contesto già filtrato:
- i fatti utilizzabili;
- le evidenze collegate;
- le fonti esterne più pertinenti;
- i blocchi da rispettare;
- le parti incomplete da non trasformare in conclusioni.
Questo riduce token, costi e rumore.
Ma soprattutto riduce il rischio di allucinazione.
Se il modello introduce un dato non radicato, il sistema può respingerlo e collegare il rifiuto al grafo come conflitto. In questo modo anche l’errore del modello diventa un evento tracciabile, non un testo da accettare passivamente.
Cosa mostra il diagramma Mermaid
Il diagramma Mermaid riassume molto bene l’intera architettura.
La prima parte descrive la catena di ottimizzazione:
Documenti letti una sola volta
→ fatti strutturati riutilizzabili
→ controlli eseguiti senza LLM
→ recupero selettivo delle fonti
→ prompt ridotto
→ meno token, meno chiamate, più velocità e tracciabilità
Questa è la filosofia del sistema in una riga.
La seconda parte mostra il flusso operativo:
- scelta del workflow;
- caricamento di file o cartelle;
- quality gate documentale;
- richiesta di integrazione se il materiale non è utilizzabile;
- parsing e classificazione;
- estrazione di fatti con fonte;
- costruzione del grafo volatile in RAM;
- controlli deterministici;
- recupero selettivo di fonti pertinenti;
- creazione del contesto mirato;
- redazione assistita dal modello;
- quality gate finale;
- generazione di bozza e audit;
- download, stampa e cancellazione della sessione.
Il punto chiave è che il modello linguistico non è al centro di tutto. È un componente della pipeline.
Prima del modello c’è una struttura. Dopo il modello c’è un controllo.
Questo è il motivo per cui il sistema scala meglio.
Perché questa architettura evita il collo di bottiglia
Il collo di bottiglia nasce quando tutto viene concentrato in un solo passaggio: prompt, contesto, collection e centinaia di file.
Qui invece il lavoro viene distribuito.
Il parsing legge i documenti.
Il grafo conserva le relazioni.
I controlli deterministici validano la struttura.
Qdrant recupera solo fonti pertinenti.
Il reranking seleziona il meglio.
Il traversal produce un contesto compatto.
L’LLM ragiona su ciò che resta.
Questa separazione cambia completamente la qualità del sistema.
Non abbiamo più un modello costretto a nuotare in un mare di testo. Abbiamo un modello che riceve una mappa.
E una mappa è molto più utile di un mucchio di pagine.
Una lezione importante per chi costruisce AI documentale
Quando si lavora con molti documenti, la domanda non dovrebbe essere: “quanti token posso inserire nella finestra di contesto?”.
La domanda giusta è: “quale struttura devo costruire prima di chiamare il modello?”.
La Knowledge Graph con Graphology risponde esattamente a questa domanda.
Permette di trasformare un corpus disordinato in una rete di elementi verificabili. Permette di separare i dati persistenti da quelli volatili. Permette di interrogare il contesto invece di trascinarlo tutto nel prompt.
E soprattutto permette di usare l’LLM per ciò che sa fare meglio: ragionare e scrivere su un contesto già selezionato, non sostituirsi a un motore di validazione documentale.
Conclusione
Questa architettura dimostra un principio semplice ma potentissimo: nei sistemi AI complessi, il problema non è solo generare testo; è costruire prima una buona rappresentazione della conoscenza.
Graphology diventa il motore silenzioso che collega documenti, fatti, evidenze, requisiti e conflitti.
Il grafo volatile evita di appesantire il sistema con persistenze inutili. Il traversal riduce il contesto. I controlli deterministici tagliano chiamate superflue. Il recupero selettivo evita di riversare troppe fonti nel prompt.
Il risultato è una pipeline più veloce, più tracciabile e più controllabile.
Non un prompt gigante.
Non una collection usata come discarica semantica.
Ma una vera mappa della conoscenza, costruita prima della generazione e attraversata solo dove serve.
Ed è proprio qui che una Knowledge Graph smette di essere una buzzword e diventa architettura concreta.