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

> Analisi dettagliata di DocAnalyzer, un sistema modulare basato su Retrieval-Augmented Generation (RAG) per l'analisi di documenti in vari formati

- URL: https://mautoblog.com/docs/doc-analyzer-paper/
- Lingua: it
- Pubblicato: 2025-02-21
- Aggiornato: 2026-10-16
- Autore: Matteo

---
## 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:

1. **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

2. **Strato di Elaborazione Documenti**
   - Processore PDF: Gestisce documenti PDF utilizzando PyMuPDF
   - Processore Word: Gestisce file DOCX con python-docx e file DOC con textract (che si appoggia ad antiword)
   - Classe base astratta per future implementazioni di processori
   - Strategia di chunking unificata tra i processori

3. **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
   - Recupero per similarità semantica (retriever LangChain di default, k=4)
   - Gestisce un solo documento alla volta: ogni nuovo upload azzera il database vettoriale (con `PERSIST_VECTORDB=true` i vettori vengono scritti su disco ma non ricaricati al riavvio)

4. **Strato di Interfaccia**
   - Backend FastAPI che ospita l'interfaccia Gradio (montata su `/`); API REST dedicate non ancora presenti
   - Frontend Gradio per interfaccia utente interattiva
   - Gestione upload file multi-formato
   - Selezione analisi basata su ruoli
   - Interfaccia chat con cronologia della conversazione (risposta restituita al termine della generazione)
   - Gestione errori e feedback utente

### 1.2 Dipendenze del Sistema

```plaintext
Dipendenze Core:
- fastapi==0.109.0 - Framework web
- gradio==4.44.1 - Framework UI
- langchain==0.0.350 - Elaborazione documenti
- langchain-community==0.0.10 - Loader, vector store ed embedding LangChain
- 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

Dipendenze di sistema (Docker):
- poppler-utils, tesseract-ocr, libtesseract-dev
- antiword, unrtf (usati da textract per i file DOC)
```

## 2. Configurazione del Sistema

### 2.1 Variabili d'Ambiente

Il sistema è altamente configurabile attraverso variabili d'ambiente:

```plaintext
# 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            # Scrittura su disco del Vector DB (azzerato a ogni nuovo upload)

# Configurazione Modello
LLM_MODEL=deepseek-r1:14b         # Qualsiasi modello Ollama (default DeepSeek R1 14B)

# Configurazione Elaborazione (valori in caratteri)
CHUNK_SIZE=1000                   # Dimensione chunk documento (default nel codice)
CHUNK_OVERLAP=200                 # Dimensione sovrapposizione chunk (default nel codice)
```

Nota: il file `.env.example` del repository usa `CHUNK_SIZE=2000` e `CHUNK_OVERLAP=100`; i valori sopra sono i default applicati dal codice quando le variabili non sono impostate.

### 2.2 Linee Guida Risorse

Indicazioni orientative, non misurate. Requisiti dal README: 8GB di RAM e 20GB di disco. Il modello LLM gira in Ollama sull'host e richiede memoria aggiuntiva (circa 9GB o più per deepseek-r1:14b).

| Profilo Risorse | RAM (container) | Storage | Configurazione |
|-----------------|-----------------|---------|----------------|
| Minimo (README) | 8GB | 20GB | CHUNK_SIZE=500, CHUNK_OVERLAP=100 (suggeriti dal README in caso di problemi di memoria) |
| Standard | 8GB | 20GB | CHUNK_SIZE=1000, CHUNK_OVERLAP=200 (default nel codice) |
| Alte Prestazioni (indicativo) | 16GB+ | 40GB+ | CHUNK_SIZE=2000, CHUNK_OVERLAP=100 (valori di `.env.example`) |

Considerazioni chiave per il dimensionamento dei chunk:

- `CHUNK_SIZE` e `CHUNK_OVERLAP` sono espressi in caratteri, non in token (`RecursiveCharacterTextSplitter`)
- Chunk più grandi forniscono più contesto per singolo frammento, ma allungano il prompt inviato al modello
- Un overlap del 10-20% è un punto di partenza comune (euristica, da validare sui propri documenti); `.env.example` usa il 5%
- La complessità del documento influenza la dimensione ottimale del chunk
- Il vincolo principale è la finestra di contesto del modello: i k=4 chunk recuperati più il prompt devono rientrarvi

## 3. Analisi dell'Implementazione

### 3.1 Pipeline di Elaborazione Documenti

La pipeline di elaborazione documenti segue questi passaggi:

1. **Rilevamento Formato** (`src/processors/factory.py`)
```python
class ProcessorFactory:
    @staticmethod
    def get_processor(file_path: Union[str, Path]) -> DocumentProcessor:
        if isinstance(file_path, str):
            file_path = Path(file_path)

        if hasattr(file_path, 'name'):
            extension = Path(file_path.name).suffix.lower()
        else:
            extension = file_path.suffix.lower()

        if extension == '.pdf':
            return PDFProcessor()
        elif extension in ['.doc', '.docx']:
            return WordProcessor()

        raise ValueError("Please upload a PDF, DOC, or DOCX file")
```

2. **Estrazione Testo** (`src/processors/pdf_processor.py`; `WordProcessor` segue lo stesso schema)
```python
def process(self, file_obj):
    # Gestisce sia percorsi stringa sia oggetti file da Gradio
    if isinstance(file_obj, str):
        file_path = file_obj
    else:
        with tempfile.NamedTemporaryFile(delete=False, suffix='.pdf') as tmp_file:
            # File da Gradio: si usa direttamente il suo percorso
            if hasattr(file_obj, 'name'):
                file_path = file_obj.name
            else:
                # Altrimenti si scrive il contenuto in un file temporaneo
                content = file_obj.read() if hasattr(file_obj, 'read') else file_obj
                if isinstance(content, str):
                    content = content.encode('utf-8')
                tmp_file.write(content)
                file_path = tmp_file.name

    try:
        loader = PyMuPDFLoader(file_path)
        documents = loader.load()

        # Divide in chunk
        chunks = self.text_splitter.split_documents(documents)
        return chunks
    finally:
        # Pulizia solo se è stato creato un file temporaneo
        if 'tmp_file' in locals():
            os.unlink(file_path)
```

Nel `WordProcessor` l'estrazione avviene con `_process_docx` (python-docx, unione dei paragrafi) o `_process_doc` (`textract.process`), e il testo ottenuto diventa un unico `Document` prima del chunking.

3. **Storage Vettoriale** (`src/processors/rag_processor.py`)
```python
def process_document(self, chunks):
    if not chunks:
        raise ValueError("No document chunks provided")

    # Azzera il database vettoriale (un documento alla volta)
    self._clean_db()

    self.vectordb = Chroma.from_documents(
        documents=chunks,
        embedding=self.embeddings,
        persist_directory=self.chroma_path if self.persist_db else None
    )

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

### 3.2 Elaborazione Query

Il flusso di elaborazione delle query:

1. **Recupero Contesto**
```python
def query(self, question, role="default"):
    if self.vectordb is None:
        raise ValueError("Please upload a document before asking questions")

    if role not in ROLE_PROMPTS:
        raise ValueError(f"Invalid role. Must be one of: {', '.join(ROLE_PROMPTS.keys())}")

    # 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])
```

2. **Analisi Basata su Ruoli**
```python
# Prepara prompt specifico per ruolo
prompt = BASE_PROMPT.format(
    role_prompt=ROLE_PROMPTS[role],
    context=context,
    question=question
)
```

3. **Generazione Risposta**
```python
client = ollama.Client(
    host=f"http://{os.getenv('OLLAMA_HOST', 'localhost')}:{os.getenv('OLLAMA_PORT', '11434')}"
)

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

return response['message']['content']
```

## 4. Sistema di Analisi Basato su Ruoli

### 4.1 Ruoli Disponibili

Il sistema supporta ruoli di analisi specializzati (tra parentesi la chiave usata nel codice):

1. **Analista Generale** (`default`)
   - Analisi oggettiva del contenuto
   - Estrazione completa delle informazioni
   - Generazione risposta strutturata

2. **Consulente Legale** (`legal`)
   - Implicazioni legali e requisiti normativi
   - Valutazione rischi legali
   - Criticità di compliance e opportunità legali

3. **Consulente Finanziario** (`financial`)
   - Analisi costi-benefici
   - Focus su ROI e aspetti economici
   - Valutazione rischi finanziari

4. **Consulente Viaggi** (`travel`)
   - Pianificazione logistica
   - Informazioni specifiche località
   - Raccomandazioni pratiche di viaggio

5. **Esperto Tecnico** (`technical`)
   - 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 (`src/config/prompts.py`, testo originale in inglese):
```python
ROLE_PROMPTS = {
    "technical": """Act as a technical expert analyzing the content.
Focus on technical details, implementation specifics, and architectural considerations.
Use appropriate technical terminology while keeping the explanation accessible.
        Highlight technical requirements, challenges, and solution approaches if present."""
}
```

Traduzione: "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."

Il prompt di ruolo viene inserito in un `BASE_PROMPT` comune, che chiede di usare solo le informazioni degli estratti e di rispondere nella stessa lingua della domanda.

## 5. Testing

Il sistema include una suite di test unitari (con mock):

- **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 (nota: nella versione descritta il file `tests/processors/ test_word_processor.py` ha uno spazio iniziale nel nome e non viene raccolto da pytest)
- **Test unitari**:
  - Test delle funzioni di gestione upload/query in `app.py`
  - Test del processore RAG
  - Validazione delle funzionalità core

## 6. Sviluppo e Deployment

### 6.1 Sviluppo Locale

```bash
# 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
```

### 6.2 Deployment Docker

```yaml
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env
    extra_hosts:
      - "host.docker.internal:host-gateway"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
```

## Conclusioni

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

1. **Flessibilità di Formato**
   - Supporto per PDF, DOCX e DOC (quest'ultimo tramite textract/antiword)
   - Architettura estensibile
   - Pipeline di elaborazione unificata

2. **Analisi Intelligente**
   - Comprensione del contesto basata su ruoli
   - Informazioni specifiche per dominio
   - Generazione adattiva delle risposte

3. **Efficienza Operativa**
   - Utilizzo risorse configurabile
   - Pipeline di elaborazione semplice e lineare
   - Opzioni di deployment flessibili

4. **Architettura Manutenibile**
   - Design modulare
   - Suite di test unitari (con mock)
   - 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.

