Chat RAG con Documenti Locali e Foundry

Questo progetto implementa un sistema RAG (Retrieval-Augmented Generation) completo che permette di conversare con i propri documenti (.pdf, .docx, .xlsx, .txt) utilizzando modelli linguistici in esecuzione interamente sul proprio computer, grazie a Foundry.

Il sistema è ottimizzato per funzionare su CPU, utilizzando tecniche come la ricerca ibrida e il reranking parallelizzato per massimizzare la pertinenza delle risposte.

✨ Funzionalità Principali

• Supporto Multi-Formato: Ingerisce e processa file .pdf, .docx, .xlsx e .txt.
• Ricerca Ibrida: Combina la ricerca vettoriale (semantica, per significato) con la ricerca sparse TF-IDF (per parole chiave) per un recupero delle informazioni più robusto.
• Reranking di Precisione: Utilizza un modello Cross-Encoder per riordinare i risultati della ricerca e fornire al modello LLM solo i contesti più pertinenti.
• Ottimizzato per CPU: Sfrutta il multiprocessing per parallelizzare i carichi di lavoro più intensi e velocizzare le operazioni.
• 100% Locale e Privato: Nessun dato lascia mai il tuo computer. I tuoi documenti e le tue conversazioni rimangono private.
• Configurabile e Portabile: Facilmente configurabile tramite una sezione dedicata nel codice e progettato per funzionare su qualsiasi macchina senza modifiche ai percorsi.

⚙️ Architettura del Sistema

Il flusso di lavoro del progetto è il seguente:

1. Ingestione: I documenti nella cartella documenti/ vengono letti e divisi in "chunk" (pezzi di testo).
2. Indicizzazione:
   • Un modello di embedding (multilingual-e5-base) trasforma ogni chunk in un vettore numerico.
   • I vettori vengono salvati in un indice Faiss per una ricerca ultra-veloce.
   • Viene creato anche un indice TF-IDF per la ricerca basata su parole chiave.
3. Ciclo di Chat:
   • L'utente inserisce una domanda.
   • Il sistema esegue una ricerca ibrida negli indici per trovare i chunk più rilevanti.
   • Un modello di reranking (bge-reranker-base) riordina questi chunk per pertinenza.
   • I chunk migliori vengono inseriti in un prompt insieme alla domanda originale.
   • Il prompt viene inviato a Foundry, che ospita il modello LLM (Phi-3.5-mini).
   • Il modello genera una risposta basata esclusivamente sul contesto fornito.
   • La risposta viene mostrata all'utente.

---

🚀 Guida all'Installazione e Avvio

Segui questi passaggi attentamente per configurare l'intero ambiente da zero.

Prerequisiti

• Python 3.8 o superiore. Puoi verificarlo aprendo un terminale e digitando python --version.
• pip (il gestore di pacchetti di Python), che solitamente è incluso con Python.

Fase 1: Configurazione del Progetto Python

Questa fase prepara l'ambiente per eseguire lo script principale.

1. Clona o Scarica il Progetto Se hai git, clona il repository. Altrimenti, scarica lo ZIP e scompattalo in una cartella a tua scelta.

2. Crea un Ambiente Virtuale È una best practice fondamentale per isolare le dipendenze del progetto. Apri un terminale nella cartella principale del progetto (rag_foundry_finale) ed esegui:

   python -m venv venv

   Questo creerà una cartella venv contenente un'installazione isolata di Python.

3. Attiva l'Ambiente Virtuale Devi attivarlo ogni volta che lavori al progetto.

   • Su Windows (cmd.exe):

     .\venv\Scripts\activate

   • Su Windows (PowerShell):

     .\venv\Scripts\Activate.ps1

   • Su macOS e Linux:

     source venv/bin/activate

   Vedrai (venv) apparire all'inizio della riga del terminale.

4. Installa le Dipendenze Python Con l'ambiente attivo, installa tutte le librerie necessarie con un solo comando, utilizzando il file fornito:

   pip install -r requirements.txt

Fase 2: Configurazione di Foundry e del Modello LLM

Questa fase installa il server locale che ospiterà il nostro modello di linguaggio.

1. Installa Foundry Nel terminale (con l'ambiente venv sempre attivo), esegui:

   pip install nlm-foundry

2. Scarica il Modello LLM Useremo Phi-3.5-mini-instruct, un modello potente e leggero. Scaricalo con questo comando:

   foundry model download Phi-3.5-mini-instruct-generic-cpu:1

   Il download potrebbe richiedere alcuni minuti a seconda della tua connessione. Il modello verrà salvato in una cache locale di Foundry.

Fase 3: Avvio e Utilizzo del Sistema

Per funzionare, il sistema necessita di due terminali aperti contemporaneamente (con l'ambiente venv attivo in entrambi).

Terminale 1: Avvia il Server Foundry

1. In questo terminale, avvia il server del modello. È fondamentale specificare la porta corretta (7317) per farla corrispondere a quella configurata nello script Python.

   foundry model run Phi-3.5-mini-instruct-generic-cpu:1 --port 7317

2. Attendi il caricamento. Quando vedi un messaggio simile a questo, il server è pronto e in ascolto: 🟢 Service is Started on http://1227.0.0.1:7317/, PID ...!
3. Lascia questo terminale aperto per tutta la durata della sessione.

Terminale 2: Avvia lo Script RAG

1. Aggiungi i tuoi Documenti Sposta tutti i file (.pdf, .docx, etc.) con cui vuoi chattare all'interno della cartella documenti/.

2. Esegui lo Script Principale In questo secondo terminale, naviga fino alla cartella script/ ed esegui il file Python:

   python script/main.py

   • La prima volta, lo script eseguirà una lunga indicizzazione dei documenti. Sii paziente.
   • Le volte successive, caricherà l'indice esistente e si avvierà molto più velocemente.

3. Inizia a Chattare! Una volta che vedi il messaggio 💬 Chat RAG (Foundry Locale), puoi iniziare a fare domande sui tuoi documenti. Digita exit per terminare.

---

🔧 Personalizzazione

La maggior parte dei parametri chiave (modelli, dimensione dei chunk, URL di Foundry) si trova nella sezione CONFIGURAZIONE GLOBALE all'inizio del file rag_foundry_chat_finale.py. Puoi modificarli lì per sperimentare.

📂 Struttura del Progetto

rag_foundry_finale/
├── 📂 documenti/              <-- Metti qui i tuoi file
│   └── (esempio.pdf)
├── 📂 script/
│   ├── 📜 rag_foundry_chat_finale.py  <-- Lo script principale
│   └── 📂 index_data/          <-- Creata automaticamente per gli indici
├── 📜 README.md                 <-- Questo file
└── 📜 requirements.txt          <-- Lista delle dipendenze Python

⚠️ Risoluzione dei Problemi Comuni

• Errore di Connessione (Connection refused, WinError 10061):

  • Hai avviato il server Foundry nel primo terminale?
  • Hai usato il comando foundry model run con --port 7317?

• Timeout (Read timed out):

  • Il tuo computer sta lavorando duramente per generare la risposta. Questo è normale per le CPU.
  • Soluzione: Prova a ridurre il parametro TOP_CONTEXT a 2 o 3 nello script per inviare meno contesto al modello.

• Risposte Imprecise o Errate:

  • La qualità dei documenti è fondamentale. PDF con tabelle complesse, colonne o testo scansionato possono essere letti male.
  • Prova a porre domande più specifiche e dettagliate.