Esto es Parte 2 de la serie DocSummarizer. Véase Parte 1 para la arquitectura y los patrones, o Parte 3 para la inmersión técnica profunda en incrustaciones y recuperación.
Convierta documentos o URLs en resúmenes basados en pruebas - para humanos o agentes de IA - sin enviar nada a la nube.
Cada reclamación es rastreable. Cada hecho cita su fuente. binario autónomo, se ejecuta enteramente en su máquina.
# Human-readable summary
docsummarizer -f contract.pdf
# JSON for agents/pipelines
docsummarizer tool -u "https://docs.example.com"
¿Qué cubre este artículo?: Instalación, modos clave (Auto/BertRag/Bert), plantillas y casos de uso común.
Lo que no cubre: Referencia completa del comando, opciones de configuración, resolución de problemas, detalles de arquitectura.
Para obtener documentación completa, consulte el apartado README. Para ver cómo funciona internamente, véase Parte 3.
La mayoría de los resúmenes le dan texto. Esto le da pruebas.
[chunk-N] citaciones volver al material de origenSi es necesario confianza un resumen - o alimentarlo a otro sistema - que importa.
Los tool comando está diseñado específicamente para la integración con agentes de IA, servidores MCP, y otros sistemas automatizados. Sale JSON estructurado a stdout con reclamaciones basadas en la evidencia - perfecto para la construcción de tuberías RAG o herramientas de agente.
# 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'
El comando tool devuelve JSON estructurado con seguimiento de evidencia:
{
"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]
|--------|-------|-------------|
| --url | -u URL a buscar y resumir
| --file | -f Archivo para resumir
| --query | -q Consulta de enfoque opcional
| --mode | -m Modo de resumen (Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterativo)
| --model Ollama modelo a utilizar
| --config | -c Ruta del archivo de configuración
evidence IDs que hacen referencia a trozos de origenhigh, medium, o low sobre la base de pruebas justificativasexecutive resumen no tiene marcadores de citas para una fácil visualizaciónsuccess: false con una error mensajeGuión de 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']}")
Gasoducto 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'
Los ejecutables nativos pre-construidos están disponibles en Liberaciones de GitHub:
Plataforma Arquitectura Descargar |----------|--------------|----------|
docsummarizer-win-x64.zip |docsummarizer-win-arm64.zip |Linux x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 x64 docsummarizer-linux-x64.tar.gz |
|---|
macOS x64 (Intel) docsummarizer-osx-x64.tar.gz |
macOS ARM64 (Apple Silicon) 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 "."
Para la sumarización pura extractiva, no se requieren servicios externos:
docsummarizer -f document.md -m Bert
Los modelos ONNX descargan automáticamente de HuggingFace al primer uso (~23MB). Devuelve en ~3-5 segundos.
Para la sumarización con LLM, se requiere Ollama:
# Install Ollama from https://ollama.ai
ollama pull llama3.2:3b # Default model - good balance of speed/quality
ollama serve
Punta de velocidad: Para resúmenes más rápidos (~3s vs ~15s), use
--model qwen2.5:1.5b
Requerido para archivos PDF, DOCX, XLSX, PPTX, HTML, imágenes (PNG/JPG/TIFF), CSV, VTT y AsciiDoc. Los archivos Markdown y de texto plano se leen directamente - no se requiere Docling.
docker run -d -p 5001:5001 quay.io/docling-project/docling-serve
No se requiere por defecto - BertRag utiliza vectores en memoria. Habilite Qdrant para el almacenamiento persistente para evitar volver a empotrar documentos en las siguientes ejecuciones:
docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant
A continuación, configurar en docsummarizer.json:
{
"bertRag": {
"vectorStore": "Qdrant",
"collectionName": "docsummarizer",
"persistVectors": true
}
}
Si prefiere Ollama para incrustaciones en lugar de ONNX:
ollama pull nomic-embed-text # Or mxbai-embed-large
# Then use: --embedding-backend Ollama
docsummarizer check --verbose
La salida esperada muestra una tabla formateada:
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: Docling y Qdrant mostrar está bien para los flujos de trabajo sólo Markdown.
Correr docsummarizer sin argumentos:
README.md en el directorio actualreadme.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
La herramienta evolucionó de "sólo MapReduce" a una tubería completa. Esto es lo que cada modo realmente hace:
Elige el modo correcto basado en lo que estás pidiendo. Usa esto a menos que tengas una razón para no hacerlo.
docsummarizer -f doc.pdf
Esto es lo que quieres para la producción.
docsummarizer -f doc.pdf -m BertRag
docsummarizer -f doc.pdf -m BertRag --focus "payment terms"
¿Por qué usarlo: Cada reclamación se remonta a un segmento fuente. No hay alucinaciones. Escalas a cualquier tamaño de documento. LLM sólo se ejecuta al final (barato).
Extracción pura utilizando modelos ONNX locales. Ninguna llamada LLM en absoluto.
docsummarizer -f doc.pdf -m Bert
¿Por qué usarlo: Funciona fuera de línea. Devuelve en ~3-5 segundos. Determinista (misma entrada = misma salida).
Extractos BERT, pulidos LLM. Medio terreno entre Bert y BertRag.
docsummarizer -f doc.pdf -m BertHybrid
Los modos originales. Todavía funcionan, pero BertRag los reemplazó para la mayoría de los casos de uso.
docsummarizer -f doc.pdf -m MapReduce # Full coverage
docsummarizer -f doc.pdf -m Rag --focus "query" # Legacy focused mode
En lugar de resumir, haga preguntas sobre un documento:
docsummarizer -f manual.pdf --query "How do I install the software?"
Resuma las páginas web directamente sin descargar:
# 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
Contenido soportado: HTML (sanitizado), PDF, Markdown, imágenes (OCR), documentos de Office. Imágenes grandes se redimensionan automáticamente.
Seguridad: Protección SSRF, protección de reencuadernación DNS, gating de tipo contenido, protección de bomba de descompresión, desinfección HTML.
Páginas en formato JavaScript: Usar --web-mode Playwright para aplicaciones de SPA y React (autoinstala Chromium en el primer uso).
Extraer JSON legible por máquina en lugar de prosa:
docsummarizer -f document.pdf --structured -o Json
Extractos: entidades, funciones, flujos clave, hechos (con niveles de confianza), incertidumbres, pasajes con cuotas.
# 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
|----------|-------|----------|
| default Resumen equilibrado con temas (2 párrafos)
| prose ~400 Limpio multi-párrafo prosa - sin metadatos
| brief Síntesis rápida de la oración de 2-3
| oneliner ~25 Resumen de una sola oración
| bullets Lista de puntos de bala (5-7 elementos)
| executive Reunión informativa ejecutiva con recomendaciones
| detailed ~1000 Comprensivo con temas completos
| technical ~350 Documentos técnicos con detalles de la aplicación
| academic Formato abstracto académico
| citations auto Citas clave con citas de la fuente solamente
| bookreport ~500 Informe del libro (establecimiento, caracteres, trama, temas)
| meeting Notas de la reunión (decisiones, acciones, preguntas)
| strict ~60 Token-eficiente, 3 balas max, sin cobertura
Para ver todas las plantillas disponibles con descripciones:
docsummarizer templates
Comparar modelos en el mismo documento usando el benchmark subcomando:
docsummarizer benchmark -f doc.pdf -m "qwen2.5:1.5b,llama3.2:3b,ministral-3:3b"
El comando benchmark analiza el documento una vez, luego ejecuta cada modelo en los mismos trozos para una comparación justa. La salida muestra el tiempo, el recuento de palabras y palabras/segundo para cada modelo.
Procesar directorios completos:
# 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
Opción Corta Descripción Predefinida
|--------|-------|-------------|---------|
| --file | -f Ruta al documento (DOCX, PDF, MD) -
| --directory | -d Ruta al directorio para el procesamiento por lotes
| --url | -u URL Web para buscar y resumir
| --web-enabled Habilitar la búsqueda de web (requerido para --url) false |
| --mode | -m Modo de resumen: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterative Auto |
| --structured | -s Usar el modo de extracción estructurado de JSON false |
| --focus Consulta de enfoque para el modo RAG Ninguno
| --query | -q Modo de consulta en lugar de resumen Ninguno
| --model Ollama modelo a utilizar llama3.2:3b |
| --verbose | -v Muestra el progreso detallado con la interfaz de usuario en vivo false |
| --config | -c Ruta al archivo de configuración Auto-descubrimiento
| --output-format | -o Formato de salida: Consola, Texto, Markdown, Json Console |
| --output-dir Directorio de salida para salidas de archivos
| --extensions | -e Extensiones de archivo para modo por lotes Todos los formatos de Docling
| --recursive | -r Directorios de procesos recursivamente false |
| --template | -t Plantilla de resumen (predeterminado, breve, balas, ejecutivo, etc.) default |
| --words | -w Conteo de palabras objetivo (overrides template) Plantilla por defecto
--embedding-backend Embebido motor: Onnx, Ollama Onnx |
|
|---|---|
--web-mode Web buscar modo: Simple, Playwright Simple |
|
--analyze |
-a Ejecutar análisis de calidad en resumen false |
Mejor para resúmenes completos con cobertura completa de documentos.
docsummarizer -f document.pdf -m MapReduce -v
Cómo funciona:
Reducción jerárquica de documentos largos:
Para documentos muy largos en los que los resúmenes combinados superan la ventana contextual del modelo, MapReduce utiliza automáticamente la reducción jerárquica:
100 chunks → 100 summaries → 5 batches → 5 intermediate summaries → final
Esto preserva la cobertura completa del documento independientemente de la longitud - cada trozo contribuye al resumen final. La herramienta estima tokens (~4 caracteres/token) y objetivos 60% utilización de ventanas de contexto por pase de reducción.
Pros: Cobertura rápida, completa, procesamiento paralelo, maneja cualquier longitud de documento Contras: Puede perderse las conexiones de sección transversal, más lento para documentos muy largos
Mejor cuando necesitas enfocarte en temas específicos o tener una pregunta específica.
docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v
Cómo funciona:
Cuándo usar RAG sobre MapReduce:
Escenario Mejor Modo |----------|-----------| "Resumir todo este documento" MapReduce "¿Qué dice esto sobre la seguridad?" manual de 500 páginas, necesita todo MapReduce (jerárquico) Manual de 500 páginas, necesidad específica sección RAG Necesito resultados rápidos, no tengo Qdrant MapReduce
RAG es no sobre el manejo de documentos largos - MapReduce maneja eso con reducción jerárquica. filtrado de relevancia: cuando desea ignorar el 90% de un documento y centrarse en lo que importa a su pregunta específica.
Pros: Enfoque tópico, comprensión semántica, índice de reutilización, más rápido para consultas enfocadas Contras: Puede perderse el contenido fuera del área de enfoque, requiere Qdrant, indexación inicial más lenta
Mejor para documentos narrativos donde el contexto fluye secuencialmente.
docsummarizer -f story.pdf -m Iterative -v
Aviso: Más lento y puede perder contexto en documentos largos (> 10 trozos).
|---------------|------|------|-----| Especificaciones técnicas (50+ páginas) Resumen completo MapaReduce la cobertura completa Novela/Narrativa Resumen completo MapaReduce Necesidades contexto temporal
Contrato legal "Términos de pago?" RAG Focus on specific section API docs (200 páginas) "¿Cómo funciona la autenticación?" RAG Consultar tema específico Documento de investigación Resumen completo MapaReduce Estructurado, necesita todo
Tipo de contenido Mejor modo Notas |--------------|-----------|-------| | Ficción/Narrativa MapaReduce La trama requiere contexto secuencial | Documentos técnicos Tanto MapReduce para una visión general, RAG para detalles | Contratos/jurídicos MapaReduce Cada cláusula importa | Manuales RAG Usualmente consultando para específicos
|---------------|-----------|-----|-------| 10 páginas 15s 20s Ambos rápido 50 páginas 45s 30s RAG más rápido si se centra 200 páginas 3-5 min 1-2 min Reducción jerárquica 500+ páginas 10-15 min 2-3 min Considera múltiples consultas RAG
docsummarizer config --output myconfig.json
La configuración es auto-descubierta desde:
--config opcióndocsummarizer.json en el directorio actual.docsummarizer.json (archivo oculto)~/.docsummarizer.json (usuario de casa)Ejemplo 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
}
}
Opción por defecto Descripción
|--------|---------|-------------|
| maxLlmParallelism 8 Solicitudes LLM concurrentes (colas de Ollama, por lo que los valores más altos sólo cola)
| maxHeadingLevel 2 Dividir en H1/H2 solamente. Set a 3 para la granularidad más fina
| targetChunkTokens 0 (auto) Tamaño del trozo de destino. 0 = auto-calcular (~25% de la ventana de contexto)
| minChunkTokens 0 (auto) Mínimo antes de la fusión. 0 = 1/8 del objetivo
## 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
métricas de trazas: Cobertura (% secciones incluidas), Tasa de citación (citas/bullet), Chunks procesados (RAG puede omitir algunos).
|-------|------|-------|---------|----------|
| qwen2.5:1.5b 986MB Muy rápido (~3s) Buena Velocidad optimizada
| gemma3:1b 815MB Rápido (~10s) Feria Modelo pequeño alternativo
| llama3.2:3b 2GB Medio (~15s) Muy bueno Predeterminado - buen equilibrio
| ministral-3:3b 2.9GB Medio (~20s) Muy bueno Calidad centrada
| llama3.1:8b 4.7GB Lento (~45s) Excelente Resúmenes de alta calidad
Consejo: Para resúmenes más rápidos (~3s vs ~15s), use
--model qwen2.5:1.5b. Para documentos críticos donde la calidad importa más, utilizar--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
Para el despliegue de producción sin necesidad de instalación de tiempo de funcionamiento .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
Producto: 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/qdrantSíntomas: Los puntos de bala se hacen eco del prompt ("Sólo devuelven los puntos de bala", "La regla es...") en lugar de resumir el contenido.
Causa: Modelo que lucha con el prompt o el contenido demasiado tiempo.
Arreglar: El valor predeterminado qwen2.5:1.5b maneja la mayoría de los documentos bien. Para documentos problemáticos, intente --model llama3.2:3b. Véase Recomendaciones modelo.
Si el resumen parece genérico o no hace referencia al contenido específico:
Citation rate en traza de salida--mode Rag) que presenta resúmenes en trozos recuperados--verbose para ver qué trozos se están procesandoSi no hay resúmenes [chunk-N] citaciones:
llama3.2:3bCitation rate en traza - valores más altos indican una mejor trazabilidadqwen2.5:1.5b para la velocidad, llama3.2:3b para el saldo, llama3.1:8b para la calidadmaxLlmParallelism si experimenta tiempo muerto
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.