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 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
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=truei vettori vengono scritti su disco ma non ricaricati al riavvio)
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
- Backend FastAPI che ospita l’interfaccia Gradio (montata su
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
- 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:
# 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_SIZEeCHUNK_OVERLAPsono 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.exampleusa 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:
- Rilevamento Formato (
src/processors/factory.py)
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")
- Estrazione Testo (
src/processors/pdf_processor.py;WordProcessorsegue lo stesso schema)
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.
- Storage Vettoriale (
src/processors/rag_processor.py)
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:
- Recupero Contesto
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])
- Analisi Basata su Ruoli
# Prepara prompt specifico per ruolo
prompt = BASE_PROMPT.format(
role_prompt=ROLE_PROMPTS[role],
context=context,
question=question
)
- Generazione Risposta
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):
Analista Generale (
default)- Analisi oggettiva del contenuto
- Estrazione completa delle informazioni
- Generazione risposta strutturata
Consulente Legale (
legal)- Implicazioni legali e requisiti normativi
- Valutazione rischi legali
- Criticità di compliance e opportunità legali
Consulente Finanziario (
financial)- Analisi costi-benefici
- Focus su ROI e aspetti economici
- Valutazione rischi finanziari
Consulente Viaggi (
travel)- Pianificazione logistica
- Informazioni specifiche località
- Raccomandazioni pratiche di viaggio
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):
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.pyha 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
- Test delle funzioni di gestione upload/query in
6. Sviluppo e Deployment
6.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
6.2 Deployment Docker
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:
Flessibilità di Formato
- Supporto per PDF, DOCX e DOC (quest’ultimo tramite textract/antiword)
- 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 semplice e lineare
- Opzioni di deployment flessibili
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.