Intermedio 18 minRAG

PrivateGPT v2: chatbot per documenti 100% privato

PrivateGPT v2 è un chatbot per documenti 100% privato per dialogare con i propri file PDF, Word e Markdown senza che un solo byte esca dalla macchina. La v2 ha abbandonato il suo motore LLM integrato per affidarsi a Ollama: si mantiene la qualità di un RAG ben fatto, si beneficia di tutti i modelli disponibili tramite Ollama e si semplifica radicalmente lo stack. Questa guida copre l'installazione, la connessione a Ollama e tre casi d'uso professionali concreti (risorse umane, ambito giuridico e contabilità).

Di Mohamed Meguedmi·Agg. 2026-08-27·Testato su Windows, macOS e Linux

#Perché PrivateGPT v2 per un chatbot con documenti locali

La necessità è comune: poter porre domande in linguaggio naturale a un corpus di documenti interni (contratti, buste paga, fatture, verbali) senza inviare questi dati a OpenAI, Anthropic o Google. È esattamente l'obiettivo di PrivateGPT fin dalla prima versione, uscita nel 2023.

La v2 del progetto ha fatto una scelta netta: niente più motore LLM integrato, niente più gestione interna della quantizzazione. Al loro posto, PrivateGPT v2 delega la generazione a un backend esterno — Ollama nella maggior parte dei casi. Questo rende il progetto molto più facile da mantenere e dà accesso all'intera libreria di modelli Ollama (Qwen, Gemma, Granite, Mistral, ecc.) senza configurazioni specifiche.

100% locale
Tutto gira sulla tua macchina. Nessuna telemetria, nessuna chiamata in uscita una volta scaricati i modelli.
UI Gradio inclusa
Un'interfaccia web si apre su localhost, pronta per chattare con i tuoi documenti — non serve mettere insieme un front-end.
API compatibile con OpenAI
Il server PrivateGPT offre anche endpoint REST simili al formato OpenAI, utili se vuoi integrarlo in un'app personalizzata.
Formati supportati
PDF, DOCX, PPTX, MD, TXT, HTML, EPUB, CSV e diversi altri attraverso i loader LlamaIndex sottostanti.
i
Architettura a due blocchi
PrivateGPT v2 = pipeline RAG (chunking, embeddings, vector store, retrieval, prompt assembly) + UI Gradio. Ollama = motore di inferenza LLM. I due comunicano localmente tramite HTTP sulla porta 11434.

#Prerequisiti

Il kit RAG Locale

I tuoi documenti, la tua IA: un RAG locale affidabile sui tuoi PDF, sulle tue note e sulle tue email — senza inviare nulla nel cloud.

  • Spazio online a vita
  • PDF + file
  • Aggiornamenti a vita
Il kit RAG Locale →o tutti i kit a vita — 49 € →
Python 3.11
PrivateGPT v2 supporta ufficialmente solo Python 3.11. Con 3.12+, alcune dipendenze continuano a non funzionare.
Poetry
Il progetto utilizza Poetry per gestire le dipendenze con extras (ui, llms-ollama, embeddings-ollama, vector-stores-qdrant).
Ollama installato e attivo
Daemon Ollama raggiungibile all'indirizzo http://localhost:11434. Se non l'hai, installalo prima — l'installazione richiede 3 minuti.
Almeno 8 GB di RAM
16 GB per lavorare comodamente. Se carichi un modello 8B–9B Q4 in VRAM tramite Ollama, considera altri 5–7 GB di memoria sulla GPU.
GPU consigliato (opzionale)
Una RTX 3060 12 GB o superiore permette di utilizzare modelli 8B–14B con un tempo di risposta adeguato. Senza GPU, rimani su un 3B (Granite 4.2 3B o Qwen 3.5 2B).
→
Non hai installato Ollama?
Segui prima la nostra guida di installazione di Ollama per il tuo sistema operativo, poi torna qui. PrivateGPT v2 presuppone che il comando "ollama run" funzioni già.

#1. Installare PrivateGPT v2

Il progetto è ospitato su GitHub a zylon-ai/private-gpt. Si clona, si installa Poetry se non è già presente, poi si installano le dipendenze con gli extras corrispondenti al backend scelto.

Clonare il repo
git clone https://github.com/zylon-ai/private-gpt.git
cd private-gpt
Installare Poetry (se assente)
curl -sSL https://install.python-poetry.org | python3 -
# Ajoutez ~/.local/bin au PATH si ce n'est pas déjà fait
Installare PrivateGPT con gli extra Ollama
poetry install --extras "ui llms-ollama embeddings-ollama vector-stores-qdrant"

Questo comando installa quattro gruppi di extra: l'interfaccia Gradio, il client LLM Ollama, il client di embedding Ollama e Qdrant come database vettoriale locale incorporato. L'installazione dura da 5 a 15 minuti a seconda della tua connessione — ci sono molte dipendenze scientifiche (numpy, scipy, transformers).

!
Python 3.12 e 3.13: attenzione
Al momento in cui queste righe vengono scritte, le build di alcune dipendenze native (soprattutto llama-index e i componenti tokenizers) non sono tutte pubblicate per 3.12+. Se Poetry ti restituisce errori di compilazione, crea un venv Python 3.11 dedicato: "pyenv install 3.11.9 && pyenv local 3.11.9".

#2. Configurare Ollama come backend per LLM ed embedding

PrivateGPT v2 utilizza un sistema di profili YAML nella cartella settings/. Il profilo ollama si attiva tramite la variabile d'ambiente PGPT_PROFILES.

Prima di tutto, si scaricano i due modelli necessari: un modello di generazione e un modello di embedding. Per il francese, Qwen 3.5 9B è una buona scelta predefinita nel 2026 come LLM (6,6 GB, 256k di contesto, licenza Apache 2.0), e nomic-embed-text rimane un'ottima scelta per embedding multilingue leggeri.

Preparare i modelli in Ollama
# LLM de génération
ollama pull qwen3.5:9b

# Modèle d'embeddings (137M, ~280 Mo)
ollama pull nomic-embed-text

Si verifica poi il file settings/settings-ollama.yaml fornito nel repo. Deve puntare ai nomi corretti dei modelli e all'URL corretta di Ollama :

settings/settings-ollama.yaml
llm:
  mode: ollama
  max_new_tokens: 512
  context_window: 8192

embedding:
  mode: ollama

ollama:
  llm_model: qwen3.5:9b
  embedding_model: nomic-embed-text
  api_base: http://localhost:11434
  embedding_api_base: http://localhost:11434
  request_timeout: 120.0

vectorstore:
  database: qdrant

qdrant:
  path: local_data/private_gpt/qdrant
→
Finestra di contesto
context_window: 8192 è un compromesso ragionevole per iniziare con Qwen 3.5 9B (che può arrivare a 256k). Su una GPU con più VRAM, passa a 16384 o 32768 per elaborare documenti più lunghi senza suddividerli troppo. Attenzione: la VRAM utilizzata dalla cache KV aumenta rapidamente.

#3. Avviare il server e l'interfaccia utente

  1. 01
    Verificare che Ollama sia in esecuzione
    Digita "ollama list" in un terminale. Se il comando risponde con l'elenco dei modelli, il daemon è attivo. Altrimenti, avvia "ollama serve" in un terminale separato.
  2. 02
    Attivare il profilo ollama
    Nel terminale in cui avvierai PrivateGPT, esporta la variabile PGPT_PROFILES=ollama. Questo indica al progetto di caricare settings-ollama.yaml sovrapponendolo a settings.yaml.
  3. 03
    Avviare il server
    Dalla directory radice del repo, esegui "PGPT_PROFILES=ollama make run". Il server si avvia sulla porta 8001 e Gradio apre l'interfaccia allo stesso indirizzo.
  4. 04
    Aprire l'UI
    Vai su http://localhost:8001 nel tuo browser. Arrivi su un'interfaccia chat con un pannello laterale per caricare documenti.
Comando di avvio
PGPT_PROFILES=ollama make run

Al primo avvio, vedrai nei log che PrivateGPT contatta Ollama per verificare che i modelli dichiarati siano disponibili. Se manca un modello, il server si arresta con un messaggio esplicito: scarica il modello mancante con ollama pull, poi riavvia.

#4. Indicizzare i propri documenti

L'interfaccia Gradio offre una scheda "Ingest" in cui puoi trascinare e rilasciare i tuoi file. Dietro le quinte, PrivateGPT suddivide ogni documento in blocchi (per impostazione predefinita ~1024 token con una sovrapposizione di 200), calcola gli embedding tramite Ollama e memorizza tutto in Qdrant.

PDF
Testo estratto tramite pypdf. I PDF scansionati (contenenti solo immagini) non vengono sottoposti a OCR — usa uno strumento come ocrmypdf prima dell'ingestione.
DOCX / PPTX
Supportati nativamente dai loader LlamaIndex. Tabelle ed elenchi vengono preservati come testo semplice.
Markdown / TXT / HTML
Indicizzazione immediata: in pratica, è il formato che funziona meglio per il RAG.
CSV
Ogni riga diventa un chunk. Utile per basi di FAQ o estratti di dati aziendali.
!
Tempo di indicizzazione da mettere in conto
L'ingestione chiama Ollama per calcolare gli embedding, documento per documento. Usando solo la CPU, considera circa 5 secondi per pagina di PDF. Su GPU, è quasi istantanea. Per acquisire 500 PDF, prevedi un ampio margine di tempo e avvia l'elaborazione in batch tramite l'API anziché con il drag-and-drop.
Acquisizione in batch tramite lo script CLI
# Depuis la racine du repo private-gpt
python scripts/ingest_folder.py /chemin/vers/mes/documents \
  --watch  # surveille en continu les nouveaux fichiers

#Casi d'uso professionali concreti

#Risorse umane: interrogare le buste paga e i contratti collettivi

Caso tipico: un ufficio HR con 200 buste paga mensili archiviate in PDF, più il contratto collettivo del settore (spesso oltre 100 pagine). PrivateGPT v2 permette a un collaboratore HR di porre domande del tipo "Qual è il coefficiente della signora Dupont nel 2025?" o "Cosa dice il contratto collettivo sui giorni di permesso per un figlio malato?".

Modello consigliato
Qwen 3.5 9B Q4 basta per l'estrazione di informazioni fattuali. Per l'interpretazione giuridica della convenzione, passa a Mistral Small 24B (buono in francese, 14 GB) o Qwen 3.8 27B (18 GB, 262k di contesto), se la VRAM lo permette.
Suddivisione
Per le buste paga (1 pagina), un chunk = un documento. Per la convenzione, il chunking per sezione (titolo H2/H3) funziona meglio del chunking per token.
Privacy
È proprio in questo caso che PrivateGPT v2 fa la differenza: le buste paga non dovrebbero mai passare attraverso un servizio cloud, nemmeno in modalità "aziendale".

#Giuridico: analizzare un portafoglio di contratti

Caso tipico: un ufficio legale con alcune centinaia di contratti con clienti/fornitori in PDF, a volte scansionati. Le domande più comuni: "Quali contratti scadono nei prossimi 6 mesi?", "Quale clausola di risoluzione si applica al contratto ACME?", "Quali contengono una clausola di esclusiva?".

Pre-elaborazione
Avvia ocrmypdf sui documenti scansiti prima dell'ingestione. Senza OCR, questi PDF non sono visibili per il retrieval.
Modello consigliato
Mistral Small 24B o Qwen 3.8 27B per la qualità del ragionamento giuridico in francese. Qwen 3.5 9B basta per la sola ricerca.
Prompt di sistema
Definisci un prompt di sistema che imponga di citare il nome del contratto e il numero della clausola in ogni risposta: altrimenti il modello tende a sintetizzare senza citare le fonti.
i
Verificare sempre le fonti
L'interfaccia Gradio di PrivateGPT v2 mostra i chunk recuperati sotto la risposta. Per un uso giuridico serio, considera le risposte come spunti e verifica sistematicamente il passaggio originale — un RAG è una ricerca assistita, non un parere giuridico automatico.

#Contabile: interrogare una cartella di fatture ed estratti conto

Caso tipico: uno studio di contabilità che vuole interrogare un corpus di fatture dei fornitori e di estratti conto bancari di un cliente (PDF + CSV). Domande previste: "Qual è il totale delle fatture Free Mobile nel 2025?", "C'è una fattura del fornitore X ancora da pagare?".

Limite da conoscere
Il RAG non aggrega di per sé: recupera i passaggi pertinenti, ma non calcola le somme in modo perfetto su grandi volumi di dati. Per un'analisi rigorosa, esporta il CSV delle fatture in uno strumento dedicato e usa PrivateGPT per il contesto qualitativo.
Formato da preferire
I CSV di contabilità vengono indicizzati riga per riga: va bene per cercare singole voci, ma non per i calcoli. Allega un PDF di sintesi per ogni mese se vuoi che il LLM abbia una visione d'insieme.
Modello
Qwen 3.5 9B (anche in Q8, 11 GB) è molto solido con i numeri e nella lettura di tabelle rispetto a un piccolo modello da 3B. Se hai una RTX 4070 da 12 GB o superiore, è la scelta predefinita qui.

#Risoluzione dei problemi comuni

"Connection refused" all'avvio
Il daemon Ollama non è avviato. Verifica con "curl http://localhost:11434" — devi vedere "Ollama is running".
Risposte molto lente
O Ollama gira sulla CPU (verifica con "ollama ps" — colonna PROCESSOR), oppure il valore di context_window è troppo alto. Riducilo a 4096 per fare una prova.
"Model not found"
Il nome del modello in settings-ollama.yaml deve corrispondere esattamente a un modello elencato da "ollama list". Attenzione ai tag di quantizzazione: qwen3.5:9b ≠ qwen3.5:9b-q8_0.
Embedding diversi tra ingestione e richiesta
Se cambi il modello di embedding dopo un'ingestione, devi reindicizzare. Elimina local_data/private_gpt/qdrant/ e riesegui l'ingestione.
Interfaccia Gradio non accessibile
Se sei su una macchina remota, avvia con "PGPT_PROFILES=ollama python -m private_gpt" e riconfigura l'host in settings.yaml (server.host: 0.0.0.0).

#Per approfondire

PrivateGPT v2 è un ottimo punto di partenza per il RAG documentale locale, ma è solo un tassello. Alcune strade per andare oltre:

RAG senza scrivere codice con Open WebUI o AnythingLLM
Se PrivateGPT ti sembra pesante da installare (Poetry, Python 3.11), Open WebUI offre un'esperienza RAG simile, più semplice da deployare in Docker.
Embeddings francesi performanti
nomic-embed-text fa il suo lavoro, ma modelli specializzati in francese come Solon o BGE-M3 danno risultati migliori su contenuti giuridici o amministrativi francesi.
Strategie di chunking avanzate
Il chunking per sezione (intestazioni markdown, struttura DOCX) supera ampiamente il chunking con un numero fisso di token sui corpus strutturati — un miglioramento della pertinenza facile da ottenere.
Questa guida ti è stata utile?

Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.