DocAnalyzer: Sistema RAG Modulare per l'Analisi Multi-Formato di Documenti

Abstract

Questo paper tecnico presenta un’analisi dettagliata di DocAnalyzer, un sistema modulare basato su Retrieval-Augmented Generation (RAG) per l’analisi di documenti in vari formati (PDF, DOC, DOCX). Il sistema implementa un’architettura factory per la gestione flessibile dei formati, utilizza modelli linguistici attraverso Ollama (con DeepSeek R1 come default), ChromaDB per lo storage vettoriale, e uno stack web basato su FastAPI e Gradio. L’architettura supporta analisi basate su ruoli specifici e può essere facilmente estesa per supportare nuovi formati di documento.

1. Architettura del Sistema

1.1 Componenti Principali

Il sistema è composto da quattro componenti fondamentali:

Strato Factory
- Implementa il pattern Factory per la creazione dei processori
- Gestisce la selezione automatica del processore in base al tipo di file
- Facilita l’estensione per nuovi formati attraverso un’interfaccia unificata
- Fornisce gestione degli errori e validazione per i formati supportati
Strato di Elaborazione Documenti
- Processore PDF: Gestisce documenti PDF utilizzando PyMuPDF
- Processore Word: Gestisce file DOC/DOCX con python-docx e textract
- Classe base astratta per future implementazioni di processori
- Strategia di chunking unificata tra i processori
Strato di Elaborazione RAG
- Genera embedding utilizzando il modello linguistico configurato
- Gestisce lo storage vettoriale attraverso ChromaDB
- Implementa il recupero contestuale e la generazione delle risposte
- Supporta analisi basate su ruoli attraverso prompt specializzati
- Gestisce la persistenza dei documenti e l’ottimizzazione del recupero
Strato di Interfaccia
- Backend FastAPI per supporto API RESTful
- Frontend Gradio per interfaccia utente interattiva
- Gestione upload file multi-formato
- Selezione analisi basata su ruoli
- Streaming risposte in tempo reale
- Gestione errori e feedback utente

1.2 Dipendenze del Sistema

Dipendenze Core:
- fastapi==0.109.0 - Framework web
- gradio==4.44.1 - Framework UI
- langchain==0.0.350 - Elaborazione documenti
- chromadb==0.4.22 - Storage vettoriale
- ollama==0.1.6 - Interfaccia LLM

Elaborazione Documenti:
- PyMuPDF==1.23.8 - Elaborazione PDF
- python-docx==0.8.11 - Elaborazione DOCX
- textract==1.6.5 - Elaborazione DOC

Infrastruttura:
- uvicorn==0.27.0 - Server ASGI
- python-multipart>=0.0.9 - Gestione upload file
- python-dotenv==1.0.0 - Gestione ambiente

2. Configurazione del Sistema

2.1 Variabili d’Ambiente

Il sistema è altamente configurabile attraverso variabili d’ambiente:

# Configurazione di Rete
OLLAMA_HOST=host.docker.internal  # Host servizio LLM
OLLAMA_PORT=11434                 # Porta servizio LLM

# Configurazione Storage
CHROMA_DB_PATH=/app/data/chroma   # Percorso storage Vector DB
PERSIST_VECTORDB=false            # Flag persistenza Vector DB

# Configurazione Modello
DEEPSEEK_MODEL=deepseek-r1:14b    # Selezione modello linguistico

# Configurazione Elaborazione
CHUNK_SIZE=1000                   # Dimensione chunk documento
CHUNK_OVERLAP=200                 # Dimensione sovrapposizione chunk

2.2 Linee Guida Risorse

Raccomandazioni risorse di sistema basate sui pattern di utilizzo:

Profilo Risorse	RAM	Storage	Dim. Max Doc	Configurazione
Minimo	4GB	10GB	20MB	CHUNK_SIZE=500, CHUNK_OVERLAP=100
Standard	8GB	20GB	50MB	CHUNK_SIZE=1000, CHUNK_OVERLAP=200
Alte Prestazioni	16GB+	40GB+	100MB+	CHUNK_SIZE=2000, CHUNK_OVERLAP=400

Considerazioni chiave per il dimensionamento dei chunk:

Chunk più grandi forniscono un contesto migliore ma aumentano l’uso della memoria
La percentuale di sovrapposizione dovrebbe essere 20-30% della dimensione del chunk
La complessità del documento influenza la dimensione ottimale del chunk
La memoria di sistema disponibile vincola la dimensione massima del chunk

3. Analisi dell’Implementazione

3.1 Pipeline di Elaborazione Documenti

La pipeline di elaborazione documenti segue questi passaggi:

Rilevamento Formato

def get_processor(file_path: Union[str, Path]) -> DocumentProcessor:
    extension = Path(file_path).suffix.lower()
    if extension == '.pdf':
        return PDFProcessor()
    elif extension in ['.doc', '.docx']:
        return WordProcessor()
    raise ValueError("Formato non supportato")

Estrazione Testo

def process(self, file_obj):
    # Crea file temporaneo per upload
    with tempfile.NamedTemporaryFile(delete=False) as tmp_file:
        file_path = tmp_file.name

    try:
        # Estrae testo in base al formato
        documents = self.extract_text(file_path)

        # Divide in chunk
        chunks = self.text_splitter.split_documents(documents)
        return chunks
    finally:
        # Pulizia
        os.unlink(file_path)

Storage Vettoriale

def process_document(self, chunks):
    # Inizializza database vettoriale
    self.vectordb = Chroma.from_documents(
        documents=chunks,
        embedding=self.embeddings,
        persist_directory=self.chroma_path
    )

    if self.persist_db:
        self.vectordb.persist()

3.2 Elaborazione Query

Il flusso di elaborazione delle query:

Recupero Contesto

def query(self, question, role="default"):
    # Ottiene chunk rilevanti
    retriever = self.vectordb.as_retriever()
    relevant_chunks = retriever.get_relevant_documents(question)

    # Prepara contesto
    context = "\n\n".join([chunk.page_content for chunk in relevant_chunks])

Analisi Basata su Ruoli

# Prepara prompt specifico per ruolo
prompt = BASE_PROMPT.format(
    role_prompt=ROLE_PROMPTS[role],
    context=context,
    question=question
)

Generazione Risposta

response = client.chat(
    model=self.model_name,
    messages=[{
        "role": "user",
        "content": prompt
    }]
)

4. Sistema di Analisi Basato su Ruoli

4.1 Ruoli Disponibili

Il sistema supporta ruoli di analisi specializzati:

Analista Generale
- Analisi oggettiva del contenuto
- Estrazione completa delle informazioni
- Generazione risposta strutturata
Analista Legale
- Focus sulla conformità normativa
- Valutazione rischi legali
- Identificazione opportunità di compliance
Analista Finanziario
- Analisi costi-benefici
- Calcoli ROI
- Valutazione rischi finanziari
Consulente Viaggi
- Pianificazione logistica
- Informazioni specifiche località
- Raccomandazioni pratiche di viaggio
Analista Tecnico
- Dettagli implementativi
- Requisiti tecnici
- Considerazioni architetturali

4.2 Ingegneria dei Prompt

I prompt basati su ruoli sono strutturati per garantire:

Chiara definizione del ruolo
Focus specifico del dominio
Terminologia consistente
Spiegazioni accessibili
Informazioni pratiche

Esempio struttura prompt:

ROLE_PROMPTS = {
    "technical": """Agisci come un esperto tecnico nell'analisi del contenuto.
    Concentrati su dettagli tecnici, specifiche implementative e considerazioni architetturali.
    Utilizza una terminologia tecnica appropriata mantenendo la spiegazione accessibile.
    Evidenzia requisiti tecnici, sfide e approcci alle soluzioni se presenti."""
}

5. Testing

Il sistema include diversi tipi di test:

Test base processori: Verifica del comportamento della classe base DocumentProcessor
Test della factory: Validazione della creazione corretta dei processori per i vari formati di file
Test del processore Word: Test specifici per l’elaborazione di documenti DOC e DOCX
Test unitari:
- Test dell’applicazione FastAPI
- Test del processore RAG
- Validazione delle funzionalità core

6. Sviluppo e Deployment

5.1 Sviluppo Locale

# Setup ambiente
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Avvio server sviluppo
uvicorn src.app:app --reload

5.2 Deployment Docker

services:
  web:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    env_file: .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
      interval: 30s
      retries: 3

Conclusioni

DocAnalyzer rappresenta un approccio sofisticato all’analisi documentale, offrendo:

Flessibilità di Formato
- Supporto nativo per PDF, DOC e DOCX
- Architettura estensibile
- Pipeline di elaborazione unificata
Analisi Intelligente
- Comprensione del contesto basata su ruoli
- Informazioni specifiche per dominio
- Generazione adattiva delle risposte
Efficienza Operativa
- Utilizzo risorse configurabile
- Pipeline di elaborazione ottimizzata
- Opzioni di deployment flessibili
Architettura Manutenibile
- Design modulare
- Testing completo
- Documentazione chiara

La combinazione di elaborazione multi-formato, analisi basata su ruoli e integrazione flessibile del modello linguistico rende il sistema uno strumento versatile per applicazioni di analisi documentale. La sua architettura modulare garantisce una facile manutenzione ed estensibilità futura.