# DocSummarizer Parte 2 - Uso dello strumento

<!--category-- AI, LLM, RAG, C#, Docling, Ollama, Qdrant, Tools -->
<datetime class="hidden">2025-12-21T11:00</datetime>

[![Rilascio di GitHub](https://img.shields.io/github/v/release/scottgal/mostlylucidweb?filter=docsummarizer*&label=docsummarizer)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
[![.NET](https://img.shields.io/badge/.NET-9.0-512BD4)](https://dotnet.microsoft.com/)
[![Versione](https://img.shields.io/badge/version-3.1.0-blue)](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)

Questo e' **Parte 2** della serie DocSummarizer. Vedi [Parte 1](/blog/building-a-document-summarizer-with-rag) per l'architettura e i modelli, o [Parte 3](/blog/docsummarizer-advanced-concepts) per l'immersione tecnica profonda in inglobi e recupero.

> **Trasforma i documenti o gli URL in riassunti basati sulle prove - per esseri umani o agenti AI - senza inviare nulla al cloud.**

Ogni affermazione è tracciabile. Ogni fatto cita la sua fonte. Self-contained binario, funziona interamente sulla vostra macchina.

```bash
# Human-readable summary
docsummarizer -f contract.pdf

# JSON for agents/pipelines
docsummarizer tool -u "https://docs.example.com"
```

**Ciò che questo articolo copre**: Installazione, modalità chiave (Auto/BertRag/Bert), modelli e casi di uso comune.

**Quello che non copre**: Riferimento completo dei comandi, opzioni di configurazione, risoluzione dei problemi, dettagli dell'architettura.

Per una documentazione completa, consultare il [README](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid.DocSummarizer/README.md). Per come funziona internamente, vedere [Parte 3](/blog/docsummarizer-advanced-concepts).

[TOC]

## Perché questo esiste

La maggior parte dei sintetizzatori ti danno testo. Questo ti dà *prove*.

- **Ogni reclamo comprende: `[chunk-N]` citazioni** Ritorna al materiale sorgente
- **Livelli di fiducia** (alto/medio/basso) sulla base di prove a sostegno
- **Uscita JSON strutturata** per l'integrazione di agenti, pipeline CI o server MCP
- **metriche di qualità** catturare allucinazioni prima che scappino

Se hai bisogno di *fiducia* una sintesi - o alimentarla ad un altro sistema - che conta.

## Caratteristiche

- **BertRag Pipeline**: Estrazione BERT di qualità produttiva → recupero → sintesi LLM
- **Modalità automatica**: Smart mode selection basato su documento e query
- **Modalità Bert**: Sintesi estrattiva pura - nessun LLM necessario, lavori offline (~3-5s)
- **Evidence-Grounded Output**: Citazioni, livelli di fiducia, crediti tracciabili
- **Modalità multiple**Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative
- **Modalità strumento**: Clean JSON per agenti LLM, server MCP, controlli CI
- **13 Modelli**: di default, prosa, breve, oneliner, proiettili, esecutivo, dettagliato, tecnico, accademico, citazioni, bookreport, riunione, rigoroso
- **Documenti di grandi dimensioni**: Gestisce oltre 500 pagine con elaborazione gerarchica
- **Recupero web**: Sicurezza temprata (protezione SSRF, sanificazione HTML)
- **Modalità Playwright**: Browser senza testa per JavaScript-rendered pagine (SPA, React apps)
- **Abbinamenti ONNX**: Zero-config embeddings locali - modelli auto-download sul primo utilizzo
- **Analisi della qualità**: Rilevamento dell'allucinazione, estrazione dell'entità
- **LLM resiliente**: Riprova Polly con jitter backoff + interruttore
- **Solo locale**: Niente lascia la tua macchina

## Usare come strumento LLM

La `tool` Il comando è progettato specificamente per l'integrazione con agenti AI, server MCP e altri sistemi automatizzati. Emette JSON strutturato a stdout con reclami basati su prove - perfetto per la costruzione di pipeline RAG o strumenti agenti.

### Uso dello strumento di base

```bash
# Summarize a URL and get JSON output
docsummarizer tool --url "https://example.com/docs.html"

# Summarize a local file
docsummarizer tool -f document.pdf

# With a focus query
docsummarizer tool -f contract.pdf -q "payment terms and conditions"

# Pipe to jq for processing
docsummarizer tool -f doc.pdf | jq '.summary.keyFacts'
```

### Struttura dell' output strumento

Il comando tool restituisce JSON strutturato con tracciamento delle prove:

```json
{
  "success": true,
  "source": "https://example.com/docs.html",
  "contentType": "text/html",
  "summary": {
    "executive": "Brief summary of the document.",
    "keyFacts": [
      {
        "claim": "The system supports 10,000 TPS.",
        "confidence": "high",
        "evidence": ["chunk-3", "chunk-7"],
        "type": "fact"
      }
    ],
    "topics": [
      {
        "name": "Architecture",
        "summary": "The system uses microservices...",
        "evidence": ["chunk-1", "chunk-2"]
      }
    ],
    "entities": {
      "people": ["John Smith"],
      "organizations": ["Acme Corp"],
      "concepts": ["OAuth 2.0", "REST API"]
    },
    "openQuestions": ["What is the disaster recovery plan?"]
  },
  "metadata": {
    "processingSeconds": 12.5,
    "chunksProcessed": 15,
    "model": "qwen2.5:1.5b",
    "mode": "MapReduce",
    "coverageScore": 0.95,
    "citationRate": 1.2,
    "fetchedAt": "2025-01-15T10:30:00Z"
  }
}
```

### Opzioni dei comandi strumenti

```bash
docsummarizer tool [options]
```

| Opzione | Corto | Descrizione |
|--------|-------|-------------|
| `--url` | `-u` | URL per recuperare e riassumere |
| `--file` | `-f` | File da riassumere |
| `--query` | `-q` | Interrogazione di messa a fuoco opzionale |
| `--mode` | `-m` | Modalità di sintesi (Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative) |
| `--model` | | Modello Ollama da usare |
| `--config` | `-c` | Percorso del file di configurazione |

### Principi chiave di progettazione

- **Evidence Grounding**: Ogni reclamo include `evidence` ID che fanno riferimento ai pezzi sorgente
- **Livelli di fiducia**: I crediti sono valutati `high`, `medium`, oppure `low` sulla base di elementi di prova a sostegno
- **Pulisci output**: La `executive` sommario non ha marcatori di citazione per una visualizzazione facile
- **Metadati**: Le statistiche di elaborazione aiutano con il debug e la valutazione della qualità
- **Gestione degli errori**: Fallimenti di ritorno `success: false` con `error` messaggio

### Esempi di integrazione

**Script Python:**

```python
import subprocess
import json

result = subprocess.run(
    ["docsummarizer", "tool", "-u", "https://example.com/api-docs"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

if data["success"]:
    for fact in data["summary"]["keyFacts"]:
        if fact["confidence"] == "high":
            print(f"- {fact['claim']}")
```

**Conduttura di shell:**

```bash
# Extract high-confidence facts only
docsummarizer tool -f doc.pdf | jq '[.summary.keyFacts[] | select(.confidence == "high")]'

# Get just the executive summary
docsummarizer tool -u "https://example.com" | jq -r '.summary.executive'
```

## Avvio rapido

### Scarica i binari pre-costruiti

Gli eseguibili nativi pre-costruiti sono disponibili da [Rilascia GitHub](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer):

| Piattaforma | Architettura | Download |
|----------|--------------|----------|
| Finestre | x64 | `docsummarizer-win-x64.zip` |
| Finestre | ARM64 | `docsummarizer-win-arm64.zip` |
| Linux | x64 | `docsummarizer-linux-x64.tar.gz` |
| Linux | ARM64 | `docsummarizer-linux-arm64.tar.gz` |
| macOS | x64 (Intel) | `docsummarizer-osx-x64.tar.gz` |
| macOS | ARM64 (Silicone apple) | `docsummarizer-osx-arm64.tar.gz` |

```bash
# Download and extract (Linux/macOS)
curl -L -o docsummarizer.tar.gz https://github.com/scottgal/mostlylucidweb/releases/download/docsummarizer-v3.1.0/docsummarizer-linux-x64.tar.gz
tar -xzf docsummarizer.tar.gz
chmod +x docsummarizer

# Download and extract (Windows PowerShell)
Invoke-WebRequest -Uri "https://github.com/scottgal/mostlylucidweb/releases/download/docsummarizer-v3.1.0/docsummarizer-win-x64.zip" -OutFile "docsummarizer.zip"
Expand-Archive -Path "docsummarizer.zip" -DestinationPath "."
```

### Prerequisiti

#### Modalità Bert (senza servizi esterni)

per la sintesi estrattiva pura, **nessun servizio esterno richiesto**:

```bash
docsummarizer -f document.md -m Bert
```

I modelli ONNX scaricano automaticamente da HuggingFace al primo utilizzo (~23MB). Restituisce in ~3-5 secondi.

#### Modalità LLM (Auto, BertRag, MapReduce, ecc.)

Per la sintesi a motore LLM, Ollama è necessario:

```bash
# Install Ollama from https://ollama.ai
ollama pull llama3.2:3b        # Default model - good balance of speed/quality
ollama serve
```

> **Punta della velocità**: Per i riassunti più veloci (~3s vs ~15s), usare `--model qwen2.5:1.5b`

#### Facoltativo: docling (Formati binari)

Richiesto per file PDF, DOCX, XLSX, PPTX, HTML, immagini (PNG/JPG/TIFF), CSV, VTT e AsciiDoc. **Markdown e file di testo semplici sono letti direttamente - nessun Docling richiesto.**

```bash
docker run -d -p 5001:5001 quay.io/docling-project/docling-serve
```

#### Facoltativo: Qdrant (Persistent Vector Storage)

Non richiesto per impostazione predefinita - BertRag utilizza vettori in-memory. Abilitare Qdrant per lo storage persistente per evitare la ri-embedding di documenti nelle successive esecuzioni:

```bash
docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant
```

Quindi configura in `docsummarizer.json`:

```json
{
  "bertRag": {
    "vectorStore": "Qdrant",
    "collectionName": "docsummarizer",
    "persistVectors": true
  }
}
```

#### Facoltativo: Inserimento di Ollama

Se preferisci Ollama per l'imbottitura invece di ONNX:

```bash
ollama pull nomic-embed-text   # Or mxbai-embed-large
# Then use: --embedding-backend Ollama
```

### Verifica le dipendenze

```bash
docsummarizer check --verbose
```

L'output previsto mostra una tabella formattata:

```
              Dependency Status              
╭─────────┬────────┬────────────────────────╮
│ Service │ Status │ Endpoint               │
├─────────┼────────┼────────────────────────┤
│ Ollama  │   OK   │ http://localhost:11434 │
│ Docling │ Optional │ http://localhost:5001 │
│ Qdrant  │ Optional │ localhost:6333        │
╰─────────┴────────┴────────────────────────╯

        Default Model Info         
╭────────────────┬────────────────╮
│ Property       │ Value          │
├────────────────┼────────────────┤
│ Name           │ llama3.2:3b    │
│ Family         │ llama          │
│ Parameters     │ 3.2B           │
│ Context Window │ 128,000 tokens │
╰────────────────┴────────────────╯

Ready to summarize! Ollama is available.
```

> **Nota**: La docling e Qdrant che mostra il file è a posto solo per i flussi di lavoro Markdown.

## Uso

### Comportamento predefinito

In esecuzione `docsummarizer` senza argomenti:

1. Cerca `README.md` nella directory corrente
2. Riepilogalo usando **Modalità automatica** (Selezione in modalità intelligente)
3. Stampa il riepilogo per console con un bel pannello UI
4. Salvataggio automatico su `readme.summary.md`

```bash
# Summarize README.md in current directory
docsummarizer

# Shows a formatted panel with:
# - Document info table (file, mode, model)
# - Progress indicators during processing
# - Summary panel with the result
# - Topics tree if available
# - Saved: readme.summary.md
```

### Sintesi di base

```bash
# Just run it - Auto mode picks the best approach
docsummarizer -f document.pdf

# Fast mode - no LLM, pure extraction (~3-5s)
docsummarizer -f document.pdf -m Bert

# Production mode - best quality with validated citations
docsummarizer -f document.pdf -m BertRag

# Focused on specific topic
docsummarizer -f manual.pdf -m BertRag --focus "installation steps"

# Verbose progress
docsummarizer -f document.pdf -v
```

## Modalità di sintesi

Lo strumento si è evoluto da " just MapReduce" a una pipeline completa. Ecco cosa fa in realtà ogni modalità:

### Auto (predefinito)

Picks la giusta modalità in base a quello che stai chiedendo. Utilizzare questo a meno che non si ha una ragione per non farlo.

```bash
docsummarizer -f doc.pdf
```

### BertRag (produzione)

Questo è ciò che volete per la produzione.

1. **Estrai** - Esaminare il documento in segmenti, incorporarlo con BERT
2. **Recupera** - Trovare i segmenti rilevanti (ricerca semantica + punteggio salienza)
3. **Sintetizza** - LLM scrive un sommario fluente da quei segmenti

```bash
docsummarizer -f doc.pdf -m BertRag
docsummarizer -f doc.pdf -m BertRag --focus "payment terms"
```

**Perché usarlo:** Ogni richiesta risale ad un segmento sorgente. Nessuna allucinazione. Scala a qualsiasi dimensione del documento. LLM funziona solo alla fine (a buon mercato).

### BERT (Fast, No LLM)

Estrazione pura utilizzando modelli locali ONNX. Nessuna chiamata LLM a tutti.

```bash
docsummarizer -f doc.pdf -m Bert
```

**Perché usarlo:** Funziona offline. Restituisce in ~3-5 secondi. Deterministico (stesso input = stesso output). Abbastanza buono per scansioni rapide.

### BertHybridCity name (optional, probably does not need a translation)

Estratti di BERT, lucidanti LLM... terreno intermedio tra Bert e BertRag.

```bash
docsummarizer -f doc.pdf -m BertHybrid
```

### MapReduce / Rag / Iterative

Le modalità originali. Funziona ancora, ma BertRag le ha sostituite per la maggior parte dei casi d'uso.

- **MapReduce**: Parallel chunking, ottimo per la copertura al 100%
- **RagCity name (optional, probably does not need a translation)**: Ricerca vettoriale, buona per le query focalizzate (legacy - BertRag lo fa meglio)
- **Iterativo**: Elaborazione sequenziale, utilizzare solo per piccoli documenti

```bash
docsummarizer -f doc.pdf -m MapReduce  # Full coverage
docsummarizer -f doc.pdf -m Rag --focus "query"  # Legacy focused mode
```

### Modalità interrogazione

Invece di riassumere, fare domande su un documento:

```bash
docsummarizer -f manual.pdf --query "How do I install the software?"
```

### Recupero URL web

Sintesi delle pagine web direttamente senza scaricare:

```bash
# Summarize a web article
docsummarizer --url "https://example.com/article.html" --web-enabled

# Summarize a remote PDF
docsummarizer --url "https://example.com/document.pdf" --web-enabled

# With structured JSON extraction
docsummarizer --url "https://example.com/api-docs.html" --web-enabled --structured
```

**Contenuto supportato**: HTML (sanitizzato), PDF, Markdown, immagini (OCR), documenti Office. Grandi immagini automaticamente ridimensionate.

**Sicurezza**: Protezione SSRF, Protezione rilegatura DNS, Gating di tipo contenuto, Protezione antibomba decompressione, sanificazione HTML.

**Pagine rese da JavaScript**: Uso `--web-mode Playwright` per le applicazioni SPA e React (auto-installa Chromium al primo uso).

### Modalità strutturata

Estrarre JSON leggibile da macchina al posto della prosa:

```bash
docsummarizer -f document.pdf --structured -o Json
```

Estratti: entità, funzioni, flussi chiave, fatti (con livelli di fiducia), incertezze, passaggi quotabili.

### Modelli sommari

```bash
# Use a template
docsummarizer -f doc.pdf --template executive
docsummarizer -f doc.pdf -t bullets

# Specify custom word count with template:wordcount syntax
docsummarizer -f doc.pdf -t bookreport:500
docsummarizer -f doc.pdf -t executive:100

# Or use --words to override any template's default
docsummarizer -f doc.pdf -t detailed --words 300
```

| Modello | Parole | Migliore per |
|----------|-------|----------|
| `default` | ~ 300 | Sommario bilanciato con argomenti (2 paragrafi) |
| `prose` | ~ 400 | Prosa multipunto pulita - nessun metadati |
| `brief` | ~50 | Riassunto rapido di 2-3 frasi |
| `oneliner` | ~ 25 | Singola frase sommario |
| `bullets` | Auto | Elenco dei punti di proiettile (5-7 elementi) |
| `executive` | ~ 150 | briefing esecutivo con raccomandazioni |
| `detailed` | ~ 1000 | Completo di argomenti completi |
| `technical` | ~ 350 | Documenti tecnici con dettagli di implementazione |
| `academic` | ~ 250 | Formato astratto accademico |
| `citations` | Auto | Citazioni chiave con solo citazioni sorgente |
| `bookreport` | ~ 500 | Book report (setting, caratteri, trama, temi) |
| `meeting` | ~ 200 | Note di riunione (decisioni, azioni, domande) |
| `strict` | ~ 60 | Token-efficiente, 3 proiettili max, nessuna copertura |

Per vedere tutti i modelli disponibili con le descrizioni:

```bash
docsummarizer templates
```

### Modello di benchmarking

Confronta i modelli sullo stesso documento utilizzando il `benchmark` sottocomando:

```bash
docsummarizer benchmark -f doc.pdf -m "qwen2.5:1.5b,llama3.2:3b,ministral-3:3b"
```

Il comando benchmark analizza il documento una volta, quindi esegue ogni modello sugli stessi pezzi per un confronto equo. L'output mostra tempi, numero di parole e parole/secondo per ogni modello.

### Elaborazione di lotti

Elaborare intere directory:

```bash
# Use BertRag for quality
docsummarizer -d ./documents -m BertRag -v

# Fast offline batch (no LLM needed)
docsummarizer -d ./documents -m Bert -o Json --output-dir ./summaries

# Process only PDFs recursively
docsummarizer -d ./documents -e .pdf --recursive -v
```

### Opzioni della linea di comando

| Opzione | Corto | Descrizione | Predefinito |
|--------|-------|-------------|---------|
| `--file` | `-f` | Percorso del documento (DOCX, PDF, MD) | - |
| `--directory` | `-d` | Percorso della directory per l'elaborazione batch | - |
| `--url` | `-u` | URL web per recuperare e riassumere | - |
| `--web-enabled` | | Abilita il recupero della ragnatela (richiesto per --url) | `false` |
| `--mode` | `-m` | Modalità di sintesi: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative | `Auto` |
| `--structured` | `-s` | Usa modalità di estrazione JSON strutturata | `false` |
| `--focus` | | Interrogazione di messa a fuoco per la modalità RAG | Nessuno |
| `--query` | `-q` | Modalità di query invece di sintetizzazione | Nessuno |
| `--model` | | Modello Ollama da usare | `llama3.2:3b` |
| `--verbose` | `-v` | Mostra progressi dettagliati con UI dal vivo | `false` |
| `--config` | `-c` |Percorso del file di configurazione |Riscoperta automatica |
| `--output-format` | `-o` | Formato di uscita: Console, Testo, Markdown, Json | `Console` |
| `--output-dir` | | Directory di uscita per uscite di file | Dir corrente |
| `--extensions` | `-e` | Estensioni file per modalità batch | Tutti i formati di docling |
| `--recursive` | `-r` | directory di processo ricorsivamente | `false` |
| `--template` | `-t` | Modello sommario (default, brief, balls, executive, ecc.) | `default` |
| `--words` | `-w` | Conteggio delle parole di destinazione (modello overrides) | Predefinito del modello |

| `--embedding-backend` | | Backend di montaggio: Onnx, Ollama | `Onnx` |
| `--embedding-model` | | ONNX model name (RAG mode) | `AllMiniLmL6V2` |
| `--web-mode` | | Modalità di recupero Web: semplice, Playwright | `Simple` |
| `--analyze` | `-a` | Esegui analisi di qualità al sommario | `false` |

## Modalità di sintesi

### MapReduce (Consigliato)

Meglio per riassunti completi con una copertura completa dei documenti.

```bash
docsummarizer -f document.pdf -m MapReduce -v
```

**Come funziona**:

1. Divide il documento in pezzi strutturali (per rubrica)
2. Riepiloga ogni pezzo in parallelo usando LLM
3. Riduce i riassunti in sintesi con le citazioni
4. Convalida tutti i blocchi reali di riferimento delle citazioni

**Riduzione gerarchica per documenti lunghi**:

Per lunghissimi documenti in cui i sommari dei pezzi combinati superano la finestra contestuale del modello, MapReduce utilizza automaticamente la riduzione gerarchica:

1. **Lotto**: Gruppi sommari in lotti che si adattano nel contesto
2. **Riduzione intermedia**: Riduce ogni lotto in un riassunto condensato
3. **Riduzione finale**: Unisce i riassunti intermedi nell'output finale
4. **Ricorrente**: Se gli intermedi sono ancora troppo grandi, aggiunge più livelli

```
100 chunks → 100 summaries → 5 batches → 5 intermediate summaries → final
```

Questo preserva la copertura completa del documento indipendentemente dalla lunghezza - ogni pezzo contribuisce al riepilogo finale. Gli strumenti stimano i token (~4 caratteri/token) e puntano all'utilizzo del 60% della finestra del contesto per il pass di riduzione.

**Pro**: Veloce, copertura completa, elaborazione parallela, gestisce qualsiasi lunghezza del documento
**Contro**: Può perdere collegamenti di sezione trasversale, più lento per documenti molto lunghi

### RAG (Migliore per le missioni concentrate)

Meglio quando hai bisogno di concentrarsi su argomenti specifici o avere una domanda mirata.

```bash
docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v
```

**Come funziona**:

1. Indexes document chunks as vector embeddings in Qdrant
2. Estrae argomenti chiave dalle rubriche dei documenti
3. Recupera pezzi rilevanti per argomento utilizzando la ricerca semantica
4. Sintesi con citazioni

**Quando usare RAG sopra MapReduce**:

| Scenario | Modalità migliore |
|----------|-----------|
| "Summarizza l'intero documento" | MapReduce |
| "What does this say about security?" | RAG |
| Manuale di 500 pagine, bisogno di tutto | MapReduce (gerarchico) |
| Manuale a 500 pagine, sezione specifica richiesta | RAG |
| Bisogno di risultati veloci, non hanno Qdrant | MapReduce |

RAG è **non** circa la gestione di documenti lunghi - MapReduce maniglie che con riduzione gerarchica. RAG è circa **Filtraggio di rilevanza**: quando si vuole ignorare il 90% di un documento e concentrarsi su ciò che conta per la vostra domanda specifica.

**Pro**: Topic-focused, comprensione semantica, indice riutilizza, più veloce per le query focalizzate
**Contro**: Può perdere il contenuto al di fuori dell'area di messa a fuoco, richiede Qdrant, più lento indicizzazione iniziale

### Iterativo

Meglio per i documenti narrativi dove il contesto scorre in sequenza.

```bash
docsummarizer -f story.pdf -m Iterative -v
```

**Attenzione**: Più lento e può perdere il contesto su documenti lunghi (> 10 pezzi).

## Guida al documento di grandi dimensioni

### Scegliere la modalità giusta

| Tipo di documento | Obiettivo | Modalità | Perché |
|---------------|------|------|-----|
| Specifiche tecniche (50+ pagine) | Riepilogo completo | MapReduce | Copertura completa |
| Novel/Narrativo | Riassunto completo | MapReduce | Necessita di contesto temporale |
| Contratto legale | Riepilogo completo | MapReduce | Impossibile perdere le clausole |
| Contratto legale | "Termini di pagamento?" | RAG | Focus sulla sezione specifica |
| API docs (200 pagine) | "How does auth work?" | RAG | Query specific topic |
| Carta di ricerca | Riepilogo completo | MapReduce | Strutturato, bisogno di tutto |

### Fiction vs Non-Fiction

| Tipo di contenuto | Modalità migliore | Note |
|--------------|-----------|-------|
| **Fiction/Narrative** | MapReduce | Plot requires sequencing context |
| **Documenti tecnici** | Entrambi | MapReduce for overview, RAGs for specifics |
| **Legale/Contratti** | MapReduce | Ogni clausola riguarda |
| **Manuali** | RAG | Solitamente interrogazione per specifiche |

### Prestazioni

| Dimensioni del documento | MapReduce | RAG | Note |
|---------------|-----------|-----|-------|
| 10 pagine | 15s | 20s | Entrambe veloci |
| 50 pagine | 45s | 30s | RAG più veloci se messi a fuoco |
| 200 pagine | 3-5 min | 1-2 min | Riduzione gerarchica |
| 500+ pagine | 10-15 min | 2-3 min | Considerare più domande RAG |

## Configurazione

### Genera configurazione predefinita

```bash
docsummarizer config --output myconfig.json
```

### File di configurazione

La configurazione è auto-scoperta da:

1. `--config` opzione
2. `docsummarizer.json` nella directory corrente
3. `.docsummarizer.json` (file nascosto)
4. `~/.docsummarizer.json` (user home)

Esempio `docsummarizer.json`:

```json
{
  "embeddingBackend": "Onnx",
  "onnx": {
    "embeddingModel": "AllMiniLmL6V2"
  },
  "ollama": {
    "model": "llama3.2:3b",
    "embedModel": "mxbai-embed-large",
    "baseUrl": "http://localhost:11434",
    "temperature": 0.3,
    "timeoutSeconds": 1200
  },
  "docling": {
    "baseUrl": "http://localhost:5001",
    "timeoutSeconds": 1200,
    "pdfBackend": "pypdfium2",
    "pagesPerChunk": 10,
    "maxConcurrentChunks": 4,
    "enableSplitProcessing": true
  },
  "qdrant": {
    "host": "localhost",
    "port": 6333,
    "collectionName": "documents"
  },
  "processing": {
    "maxHeadingLevel": 2,
    "targetChunkTokens": 1500,
    "minChunkTokens": 200,
    "maxLlmParallelism": 2
  },
  "output": {
    "format": "Console",
    "verbose": false,
    "includeTrace": false
  },
  "webFetch": {
    "enabled": false,
    "mode": "Simple",
    "timeoutSeconds": 30,
    "userAgent": "Mozilla/5.0 DocSummarizer/1.0"
  },
  "batch": {
    "fileExtensions": [".pdf", ".docx", ".md", ".txt", ".html"],
    "recursive": false,
    "continueOnError": true
  }
}
```

### Opzioni di elaborazione

| Opzione | Predefinito | Descrizione |
|--------|---------|-------------|
| `maxLlmParallelism` | 8 | Richieste LLM concomitanti (code di Ollama, quindi valori più alti solo coda) |
| `maxHeadingLevel` | 2 | Split on H1/H2 only. Set to 3 for finer granularity |
| `targetChunkTokens` | 0 (auto) | Dimensione del pezzo di destinazione. 0 = calcolo automatico (~25% della finestra del contesto) |
| `minChunkTokens` | 0 (auto) | Minimo prima della fusione. 0 = 1/8 dell'obiettivo |

## Formato di output

### Struttura sintetica

```C:\Blog\mostlylucidweb\Mostlylucid\Markdown\docsummarizer-tool.md
## Executive Summary
- Key finding 1 with specific details [chunk-0]
- Important point 2 with numbers and dates [chunk-3]
- Critical requirement 3 [chunk-5]

## Section Highlights
- Introduction: Overview of the system architecture [chunk-0]
- Requirements: Technical specifications detailed [chunk-3]
...

## Open Questions
- What is the timeline for Phase 2?
- How does the fallback mechanism work?

### Trace

- Document: document.pdf
- Chunks: 12 total, 12 processed
- Topics: 5
- Time: 21.4s
- Coverage: 100%
- Citation rate: 1.20
```

**Traccia metriche**: Copertura (% sezioni incluse), Citazione (citazioni/bullet), Chunk elaborati (RAG può saltare alcuni).

## Raccomandazioni del modello

| Model | Size | Speed | Quality | Use case |
|-------|------|-------|---------|----------|
| `qwen2.5:1.5b` | 986MB | Molto veloce (~3s) | Buono | Velocità ottimizzata |
| `gemma3:1b` | 815MB | Fast (~10s) | Fair | Alternative small model |
| `llama3.2:3b` | 2GB | Medio (~15s) | Molto buono | **Predefinito** - buon equilibrio |
| `ministral-3:3b` | 2.9GB | Medium (~20s) | Very Good | Quality-focused |
| `llama3.1:8b` | 4.7GB | Slow (~45s) | Excellent | High-quality sommations |

> **Suggerimento**: Per i riassunti più veloci (~3s vs ~15s), usare `--model qwen2.5:1.5b`. Per i documenti critici dove la qualità è più importante, utilizzare `--model llama3.1:8b`.

## Costruisci dalla sorgente

```bash
# Clone the repository
git clone https://github.com/scottgal/mostlylucidweb.git
cd mostlylucidweb/Mostlylucid.DocSummarizer

# Build
dotnet build

# Run
dotnet run -- --help
```

### Build auto-contenuti

Per l'implementazione della produzione senza necessità di installazione di runtime .NET:

```bash
# Build self-contained executable (Windows x64)
dotnet publish -c Release -r win-x64 --self-contained

# Build for Linux
dotnet publish -c Release -r linux-x64 --self-contained

# Build for macOS
dotnet publish -c Release -r osx-x64 --self-contained
```

Output: `bin/Release/net9.0/<runtime>/publish/docsummarizer`

## Risoluzione dei problemi

### "Non potevo connettermi a Ollama"

- Assicurati che Ollama sia in esecuzione: `ollama serve`
- I modelli di controllo sono tirati: `ollama list`

### "Servizio di somministrazione non disponibile"

- Questo e' **richiesto solo per i file PDF/DOCX**
- Per i file Markdown, è possibile ignorare questo errore
- Per risolvere: `docker run -p 5001:5001 quay.io/docling-project/docling-serve`

### "Connessione Qdrant non riuscita"

- Questo e' **Solo per la modalità RAG** (`--mode Rag`)
- Per MapReduce mode (default), è possibile ignorare questo errore
- Per risolvere: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant`

### "L'interruttore è aperto"

- Ollama è sovraccaricato o si è schiantato
- Attendere 30 secondi per ripristinare l'interruttore o riavviare Ollama
- Lo strumento utilizza politiche di resilienza Polly e si auto-recupererà

### "wsarecv" o Errori di connessione (Windows)

- Questo è un problema noto Ollama su Windows (GitHub #13340)
- Lo strumento auto-gestisce questo con riprova logica e recupero di connessione
- Se persistente, riavviare Ollama e riprovare

### "La generazione dell'LLM è cronometrata"

- Aumenta il timeout nella configurazione
- Dividere documenti molto grandi
- Check Ollama non è sovraccaricato con altre richieste

### Sommari ripetitivi o di bassa qualità

**Sintomi** Note  Bibliografia  Altri progetti  Collegamenti esterni * Sito ufficiale

**Causa**: Modello che lotta con il prompt o il contenuto troppo a lungo.

**Correggi**: L'impostazione predefinita `qwen2.5:1.5b` Gestisce la maggior parte dei documenti bene. Per documenti problematici, prova `--model llama3.2:3b`. Vedi [Raccomandazioni del modello](#model-recommendations).

### Sommario Ignora il contenuto del documento

Se il riassunto sembra generico o non fa riferimento a contenuti specifici:

- Il modello può avere allucinazioni - controllare `Citation rate` in uscita traccia
- Prova la modalità RAG (`--mode Rag`) che motiva i riassunti in pezzi recuperati
- Uso `--verbose` per vedere quali pezzi vengono elaborati

### Citazioni mancanti o non valide

In caso di mancanza di sommari `[chunk-N]` citazioni:

- Piccoli modelli danno priorità al contenuto rispetto alla formattazione della citazione
- I prompt sono ottimizzati per la velocità, non rigorosa conformità citazione
- Per citazioni rigorose, utilizzare modelli più grandi come `llama3.2:3b`
- Controlla `Citation rate` in traccia - valori più elevati indicano una migliore tracciabilità

## Suggerimenti per le prestazioni

- **MapReduce** per la velocità (pezzi paralleli)
- **`qwen2.5:1.5b`** per la velocità, **`llama3.2:3b`** per l'equilibrio, **`llama3.1:8b`** per la qualità
- **Inserzioni ONNX** (default) sono più veloci di Ollama per la modalità RAG
- Abbassa **`maxLlmParallelism`** se si verificano timeout

## Risorse

- [Codice sorgente](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.DocSummarizer)
- [Rilascia GitHub](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
- [Aggancio](https://github.com/docling-project/docling) / [Servo docling](https://github.com/docling-project/docling-serve)
- [QdrantCity name (optional, probably does not need a translation)](https://qdrant.tech/) - Base dati vettoriale locale
- [OllamaCity name (optional, probably does not need a translation)](https://ollama.ai/) / [OllamaSharpCity name (optional, probably does not need a translation)](https://github.com/awaescher/OllamaSharp)
- [PollyCity name (optional, probably does not need a translation)](https://github.com/App-vNext/Polly) - Resistenza .NET e gestione dei guasti transitori
- [Spectre.Console](https://spectreconsole.net/) - Bella UI terminale

## Navigazione serie

- **[Parte 1: Costruire un sintetizzatore di documenti con RAG](/blog/building-a-document-summarizer-with-rag)** - L'architettura e i modelli
- **[Parte 2: Uso dello strumento](/blog/docsummarizer-tool)** (questo articolo) - Guida rapida
- **[Parte 3: Concetti avanzati](/blog/docsummarizer-advanced-concepts)** - Immersione profonda in BERT, ONNX, embeddings, e la ricerca ibrida

### correlati

- [Analisi CSV con LLM locali](/blog/analysing-large-csv-files-with-local-llms)
- [Contenuto Web con LLM](/blog/fetching-and-analysing-web-content-with-llms)