RAG locale : introduction

#RAG locale: la definizione e ciò che ti aspetti

RAG significa retrieval-augmented generation, cioè generazione aumentata tramite recupero: si recuperano prima dei passaggi pertinenti da una base di documenti, poi si chiede al modello di redigere una risposta a partire da essi. Il termine locale specifica che ogni fase (lettura dei documenti, calcolo degli embedding, archiviazione, generazione) avviene sul tuo hardware. È l'uso più utile di un modello privato: domande su contratti, note, una base di conoscenze interna, con risposte che citano le fonti.

#Perché usare un RAG piuttosto che inviare tutto al modello?

Prima idea: copiare tutti i propri documenti nel prompt. Ci sono però due limiti. La finestra di contesto è limitata: 300 PDF rappresentano milioni di token, ben oltre quanto un modello locale possa accettare. E anche quando un documento riesce a essere inserito, la qualità cala: uno studio di riferimento (Liu et al., Stanford) mostra che la performance può diminuire notevolmente quando l'informazione utile si trova al centro di un lungo contesto, anche per modelli progettati per contesti lunghi. Questo fenomeno si chiama lost in the middle.

Il RAG aggira questi due problemi trasmettendo al modello solo alcuni passaggi selezionati in relazione alla domanda. Il modello legge alcune centinaia di token ben mirati invece di decine di migliaia di token poco utili, con un costo di calcolo e una latenza minori. Tutta l'abilità sta nel recuperare bene i passaggi.

Un ordine di grandezza, con un calcolo illustrativo: 300 PDF di 20 pagine, con circa 600 token per pagina, rappresentano 3,6 milioni di token, cioè centinaia di volte la finestra di 8.000 token che si imposta spesso su un modello locale. Suddivisi in passaggi di 400 token, producono circa 9.000 passaggi. Una domanda ne seleziona cinque, cioè 2.000 token: il modello legge lo 0,06% del corpus, ma lo 0,06% giusto se la ricerca ha successo.

#Il concetto in due minuti: embedding e distanza

Un embedding è una lista di numeri che rappresenta il senso di un testo. Due testi che parlano della stessa cosa hanno vettori vicini, anche se non usano le stesse parole. La documentazione di Ollama descrive gli embedding come vettori numerici che si possono memorizzare in un database vettoriale, cercare tramite la similarità del coseno o utilizzare in un RAG, con una lunghezza che dipende dal modello, tipicamente compresa tra 384 e 1024 dimensioni.

Una domanda viene trasformata in un vettore dallo stesso modello, poi confrontata con tutti i passaggi indicizzati: vengono restituiti quelli più vicini. Il punto che trae in inganno i principianti: il modello di embedding utilizzato per l'indice e quello utilizzato per le domande devono essere identici. La documentazione di LlamaIndex lo ricorda nel suo esempio di ricaricamento dell'indice: è importante utilizzare lo stesso embed_model usato per costruirlo.

#Anatomia di un RAG: due fasi

#Fase 1: l'indicizzazione, eseguita una volta per documento

1. 01
   Ingestione

   Leggere i file (PDF, Word, Markdown, HTML) ed estrarne il testo pulito. È la fase più sottovalutata.
2. 02
   Suddivisione

   Suddividere in brani abbastanza piccoli da essere precisi e abbastanza grandi da conservare il senso. Brani da 200 a 500 token sono un punto di partenza comune.
3. 03
   Embedding

   Elaborare ogni brano con il modello di embedding, ad esempio con il comando ollama run embeddinggemma o l'API /api/embed.
4. 04
   Archiviazione

   Salvare i vettori insieme al testo originale e ai metadati (nome del file, pagina, data).

#Fase 2: la richiesta, per ogni domanda

1. 01
   Embedding della domanda

   Con lo stesso modello utilizzato per l’indicizzazione.
2. 02
   Ricerca

   Trovare gli N passaggi con il vettore più vicino, usando la similarità coseno come misura.
3. 03
   Assemblaggio del prompt

   Costruire un messaggio che contenga gli estratti e l'istruzione di rispondere citando le fonti e di segnalare quando la risposta non si trova negli estratti.
4. 04
   Generazione

   Inviare questo prompt al modello locale, che redige la risposta.

#Lo stack minimo e le opzioni senza codice

Per un RAG locale funzionante bastano quattro componenti: un modello di generazione servito da Ollama, un modello di embedding, un database vettoriale e uno strato che li collega. Per il francese, scegli un modello di embedding multilingue; la pagina di Ollama ne consiglia tre (embeddinggemma, qwen3-embedding, all-minilm), e le dimensioni dei vettori restano contenute, il che permette di eseguirli su un portatile.

Per evitare di programmare, la guida sul RAG in LM Studio e quella su AnythingLLM illustrano in dettaglio ciascun percorso; la guida su NotebookLM e le alternative locali tratta la query «notebook lm rag».

#Il pipeline in Python, passo dopo passo

L'esempio qui sotto segue lo schema ufficiale del tutorial LlamaIndex con modelli locali: un lettore di directory, un modello di embedding, un modello servito da Ollama, poi un motore di interrogazione. Installa prima i pacchetti llama-index-llms-ollama e llama-index-embeddings-huggingface. Adatta i nomi dei modelli a quelli che hai scaricato.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

Settings.embed_model = HuggingFaceEmbedding(model_name="intfloat/multilingual-e5-large")
Settings.llm = Ollama(model="qwen3.5:9b", request_timeout=360.0, context_window=8000)

documents = SimpleDirectoryReader("mes_documents").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(similarity_top_k=5)

response = query_engine.query("Quelles sont les échéances du contrat Dupont ?")
print(response)
print(response.source_nodes)

La prima esecuzione calcola tutti gli embedding, operazione che richiede più o meno tempo a seconda del volume e della macchina. Per evitare di ricalcolarli tutti, salva l'indice con index.storage_context.persist, poi ricaricalo con load_index_from_storage riutilizzando lo stesso modello di embedding. Il parametro context_window limita la memoria consumata, come precisato nel tutorial.

#Le insidie che fanno fallire i primi tentativi

Una suddivisione ingenua rompe le strutture

Un taglio a metà di una tabella produce passaggi illeggibili. Usa uno strumento di segmentazione che rispetti titoli e tabelle, oppure converti prima i documenti con Docling.

La lingua dell'embedding conta

Un modello di embedding addestrato soprattutto sull'inglese recupera meno efficacemente i passaggi in francese. Scegli un modello multilingue e testalo su 10 domande reali prima di indicizzare tutto il corpus.

Un unico valore di top-k raramente è adatto

Troppo pochi passaggi impoveriscono la risposta; troppi sommergono il modello. Regola il numero in base alla natura dei documenti e verifica con domande di cui conosci la risposta.

Una cattiva ricerca produce una risposta espressa con sicurezza ma falsa

Un modello che riceve estratti non pertinenti può inventare una risposta che sembra certa. Misura innanzitutto la pertinenza degli estratti.

I PDF nascondono insidie

Doppia colonna, piè di pagina, tabelle, scansioni: una parte importante del lavoro consiste nel ripulire i dati durante l'ingestione. Un PDF scansionato richiede l'OCR prima di qualsiasi altro trattamento.

Mescolare i modelli di embedding

Indicizzare con un modello e interrogare con un altro dà risultati assurdi, senza messaggi di errore.

#Quando non usare RAG

La guida che confronta il fine-tuning e il RAG approfondisce quest'ultimo caso.

#Hardware e riservatezza: ciò che resta sul tuo sistema

In un RAG completamente locale, i documenti, i vettori e le domande rimangono sulla macchina, a condizione che ogni componente sia locale: modello di embedding servito da Ollama o caricato dal disco, database vettoriale su file o come servizio locale, modello di generazione locale. Verifica che nessun componente chiami un servizio online: un embedder o un modello cloud selezionato per errore invierebbe i tuoi passaggi all'esterno.

Dal punto di vista hardware, la componente più esigente è il modello di generazione: in Q4, un modello da 8 a 9 miliardi di parametri trova posto in circa 5 GB di memoria, oltre alla memoria necessaria per il contesto. Qui il contesto cresce perché contiene gli estratti: prevedi un margine se aumenti il numero di passaggi. L'embedding, invece, è leggero; l'indicizzazione iniziale di un corpus di grandi dimensioni resta l'operazione più lunga e viene eseguita una sola volta. La guida sui LLM senza GPU indica cosa consente ciascuna quantità di RAM.

#E dopo? I miglioramenti da apportare, in ordine

Un RAG di base risponde spesso bene a domande semplici. Per andare oltre, l'ordine più conveniente è il seguente: prima una suddivisione che rispetti la struttura, poi la ricerca ibrida (vettoriale e per parole chiave con BM25, per non perdere un termine esatto come un numero di contratto), poi un reranker che riordina i primi risultati, infine una valutazione su un insieme di circa cinquanta domande di cui conosci la risposta. Senza misurazioni, ogni cambiamento rimane un'impressione.

• Che cos'è il RAG: guida per principianti
• Strategie di divisione dei documenti
• Embedding per il francese
• RAG in LM Studio
• AnythingLLM: tutorial RAG
• Valutare un RAG con Ragas

• Fonte: embedding in Ollama
• Fonte: tutorial LlamaIndex con modelli locali
• Fonte: Lost in the Middle (Liu et al.)
• Fonte: LM Studio, Chat with Documents