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.
La maggior parte dei sintetizzatori ti danno testo. Questo ti dà prove.
[chunk-N] citazioni Ritorna al materiale sorgenteSe hai bisogno di fiducia una sintesi - o alimentarla ad un altro sistema - che conta.
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.
# 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'
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"
}
}
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 |
evidence ID che fanno riferimento ai pezzi sorgentehigh, medium, oppure low sulla base di elementi di prova a sostegnoexecutive sommario non ha marcatori di citazione per una visualizzazione facilesuccess: false con error messaggioScript 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'
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 "."
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.
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
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
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
}
}
Se preferisci Ollama per l'imbottitura invece di ONNX:
ollama pull nomic-embed-text # Or mxbai-embed-large
# Then use: --embedding-backend Ollama
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.
In esecuzione docsummarizer senza argomenti:
README.md nella directory correntereadme.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
# 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
Lo strumento si è evoluto da " just MapReduce" a una pipeline completa. Ecco cosa fa in realtà ogni modalità:
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
Questo è ciò che volete per la produzione.
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).
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.
Estratti di BERT, lucidanti LLM... terreno intermedio tra Bert e BertRag.
docsummarizer -f doc.pdf -m BertHybrid
Le modalità originali. Funziona ancora, ma BertRag le ha sostituite per la maggior parte dei casi d'uso.
docsummarizer -f doc.pdf -m MapReduce # Full coverage
docsummarizer -f doc.pdf -m Rag --focus "query" # Legacy focused mode
Invece di riassumere, fare domande su un documento:
docsummarizer -f manual.pdf --query "How do I install the software?"
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).
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.
# 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
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.
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
| 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 |
Meglio per riassunti completi con una copertura completa dei documenti.
docsummarizer -f document.pdf -m MapReduce -v
Come funziona:
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:
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
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:
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
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).
| 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 |
| 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 |
| 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 |
docsummarizer config --output myconfig.json
La configurazione è auto-scoperta da:
--config opzionedocsummarizer.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
}
}
| 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 |
## 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).
| 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.
# Clone the repository
git clone https://github.com/scottgal/mostlylucidweb.git
cd mostlylucidweb/Mostlylucid.DocSummarizer
# Build
dotnet build
# Run
dotnet run -- --help
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
ollama serveollama listdocker run -p 5001:5001 quay.io/docling-project/docling-serve--mode Rag)docker run -p 6333:6333 -p 6334:6334 qdrant/qdrantSintomi 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.
Se il riassunto sembra generico o non fa riferimento a contenuti specifici:
Citation rate in uscita traccia--mode Rag) che motiva i riassunti in pezzi recuperati--verbose per vedere quali pezzi vengono elaboratiIn caso di mancanza di sommari [chunk-N] citazioni:
llama3.2:3bCitation rate in traccia - valori più elevati indicano una migliore tracciabilitàqwen2.5:1.5b per la velocità, llama3.2:3b per l'equilibrio, llama3.1:8b per la qualitàmaxLlmParallelism se si verificano timeout
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.