DocSummarizer Parte 2 - Uso dello strumento

Sunday, 21 December 2025

Questo e' Parte 2 della serie DocSummarizer. Vedi Parte 1 per l'architettura e i modelli, o Parte 3 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.

# 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. Per come funziona internamente, vedere Parte 3.

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à multipleAuto, 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

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

{
  "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

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:

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:

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

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`

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

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:

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

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:

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

Quindi configura in docsummarizer.json:

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

Facoltativo: Inserimento di Ollama

Se preferisci Ollama per l'imbottitura invece di ONNX:

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

Verifica le dipendenze

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:

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

# 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

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

docsummarizer -f doc.pdf

BertRag (produzione)

Questo è ciò che volete per la produzione.

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

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.

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.

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

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:

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

Recupero URL web

Sintesi delle pagine web direttamente senza scaricare:

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

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

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

Modelli sommari

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

docsummarizer templates

Modello di benchmarking

Confronta i modelli sullo stesso documento utilizzando il benchmark sottocomando:

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:

# 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

Modalità di sintesi

MapReduce (Consigliato)

Meglio per riassunti completi con una copertura completa dei documenti.

docsummarizer -f document.pdf -m MapReduce -v

Come funziona:

Divide il documento in pezzi strutturali (per rubrica)
Riepiloga ogni pezzo in parallelo usando LLM
Riduce i riassunti in sintesi con le citazioni
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:

Lotto: Gruppi sommari in lotti che si adattano nel contesto
Riduzione intermedia: Riduce ogni lotto in un riassunto condensato
Riduzione finale: Unisce i riassunti intermedi nell'output finale
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.

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

Come funziona:

Indexes document chunks as vector embeddings in Qdrant
Estrae argomenti chiave dalle rubriche dei documenti
Recupera pezzi rilevanti per argomento utilizzando la ricerca semantica
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.

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

docsummarizer config --output myconfig.json

File di configurazione

La configurazione è auto-scoperta da:

--config opzione
docsummarizer.json nella directory corrente
.docsummarizer.json (file nascosto)
~/.docsummarizer.json (user home)

Esempio docsummarizer.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

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

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

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

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
Rilascia GitHub
Aggancio / Servo docling
QdrantCity name (optional, probably does not need a translation) - Base dati vettoriale locale
OllamaCity name (optional, probably does not need a translation) / OllamaSharpCity name (optional, probably does not need a translation)
PollyCity name (optional, probably does not need a translation) - Resistenza .NET e gestione dei guasti transitori
Spectre.Console - Bella UI terminale

Navigazione serie

Parte 1: Costruire un sintetizzatore di documenti con RAG - L'architettura e i modelli
Parte 2: Uso dello strumento (questo articolo) - Guida rapida
Parte 3: Concetti avanzati - Immersione profonda in BERT, ONNX, embeddings, e la ricerca ibrida

DocSummarizer Parte 2 - Uso dello strumento

Perché questo esiste

Caratteristiche

Usare come strumento LLM

Uso dello strumento di base

Struttura dell' output strumento

Opzioni dei comandi strumenti

Principi chiave di progettazione

Esempi di integrazione

Avvio rapido

Scarica i binari pre-costruiti

Prerequisiti

Modalità Bert (senza servizi esterni)

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

Facoltativo: docling (Formati binari)

Facoltativo: Qdrant (Persistent Vector Storage)

Facoltativo: Inserimento di Ollama

Verifica le dipendenze

Uso

Comportamento predefinito

Sintesi di base

Modalità di sintesi

Auto (predefinito)

BertRag (produzione)

BERT (Fast, No LLM)

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

MapReduce / Rag / Iterative

Modalità interrogazione

Recupero URL web

Modalità strutturata

Modelli sommari

Modello di benchmarking

Elaborazione di lotti

Opzioni della linea di comando

Modalità di sintesi

MapReduce (Consigliato)

RAG (Migliore per le missioni concentrate)

Iterativo

Guida al documento di grandi dimensioni

Scegliere la modalità giusta

Fiction vs Non-Fiction

Prestazioni

Configurazione

Genera configurazione predefinita

File di configurazione

Opzioni di elaborazione

Formato di output

Struttura sintetica

Raccomandazioni del modello

Costruisci dalla sorgente

Build auto-contenuti

Risoluzione dei problemi

"Non potevo connettermi a Ollama"

"Servizio di somministrazione non disponibile"

"Connessione Qdrant non riuscita"

"L'interruttore è aperto"

"wsarecv" o Errori di connessione (Windows)

"La generazione dell'LLM è cronometrata"

Sommari ripetitivi o di bassa qualità

Sommario Ignora il contenuto del documento

Citazioni mancanti o non valide

Suggerimenti per le prestazioni

Risorse

Navigazione serie

correlati