# DocSummarizer Parte 2 - Uso de la herramienta
2025-12-21T11:00
[](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
[](https://dotnet.microsoft.com/)
[](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
Esto es **Parte 2** de la serie DocSummarizer. Véase [Parte 1](/blog/building-a-document-summarizer-with-rag) para la arquitectura y los patrones, o [Parte 3](/blog/docsummarizer-advanced-concepts) 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.
```bash
# 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](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid.DocSummarizer/README.md). Para ver cómo funciona internamente, véase [Parte 3](/blog/docsummarizer-advanced-concepts).
[TOC]
## Por qué existe esto
La mayoría de los resúmenes le dan texto. Esto le da *pruebas*.
- **Todas las reclamaciones incluyen: `[chunk-N]` citaciones** volver al material de origen
- **Niveles de confianza** (alto/medio/bajo) sobre la base de pruebas justificativas
- **Salida JSON estructurada** para la integración de agentes, tuberías de CI o servidores MCP
- **métricas de calidad** atrapar alucinaciones antes de escapar
Si es necesario *confianza* un resumen - o alimentarlo a otro sistema - que importa.
## Características
- **BertRag Pipeline**: Producción-grado BERT extracción → recuperación → LLM síntesis
- **Modo automático**: Selección de modo inteligente basada en documento y consulta
- **• Modo Bert**: Puro resumen extractivo - no se necesita LLM, funciona fuera de línea (~3-5s)
- **Producto redondeado con pruebas**: Citaciones, niveles de confianza, reclamaciones rastreables
- **Modos múltiples**: Auto, BertRag, Bert, BertHybrid, MapReduce, Rag, Iterativo
- **Modo de herramienta**: Limpia JSON para agentes LLM, servidores MCP, chequeos CI
- **13 Plantillas**: default, prosa, breve, oneliner, balas, ejecutivo, detallado, técnico, académico, citas, bookreport, reunión, estricto
- **Documentos de gran tamaño**: Maneja más de 500 páginas con procesamiento jerárquico
- **Obtención de páginas web**: Seguridad endurecida (protección SSRF, desinfección HTML)
- **Modo de reproducción**: Navegador sin cabeza para páginas con JavaScript (SPAs, React apps)
- **Incrustaciones ONNX**: Incrustaciones locales de configuración cero - modelos de descarga automática en el primer uso
- **Análisis de calidad**: Detección de alucinaciones, extracción de entidades
- **LLM resiliente**: Reintentar basado en Polly con jitter backoff + interruptor disyuntor
- **Solo local**: Nada sale de tu máquina
## Usar como herramienta LLM
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.
### Uso básico de la herramienta
```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'
```
### Estructura de salida de la herramienta
El comando tool devuelve JSON estructurado con seguimiento de evidencia:
```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"
}
}
```
### Opciones de comandos de herramientas
```bash
docsummarizer tool [options]
```
# Opción # # Corta # # Descripción #
|--------|-------|-------------|
| `--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
### Principios de diseño clave
- **Justificación de las pruebas**: Cada reclamación incluye: `evidence` IDs que hacen referencia a trozos de origen
- **Niveles de confianza**: Las reclamaciones están calificadas `high`, `medium`, o `low` sobre la base de pruebas justificativas
- **Salida limpia**: El `executive` resumen no tiene marcadores de citas para una fácil visualización
- **Metadatos**: Las estadísticas de procesamiento ayudan con la depuración y la evaluación de la calidad
- **Manejo de errores**: Fallas de retorno `success: false` con una `error` mensaje
### Ejemplos de integración
**Guión de 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']}")
```
**Gasoducto 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'
```
## Inicio rápido
### Descargar binarios preconstruidos
Los ejecutables nativos pre-construidos están disponibles en [Liberaciones de GitHub](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer):
Plataforma Arquitectura Descargar
|----------|--------------|----------|
# Ventanas # # x64 # `docsummarizer-win-x64.zip` |
# Windows # # ARM64 # `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` |
Linux ARM64 `docsummarizer-linux-arm64.tar.gz` |
macOS x64 (Intel) `docsummarizer-osx-x64.tar.gz` |
macOS ARM64 (Apple Silicon) `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 "."
```
### Requisitos previos
#### Modo Bert (sin servicios externos)
Para la sumarización pura extractiva, **no se requieren servicios externos**:
```bash
docsummarizer -f document.md -m Bert
```
Los modelos ONNX descargan automáticamente de HuggingFace al primer uso (~23MB). Devuelve en ~3-5 segundos.
#### Modos LLM (Auto, BertRag, MapReduce, etc.)
Para la sumarización con LLM, se requiere Ollama:
```bash
# 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`
#### Opcional: Docling (Formatos binarios)
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.**
```bash
docker run -d -p 5001:5001 quay.io/docling-project/docling-serve
```
#### Opcional: Qdrant (Almacenamiento de vectores persistentes)
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:
```bash
docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant
```
A continuación, configurar en `docsummarizer.json`:
```json
{
"bertRag": {
"vectorStore": "Qdrant",
"collectionName": "docsummarizer",
"persistVectors": true
}
}
```
#### Opcional: Ollama Embeddings
Si prefiere Ollama para incrustaciones en lugar de ONNX:
```bash
ollama pull nomic-embed-text # Or mxbai-embed-large
# Then use: --embedding-backend Ollama
```
### Verificar las dependencias
```bash
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.
## Uso
### Comportamiento predeterminado
Correr `docsummarizer` sin argumentos:
1. Busca `README.md` en el directorio actual
2. Resumirlo usando **Modo automático** (Selección de modo inteligente)
3. Imprima el resumen en consola con una buena interfaz de usuario de panel
4. Guardar automáticamente en `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
```
### Resumen básico
```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
```
## Modos de resumen
La herramienta evolucionó de "sólo MapReduce" a una tubería completa. Esto es lo que cada modo realmente hace:
### Auto (Default)
Elige el modo correcto basado en lo que estás pidiendo. Usa esto a menos que tengas una razón para no hacerlo.
```bash
docsummarizer -f doc.pdf
```
### BertRag (Producción)
Esto es lo que quieres para la producción.
1. **Extracto** - Analizar el documento en segmentos, incrustarlos con BERT
2. **Recuperar** - Encontrar los segmentos relevantes (búsqueda semántica + puntuación de relevancia)
3. **Sintetizado** - LLM escribe un resumen fluido de esos segmentos
```bash
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).
### Bert (rápido, no LLM)
Extracción pura utilizando modelos ONNX locales. Ninguna llamada LLM en absoluto.
```bash
docsummarizer -f doc.pdf -m Bert
```
**¿Por qué usarlo:** Funciona fuera de línea. Devuelve en ~3-5 segundos. Determinista (misma entrada = misma salida).
### BertHybrid
Extractos BERT, pulidos LLM. Medio terreno entre Bert y BertRag.
```bash
docsummarizer -f doc.pdf -m BertHybrid
```
### MapaReduce / Rag / Iterativo
Los modos originales. Todavía funcionan, pero BertRag los reemplazó para la mayoría de los casos de uso.
- **MapReduce**: Recorte paralelo, bueno para una cobertura del 100%
- **Rag**: Búsqueda de vectores, bueno para consultas enfocadas (legado - BertRag hace esto mejor)
- **Iterativo**: Procesamiento secuencial, sólo uso para los documentos minúsculos
```bash
docsummarizer -f doc.pdf -m MapReduce # Full coverage
docsummarizer -f doc.pdf -m Rag --focus "query" # Legacy focused mode
```
### Modo de consulta
En lugar de resumir, haga preguntas sobre un documento:
```bash
docsummarizer -f manual.pdf --query "How do I install the software?"
```
### Obtención de URL web
Resuma las páginas web directamente sin descargar:
```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
```
**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).
### Modo estructurado
Extraer JSON legible por máquina en lugar de prosa:
```bash
docsummarizer -f document.pdf --structured -o Json
```
Extractos: entidades, funciones, flujos clave, hechos (con niveles de confianza), incertidumbres, pasajes con cuotas.
### Plantillas de resumen
```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
```
# Plantilla # # Palabras # # Mejor para #
|----------|-------|----------|
| `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:
```bash
docsummarizer templates
```
### Criterio de referencia del modelo
Comparar modelos en el mismo documento usando el `benchmark` subcomando:
```bash
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.
### Procesamiento por lotes
Procesar directorios completos:
```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
```
### Opciones de línea de órdenes
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` |
| `--embedding-model` Nombre del modelo ONNX (modo RAG) `AllMiniLmL6V2` |
| `--web-mode` Web buscar modo: Simple, Playwright `Simple` |
| `--analyze` | `-a` Ejecutar análisis de calidad en resumen `false` |
## Modos de resumen
### MapReduce (recomendado)
Mejor para resúmenes completos con cobertura completa de documentos.
```bash
docsummarizer -f document.pdf -m MapReduce -v
```
**Cómo funciona**:
1. Se divide el documento en trozos estructurales (por rúbricas)
2. Resuma cada trozo en paralelo usando LLM
3. Reduce los resúmenes en resumen ejecutivo con citas
4. Valida todas las citas referencia reales trozos
**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:
1. **Batching**: Agrupa resúmenes en lotes que encajan en el contexto
2. **Reducción intermedia**: Reduce cada lote a un resumen condensado
3. **Reducción final**: Fusiona resúmenes intermedios en el resultado final
4. **Recursivo**: Si los intermedios son todavía demasiado grandes, agrega más niveles
```
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
### RAG (Mejor para consultas centradas)
Mejor cuando necesitas enfocarte en temas específicos o tener una pregunta específica.
```bash
docsummarizer -f document.pdf -m Rag --focus "pricing and payment terms" -v
```
**Cómo funciona**:
1. Indexes pedazos de documentos como incrustaciones de vectores en Qdrant
2. Extrae temas clave de los títulos de los documentos
3. Recupera trozos relevantes por tema mediante búsqueda semántica
4. Sintetiza resumen enfocado con citas
**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
### Iterativo
Mejor para documentos narrativos donde el contexto fluye secuencialmente.
```bash
docsummarizer -f story.pdf -m Iterative -v
```
**Aviso**: Más lento y puede perder contexto en documentos largos (> 10 trozos).
## Guía del documento grande
### Elegir el modo correcto
# Tipo de documento # # Meta # # Modo # # Por qué #
|---------------|------|------|-----|
Especificaciones técnicas (50+ páginas) Resumen completo MapaReduce la cobertura completa
Novela/Narrativa Resumen completo MapaReduce Necesidades contexto temporal
# Contrato legal # # Resumen completo # # MapReduce # # No puedes faltar a las cláusulas #
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
### Ficción vs. no ficción
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
### Desempeño
# Tamaño del documento # # MapReduce # # RAG # # Notas #
|---------------|-----------|-----|-------|
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
## Configuración
### Generar configuración predeterminada
```bash
docsummarizer config --output myconfig.json
```
### Archivo de configuración
La configuración es auto-descubierta desde:
1. `--config` opción
2. `docsummarizer.json` en el directorio actual
3. `.docsummarizer.json` (archivo oculto)
4. `~/.docsummarizer.json` (usuario de casa)
Ejemplo `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
}
}
```
### Opciones de procesamiento
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
## Formato de salida
### Estructura resumida
```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
```
**métricas de trazas**: Cobertura (% secciones incluidas), Tasa de citación (citas/bullet), Chunks procesados (RAG puede omitir algunos).
## Recomendaciones modelo
# Modelo # Tamaño # # Velocidad # # Calidad # # Caso de uso #
|-------|------|-------|---------|----------|
| `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`.
## Construir desde la fuente
```bash
# Clone the repository
git clone https://github.com/scottgal/mostlylucidweb.git
cd mostlylucidweb/Mostlylucid.DocSummarizer
# Build
dotnet build
# Run
dotnet run -- --help
```
### Edificios autocontenidos
Para el despliegue de producción sin necesidad de instalación de tiempo de funcionamiento .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
```
Producto: `bin/Release/net9.0//publish/docsummarizer`
## Solución de problemas
### "No se podía conectar con Ollama"
- Asegúrese de que Ollama se está ejecutando: `ollama serve`
- Los modelos de comprobación se tiran: `ollama list`
### "Servicio de consulta no disponible"
- Esto es **sólo se requiere para archivos PDF/DOCX**
- Para los archivos Markdown, puede ignorar este error
- Para arreglar: `docker run -p 5001:5001 quay.io/docling-project/docling-serve`
### "Falló la conexión Qdrant"
- Esto es **solo se requiere para el modo RAG** (`--mode Rag`)
- Para el modo MapReduce (predeterminado), puede ignorar este error
- Para arreglar: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant`
### "El interruptor de circuito está abierto"
- Ollama está sobrecargado o se ha estrellado
- Espere 30 segundos para que el interruptor se reinicie o reinicie Ollama
- La herramienta utiliza políticas de resiliencia de Polly y se auto-retratará
### "wsarecv" o errores de conexión (Windows)
- Este es un problema conocido de Ollama en Windows (GitHub #13340)
- La herramienta auto-maneja esto con lógica de reintento y recuperación de la conexión
- Si es persistente, reinicie Ollama e inténtelo de nuevo
### "Generación LLM cronometrada"
- Aumentar el tiempo de espera en la configuración
- Dividir documentos muy grandes
- Comprobar que Ollama no está sobrecargado con otras peticiones
### Resúmenes repetitivos o de baja calidad
**Sí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](#model-recommendations).
### Resumen Ignora el contenido del documento
Si el resumen parece genérico o no hace referencia al contenido específico:
- El modelo puede ser alucinante - comprobar `Citation rate` en traza de salida
- Probar el modo RAG (`--mode Rag`) que presenta resúmenes en trozos recuperados
- Uso `--verbose` para ver qué trozos se están procesando
### Citas que faltan o no son válidas
Si no hay resúmenes `[chunk-N]` citaciones:
- Los modelos pequeños priorizan el contenido sobre el formato de citación
- Las indicaciones están optimizadas para la velocidad, no para el cumplimiento estricto de las citas
- Para citas estrictas, utilice modelos más grandes como `llama3.2:3b`
- Comprobar `Citation rate` en traza - valores más altos indican una mejor trazabilidad
## Consejos de rendimiento
- **MapReduce** para la velocidad (piezas paralelas)
- **`qwen2.5:1.5b`** para la velocidad, **`llama3.2:3b`** para el saldo, **`llama3.1:8b`** para la calidad
- **Incrustaciones ONNX** (por defecto) son más rápidos que Ollama para el modo RAG
- Más abajo **`maxLlmParallelism`** si experimenta tiempo muerto
## Recursos
- [Código fuente](https://github.com/scottgal/mostlylucidweb/tree/main/Mostlylucid.DocSummarizer)
- [Liberaciones de GitHub](https://github.com/scottgal/mostlylucidweb/releases?q=docsummarizer)
- [Acoplamiento](https://github.com/docling-project/docling) / [Adornos Servir](https://github.com/docling-project/docling-serve)
- [Qdrant](https://qdrant.tech/) - Base de datos de vectores locales
- [Ollama](https://ollama.ai/) / [OllamaSharp](https://github.com/awaescher/OllamaSharp)
- [Polly](https://github.com/App-vNext/Polly) - Resiliencia de .NET y manipulación de fallos transitorios
- [Espectro.Consola](https://spectreconsole.net/) - Hermosa terminal de interfaz de usuario
## Navegación en serie
- **[Parte 1: Construcción de un resumen de documentos con RAG](/blog/building-a-document-summarizer-with-rag)** - La arquitectura y los patrones
- **[Parte 2: Uso de la herramienta](/blog/docsummarizer-tool)** (Este artículo) - Guía de inicio rápido
- **[Parte 3: Conceptos avanzados](/blog/docsummarizer-advanced-concepts)** - Inmersión profunda en BERT, ONNX, incrustaciones y búsqueda híbrida
### Relacionados
- [Análisis CSV con LLM locales](/blog/analysing-large-csv-files-with-local-llms)
- [Contenido Web con LLMs](/blog/fetching-and-analysing-web-content-with-llms)