motore ROE locale con Ollama

Una delle difficoltà più ricorrenti nei sistemi RAG non riguarda soltanto la capacità di trovare un testo simile alla domanda dell’utente. Il vero problema è capire quale parte del documento sia davvero utile, quale relazione abbia con le altre informazioni e quanto della risposta finale sia effettivamente supportato dalle fonti.

Quando si caricano manuali tecnici, procedure, istruzioni operative o documentazione industriale, la quantità di testo cresce rapidamente. Un sistema RAG tradizionale può recuperare alcuni chunk semanticamente vicini alla domanda e passarli al modello linguistico. Questo approccio funziona, ma spesso lascia al modello il compito più difficile: ricostruire da solo relazioni, cause, dipendenze, regole, componenti e vincoli.

Il progetto ROE locale con Ollama, nasce per superare questo limite. Non si limita a cercare pezzi di testo. Trasforma i manuali caricati in una struttura più leggibile: chunk vettoriali, ontologia di dominio, knowledge graph, fatti atomici, percorsi semantici e audit delle risposte.

In altre parole, ROE non chiede al modello AI di “leggere tutto ogni volta”. Prepara prima una mappa della conoscenza e poi, a ogni domanda, porta nel prompt solo ciò che serve davvero.

La parte più interessante è che tutto questo avviene in locale. Il motore non dipende da una pipeline cloud esterna per generare le risposte: gira sul PC dell’utente con Ollama, usa bge-m3:latest per gli embedding e gpt-oss:120b-cloud come modello linguistico per ragionare sui manuali. I chunk vengono trasformati in vettori e inseriti in Qdrant, mentre MongoDB conserva la parte documentale, ontologica e di audit.

Un sistema RAG classico segue di solito un flusso abbastanza lineare:

È un metodo efficace perché collega il modello a una base documentale esterna. Tuttavia, quando i documenti sono complessi, la somiglianza semantica non basta sempre. Due passaggi possono parlare dello stesso componente senza usare le stesse parole. Una procedura può dipendere da una regola descritta molte pagine prima. Un rischio può essere collegato a un evento, a un allarme e a una mitigazione distribuiti in punti diversi del manuale.

Qui entra in gioco l’approccio GraphRAG. Microsoft Research descrive GraphRAG come un modo per usare knowledge graph, analisi delle relazioni e retrieval strutturato per migliorare la qualità delle risposte su dati complessi. RAGraph Ontological Engine “ROE“,  applica questa logica in modo pratico: combina ricerca vettoriale e grafo semantico, senza rinunciare alla semplicità operativa di una chat.

Il principio alla base del progetto è semplice: un manuale non è solo una sequenza di paragrafi. È un insieme di entità, regole, componenti, misure, rischi, eventi e procedure.

ROE prova quindi a costruire tre livelli informativi:

Questa separazione è importante. Il testo resta sempre la fonte primaria, ma il grafo permette di orientarsi meglio. Il modello non riceve soltanto blocchi di testo grezzo: riceve anche fatti già normalizzati e percorsi logici già estratti.

È come passare da una pila di pagine a una mappa navigabile.

Quando l’utente carica un file PDF, TXT o Markdown, ROE avvia una pipeline di ingestione documentale. Il file viene letto, pulito e controllato per verificare che contenga testo realmente leggibile. Nel caso dei PDF viene usato un parser dedicato per estrarre il contenuto testuale.

Dopo questa fase il documento viene diviso in chunk sovrapposti. Nel progetto i chunk hanno una dimensione di circa 1000 caratteri con 200 caratteri di overlap. L’overlap serve a non tagliare bruscamente un concetto importante tra un segmento e l’altro.

A questo punto ogni chunk viene trasformato in embedding tramite Ollama. Nella configurazione locale del progetto il motore di embedding è bge-m3:latest. Nel file .env il modello è indicato come bge-m3, che in Ollama corrisponde al tag latest installato localmente. Il codice chiama l’endpoint locale /api/embeddings, riceve il vettore numerico del chunk e lo prepara per l’indicizzazione.

Gli embedding vengono poi salvati direttamente in Qdrant, quando l’infrastruttura Docker locale è attiva, oppure in una modalità virtuale in memoria quando Qdrant e MongoDB non sono disponibili. In pratica, il documento viene trasformato in segmenti testuali, ogni segmento diventa un vettore e quei vettori vengono caricati nella collection Qdrant rag_manuals.

Qdrant viene usato per la ricerca vettoriale, cioè per trovare i passaggi più vicini alla domanda dell’utente. MongoDB viene usato per conservare documenti, chunk, facts, nodi, archi, ontologie e audit.

Questa parte è simile a un RAG tradizionale. La differenza arriva subito dopo.

Prima di estrarre il grafo, ROE crea un’ontologia del dominio. Non parte da zero. Nel codice esiste una base ontologica universale con concetti generali come:

A questi concetti vengono associate relazioni generiche come PART_OF, REQUIRES, DEPENDS_ON, CAUSES, MITIGATES, MEASURED_BY e APPLIES_TO.

Il sistema prende poi un campione distribuito del documento, fino a 9 chunk scelti lungo tutto il manuale, e chiede al modello di aggiungere specializzazioni coerenti con quel dominio. Questo è un punto importante: non viene usato solo l’inizio del documento. Il campione distribuito permette di leggere sezioni diverse e ottenere un’ontologia più rappresentativa.

Il risultato è una specie di dizionario intelligente del manuale. Il sistema non sa solo che esistono “cose” nel testo, ma prova a capire che tipo di cose sono: componenti, parametri, allarmi, procedure, regole, misure, rischi o attori.

Una volta generata l’ontologia, ROE passa all’estrazione del knowledge graph.

Il documento viene analizzato in batch di chunk. Per ogni gruppo di testo il modello deve estrarre:

Un fatto atomico è una piccola unità di conoscenza del tipo:

Per esempio, in un manuale tecnico potrebbe essere qualcosa come:

oppure:

Ogni fatto conserva una fonte, per esempio il riferimento al chunk da cui è stato estratto. Questo rende il sistema più affidabile, perché la risposta finale non nasce da una memoria generica del modello, ma da elementi agganciati ai manuali caricati.

La cosa importante è che il knowledge graph non sostituisce il testo originale. Lo affianca. Il testo resta necessario per le citazioni e per la verifica finale, mentre il grafo aiuta a selezionare e organizzare il contesto.

Quando l’utente scrive una domanda nella chat ontologica, ROE esegue un flusso ibrido.

Prima genera l’embedding della domanda. Poi cerca nel database vettoriale i chunk più simili. Il primo passaggio recupera al massimo 4 chunk. Questo è già un segnale forte della filosofia del progetto: partire da poco contesto, ma molto mirato.

Se la ricerca è debole, cioè se non trova nulla o se il punteggio migliore è inferiore a 0,45, il sistema non aumenta il contesto alla cieca. Prima riscrive la query con un modello locale, aggiungendo formulazioni più adatte alla ricerca tecnica. Poi ripete il retrieval recuperando fino a 8 chunk.

Dopo la ricerca vettoriale entra in gioco il grafo. ROE usa la domanda e i chunk recuperati per estrarre termini rilevanti. Con questi termini seleziona:

Questi limiti sono fondamentali. Il sistema non manda al modello l’intero grafo. Manda solo una vista compatta e pertinente: pochi fatti, pochi percorsi, pochi nodi utili.

È qui che il motore diventa davvero ibrido. La risposta nasce dall’unione di:

Il prompt finale chiede al modello di rispondere usando esclusivamente le fonti fornite e il contesto ontologico estratto dagli stessi documenti.

Anche questa fase è locale. La generazione viene eseguita tramite Ollama con gpt-oss:120b-cloud, configurato come modello LLM principale. Questo modello non riceve tutto il manuale, ma solo il pacchetto informativo costruito dal motore ibrido: fonti testuali, facts e percorsi del grafo.

Il modello riceve tre blocchi principali:

La regola più importante è che ogni affermazione finale deve restare agganciata alle fonti. Se l’informazione non è presente nei manuali caricati, il sistema deve dichiararlo.

In più, ROE non si limita a generare una risposta. Chiede anche al modello di produrre claim atomici e di verificarli. Ogni claim può essere classificato come:

Vengono poi calcolate metriche come evidenceCoverage e reasoningScore. La prima indica quanto la risposta è coperta dalle evidenze. La seconda misura la coerenza del ragionamento e l’assenza di allucinazioni.

Se la copertura delle evidenze è troppo bassa, sotto il 40%, il sistema può avviare un secondo tentativo: riscrive la query, recupera più contesto, aggiorna il contesto ontologico e genera una nuova risposta.

Questo comportamento è molto diverso da un RAG che risponde comunque. ROE prova a capire quando la risposta non è abbastanza supportata.

Il risparmio di token non nasce da un trucco. Nasce da una scelta architetturale: spostare parte del lavoro dalla fase di domanda alla fase di ingestione.

In un RAG tradizionale, a ogni domanda il modello riceve diversi chunk testuali e deve ricostruire da solo il significato. Se la domanda richiede relazioni tra concetti, spesso bisogna aumentare il numero di chunk. Più chunk significano più token, più costo e più rumore.

In ROE , invece, durante l’ingestione il sistema ha già estratto ontologia, nodi, relazioni e facts. Quando arriva una domanda, non deve passare al modello tutto il materiale grezzo. Può passare una combinazione più compatta:

Questo produce un vantaggio concreto. La prima risposta usa al massimo 4 chunk testuali, quindi circa 4000 caratteri di testo sorgente, più un contesto ontologico molto più compatto. Solo se serve passa a 8 chunk. Un sistema RAG meno selettivo potrebbe inviare 10, 15 o 20 chunk per compensare l’incertezza del retrieval.

Il grafo agisce come un filtro semantico. Non aumenta il contesto: lo comprime.

Immaginiamo una domanda come:

Un RAG tradizionale potrebbe recuperare un chunk sull’allarme, un chunk sulla procedura, un chunk sulla manutenzione e altri passaggi solo parzialmente correlati. Il modello dovrebbe capire da solo se quei pezzi sono collegati.

ROE può fare qualcosa di diverso. Può recuperare i chunk più vicini, ma anche cercare nel grafo relazioni del tipo:

In questo modo il modello riceve non solo testo, ma anche una traccia di ragionamento. Non deve scoprire ogni relazione da zero. Deve verificare e spiegare ciò che il grafo ha già messo in evidenza.

La coerenza migliora perché ROE riduce tre problemi tipici dei sistemi RAG.

Il primo è il rumore. Recuperare troppi chunk può confondere il modello. Un contesto lungo non è sempre un contesto migliore. Se dentro ci sono passaggi simili ma non pertinenti, il modello può mescolare informazioni.

Il secondo è la perdita delle relazioni. La ricerca vettoriale trova somiglianze, ma non rappresenta bene dipendenze, cause, vincoli e collegamenti tra entità. Il knowledge graph serve proprio a mantenere queste relazioni esplicite.

Il terzo è l’assenza di controllo. ROE conserva un audit completo della domanda: chunk recuperati, facts usati, percorsi KG, claim, copertura delle evidenze e score di ragionamento. L’utente può quindi vedere perché il sistema ha risposto in quel modo.

Questa trasparenza è essenziale nei manuali tecnici. Non basta una risposta plausibile. Serve una risposta verificabile.

ROE non espone solo una chat. Offre anche strumenti per osservare e correggere la conoscenza estratta.

La vista del grafo permette di esplorare nodi e relazioni in modo visuale. Il Facts Composer permette di cercare, modificare o rimuovere fatti atomici. L’Audit Trail conserva lo storico delle interrogazioni con le metriche di copertura e ragionamento.

Questo è importante perché un motore semantico non deve essere una scatola nera. Deve permettere all’utente di capire cosa è stato estratto, quali fonti sono state usate e quali connessioni hanno guidato la risposta.

In questo senso ROE segue la stessa logica delle mappe interattive: non visualizza il grafo solo per estetica, ma per rendere navigabile una struttura complessa.

Un altro aspetto rilevante è l’uso di componenti locali. Il progetto è configurato per lavorare con Ollama come provider AI, MongoDB per la persistenza e Qdrant per il vector search. Se i servizi locali non sono disponibili, il sistema può funzionare in modalità virtuale in memoria.

Nel progetto analizzato la configurazione locale è molto chiara:

Questa scelta cambia il significato del progetto. ROE non è soltanto un’interfaccia sopra un servizio remoto. È un motore che lavora sulla macchina dell’utente, con un modello di embedding gestito da Ollama, un modello linguistico invocato tramite Ollama, un database vettoriale locale e una base documentale controllata.

Questo rende l’architettura adatta a sperimentazioni on-premise, scenari prototipali e ambienti in cui i manuali tecnici non devono necessariamente uscire dall’infrastruttura controllata.

Naturalmente il risparmio di token va letto correttamente. ROE  non elimina il costo dell’AI. Durante l’ingestione usa il modello per creare ontologia, knowledge graph e facts. Ma questo costo viene pagato una volta per documento e poi riutilizzato nelle domande successive.

È un cambio di prospettiva: meno ragionamento ripetuto a ogni query, più conoscenza strutturata riutilizzabile. E soprattutto, più controllo: l’utente sa quali modelli sta usando, dove vengono generati gli embedding e dove vengono conservati vettori, facts e audit.

Come ogni sistema GraphRAG, anche ROE dipende dalla qualità dell’estrazione iniziale. Se il modello estrae facts incompleti o relazioni imprecise, il grafo può contenere rumore. Per questo la presenza del Facts Composer è utile: permette di correggere manualmente la conoscenza documentale.

Un altro limite riguarda i documenti scansionati o poco leggibili. Se il testo non viene estratto bene dal PDF, anche embedding, ontologia e grafo ne risentono.

Infine, il knowledge graph non sostituisce la fonte originale. Deve sempre restare agganciato ai chunk e alle citazioni. ROE infatti mantiene questa distinzione: il grafo orienta, ma il testo documentale verifica.

ROE è un motore di ricerca ibrido perché unisce due modi diversi di trovare conoscenza.

Da una parte usa la ricerca vettoriale, utile per individuare rapidamente i passaggi testuali più vicini alla domanda. Dall’altra usa un’ontologia semantica e un knowledge graph per rappresentare entità, fatti, regole e relazioni.

Il risultato è un sistema che non si limita a recuperare testo, ma costruisce una mappa del contenuto dei manuali. Questa mappa permette di ridurre i token inviati al modello, migliorare la coerenza delle risposte e rendere il processo più verificabile.

Il punto più interessante è proprio questo: il risparmio non nasce dal dare meno informazioni al modello, ma dal dargli informazioni migliori. Meno testo grezzo, più conoscenza strutturata. Meno contesto ridondante, più relazioni utili. Meno tentativi alla cieca, più audit e controllo.

La scelta di usare Ollama con bge-m3:latest per gli embedding e gpt-oss:120b-cloud per la generazione rende il progetto ancora più interessante, perché porta questa logica GraphRAG dentro una soluzione locale, controllabile e riproducibile sul proprio PC.

In un contesto in cui i manuali tecnici diventano sempre più lunghi e complessi, un motore come ROE rappresenta un passaggio importante: dalla ricerca per somiglianza alla ricerca dentro grafi della conoscenza.

Questo articolo è stato sviluppato a partire dai miei appunti personali, con l’ausilio dell’intelligenza artificiale per riorganizzare i contenuti, rendere più chiara la struttura e trasformare le note iniziali in una guida più leggibile e coerente per tutti.