Questa app fornisce un sistema completo di Retrieval-Augmented Generation (RAG) multimodale che permette sia di creare un contesto basandosi su manuali in formato PDF sia, dato un contesto, di fornitura di risposte intelligenti a domande relative al manuale. Questo sistema combina l'elaborazione di testo e immagini con la ricerca vettoriale e Large Language Models (LLMs) per rispondere in maniera chiara e precisa alle domande poste (sia in forma di testo che di immagini).
- Architettura del Sistema
- 1. Backend Pipeline
- 2. Chatbot App
- 3. Gestione della Configurazione
- 4. Calcolo delle Metriche
- Getting Started
- Struttura del progetto
- Creazione di immagine e container tramite docker
Il sistema è composto da quattro componenti principali:
- Backend Pipeline - Insieme di classi per l'elaborazione di documenti PDF ed il popolamento del database vettoriale per la ricerca semantrica
- App Chatbot Streamlit - Interfaccia utente interattiva che permette di ricevere risposte precise alle domande poste
- Gestione della Configurazione - File di configurazione per la scelta degli LLM e contesti da utiizzare
- Calcolo delle Metriche - Script che permette di valutazione le prestazioni dell'architettura progettata
La backend pipeline (main_backend_pipeline.py) è il motore principale che gestisce la lettura di documenti PDF, l'elaborazione di testo/immagini, la generazione di embedding e il popolamento del database vettoriale.
Posizione: main_backend_pipeline.py
Scopo: Orchestrare l'intero flusso di elaborazione, dall'estrazione dei dati dal PDF fino al popolamento del database vettoriale.
Metodi principali:
extract_pdf()- Estrae testo e immagini dai documenti PDFprocess_and_chunk()- Processa il testo con riassunto tramite LLM e genera gli embeddingpopulate_vector_db()- Crea le collection e carica i dati all'interno del database vettoriale Qdrantrun_full_pipeline()- Esegue il workflow completo della pipelinecreate_query_interface()- Crea un'interfaccia di query per il database popolato
Classe: PDFExtractor
Funzionalità:
- Estrae testo e immagini da documenti PDF (utilizza la libreria
pymupdf4llm) - Pre-processa le pagine del PDF e prepara il testo alla vettorizzazione
- Salva le immagini estratte
Metodi Chiave:
extract_text_and_images_from_pdf()- Metodo principale di estrazionepage_preprocessing()- Pulizia e normalizzazione del testovisualize_bounding_boxes_save_images()- Elaborazione immagini con visualizzazione dei bounding box (opzionale)
Classe: Parser_and_chunker
Funzionalità:
- Processa il testo estratto utilizzando un LLM per la creazione di riassunti
- Genera embedding di testo e immagini (utilizza la classe EmbeddingModel che gestisce la creazione di embedding)
- Converte e memorizza gli embedding
Metodi Chiave:
chunk_text()- Suddivisione del testo in chunk per pagina (elabora il testo della pagina riassumendo il contenuto tramite LLM)generate_text_embeddings()- Generazione degli embedding di testogenerate_image_embeddings()- Generazione degli embedding di immagini con integrazione dei caption nel testo della pagina
Classe: VDB_client
Funzionalità:
- Gestisce le operazioni sul database vettoriale Qdrant
- Crea collezioni con più campi vettoriali (testo, immagine)
- Inserisce e recupera i dati dal database
- Supporta la ricerca multimodale
Metodi Chiave:
create_collection()- Crea collezioni vettoriali con configurazioni specificheload_into_collection()- Inserisce i dati processati nelle collezionisearch_collection()- Esegue ricerche multimodali sulla collezionecheck_existing_collections()- Elenca le collezioni disponibili
Classe: EmbeddingModel
Funzionalità:
- Genera embedding di testo (Utilizza la libreria SentenceTransformers)
- Gestisce embedding sia di testo che di immagini (as esempio usando modelli CLIP)
- Selezione automatica del dispositivo (CUDA, CPU)
Metodi Chiave:
generate_text_embeddings()- Generazione embedding di testogenerate_image_embeddings()- Generazione embedding di immagini con pre-elaborazioneretrieve_model_size()- Restituisce la dimensione degli embedding
Classe: LLMClient
Funzionalità:
- Supporta diversi provider di LLM (Ollama, OpenAI)
- Gestisce il contesto della chat e la cronologia delle conversazioni
- Gestisce la comunicazione con le API e la gestione degli errori
- Fornisce un’interfaccia unificata per i diversi modelli
Metodi Chiave:
generate()- Metodo principale di generazione del testoreset_context()- Cancella la cronologia della conversazione
Classe: CaptionGenerator
Funzionalità:
- Genera didascalie (caption) di immagini tramite modelli BLIP
- Traduce le didascalie dall’inglese all’italiano
- Si integra con LLM per i servizi di traduzione
- Gestisce l’elaborazione e validazione delle immagini
Metodi Chiave:
describe_images_with_blip_translated()- Generazione di caption e traduzione
Classe: Multimodal_query_rag
Funzionalità:
- Esegue il recupero multimodale dal database vettoriale
- Genera risposte contestualizzate utilizzando le informazioni recuperate
- Gestisce sia query testuali che visuali (immagini)
- Ottimizza i prompt per migliorare i risultati sia della ricerca nel database sia per una maggiore chiarezza e precisione delle risposte
Metodi Chiave:
search_VDB_client()- Ricerca vettoriale multimodalegenerate_answer()- Generazione della risposta con contestopreprocessing_prompt()- Miglioramento della query per un recupero più efficace
File: chatbot.py
Scopo: Interfaccia web interattiva per interrogare il sistema RAG multimodale. (Utilizza Streamlit)
- Sidebar per la Configurazione: Selezione della collezione, regolazione della dimensione del contesto, attivazione/disattivazione visualizzazione immagini
- Domanda tramite Form: Previene il ricaricamento automatico durante la digitazione
- Feedback in Tempo Reale: Indicatori di avanzamento durante l'elaborazione
- Query Testuali: Domande in linguaggio naturale sui contenuti del documento
- Query su Immagini: Upload di immagini per la ricerca di similarità visiva
- Citazioni delle Fonti: Riferimenti alle pagine e punteggi di confidenza
- Visualizzazione Immagini: Mostra immagini rilevanti estratte dal documento
- Metriche di Prestazione: Informazioni sul tempo di risposta in tempo reale
- Selezione Collezione: Scelta tra le collezioni disponibili nel database vettoriale
- Dimensione Contesto: Numero regolabile di documenti recuperati (3-10)
- Visualizzazione Immagini: Attiva/disattiva la visualizzazione delle immagini correlate
- Persistenza della Sessione: Mantiene le preferenze utente tra una query e le precedenti
- Metriche Temporali: Tempo di recupreo del contesto e di interrogazione dell'LLM
- Tempi End-to-End: Misurazione del tempo totale di risposta
- Logging: Salvataggio automatico di query e metriche in file JSON
- Inizializzazione Modelli: Carica i modelli di embedding e il client del database vettoriale
- Elaborazione Query: Gestisce input sia testuali che di immagini
- Ricerca Vettoriale: Recupera i documenti rilevanti dal database
- Generazione Risposta: Utilizza l’LLM per sintetizzare le risposte
- Formattazione Risposta: Struttura l’output con fonti e metadati
- Raccolta Metriche: Registra i dati sulle prestazioni per l’analisi
Posizione: config.py
Scopo: Gestione centralizzata della configurazione con caricamento basato sull'ambiente.
- Ambiente Locale: Carica la configurazione dal file
.env - Ambiente Cloud: Prevede un interfaccia per l'integrazione con vault di segreti (OCI, AWS, Azure)
Elaborazione Documenti:
PDF_PATH- Percorso verso il documento PDF da elaborareSAVE_IMAGES- Se salvare le immagini estratte durante il processamento
Configurazione Modelli:
TEXT_MODEL- Modello di embedding del testo (ad es. "BAAI/bge-m3")IMAGE_MODEL- Modello per embedding immagini (ad es. "clip-ViT-B-32")CAPTION_MODEL- Modello BLIP per la generazione di didascalie immaginiLLM_MODEL- Nome del modello di Large Language ModelLLM_PROVIDER- Provider LLM (ollama, openai)LLM_API_KEY- API key per i servizi LLMLLM_HOST- URL host del server LLM
Database Vettoriale:
QDRANT_URL- URL del server QdrantQDRANT_API_KEY- API key Qdrant (opzionale)QDRANT_COLLECTION- Nome della collezione di defaultVECTOR_NAMES- Nomi dei campi vettoriali (separati da virgola)VECTOR_SIZES- Dimensioni dei vettori (separate da virgola)
- Integrazione Secret Vault: Placeholder per la gestione sicura dei segreti in cloud
- Isolamento Ambienti: Configurazioni separate per locale e cloud
- Gestione API Key: Gestione sicura delle credenziali sensibili
Posizione: metrics_computation.py
Scopo: Valutazione delle prestazioni e benchmarking del sistema RAG.
- Query Predefinite: 10 domande standard sul manuale PrintF
- Ground Truth: Riferimenti alle pagine attese per ciascuna query
- Test Automatizzati: Esecuzione su più iterazioni per significatività statistica
Metriche di Accuratezza:
- Accuratezza di Recupero: Percentuale di query per cui vengono recuperate le pagine corrette
Metriche Temporali:
- TTFT Recupero: Tempo al primo token nella ricerca vettoriale
- TTFT LLM: Tempo al primo token nella generazione del modello linguistico
- E2E Totale: Tempo end-to-end per risposta completa
- Tempi Medi: Medie statistiche sui tempi su tutte le query
- Log Strutturati: Formato JSON con metadata e risultati
- Riepilogo Statistico: Percentuali di accuratezza e tempi medi
- Python 3.8+
- GPU compatibile CUDA (opzionale)
- Database vettoriale Qdrant
- Servizio LLM (Ollama, OpenAI)
- Clona il repository
- Installa le dipendenze:
pip install -r requirements.txt - Configura le variabili d'ambiente nel file
.env - Avvia il server Qdrant (Puoi scaricarlo da tramite docker:
docker pull qdrant/qdrant- vedi quickstart https://qdrant.tech/documentation/quickstart/) - Se è il contesto non è stato estratto, esegui la pipeline backend:
python main_backend_pipeline.py - Avvia il chatbot:
streamlit run chatbot.py
- Configura modelli, API key e URL database
- Imposta il percorso del tuo documento PDF
- Modifica le impostazioni del database vettoriale secondo le tue necessità
- Processa Documenti: Esegui la pipeline backend per estrarre e indicizzare il tuo PDF
- Interroga il Sistema: Usa l'interfaccia Streamlit per porre domande
- Monitora le Prestazioni: Controlla il calcolo delle metriche per la valutazione del sistema
- Analizza i Risultati: Esamina i log e i dati delle prestazioni per l'ottimizzazione
ChatBot-app/
├── backend_pipeline/ # Componenti principali di elaborazione
│ ├── pdf_extraction.py # Estrazione testi e immagini dai PDF
│ ├── parser_chunker_emb_gen.py # Elaborazione testi e generazione embedding
│ ├── VectorDB_client.py # Operazioni sul database vettoriale
│ ├── embedding_generator.py # Gestione dei modelli di embedding
│ ├── local_llm_ollama.py # Client LLM e gestione API
│ ├── caption_generator.py # Generazione didascalie per immagini
│ └── multimodal_query_rag.py # Gestione query RAG multimodali
├── chatbot.py # Interfaccia web Streamlit
├── config.py # Gestione configurazione
├── metrics_computation.py # Calcolo e valutazione metriche
├── main_backend_pipeline.py # Orchestrazione della pipeline principale
├── pdf/ # Documenti PDF e immagini estratte
├── out_pages/ # Immagini delle pagine processate
├── query_images/ # Immagini query caricate dall’utente
├── logs/ # Log delle performance e metriche
└── README.md # Questa documentazione
docker-compose --profile pipeline up
Questo comando permette di creare il VectorDB su Qdrant e caricarlo con gli embedding generati mediante mistral.
docker-compose --profile ui up
Questo comando fa partire l'interfaccia grafica.
Il software buildato tramite docker è molto lento. La soluzione migliore sarebbe quello di fare la push dell'immagine buildata su un provider cloud in cui è possibile istanziare job con delle GPU. Inoltre, il docker permette il solo utilizzo di Mistral, in quanto non è stato gestito il passaggio di APi_KEYS mediante un vault.