doc7: Convierte cualquier documento en Markdown listo para IA con comprensión visual

Si alguna vez has intentado alimentar un PDF o un documento escaneado en un pipeline de IA, conoces el dolor. Las herramientas tradicionales de extracción dependen de OCR y analizadores de diseño que a menudo estropean tablas, omiten fórmulas y pierden por completo el significado de los diagramas. doc7 adopta un enfoque diferente: en lugar de intentar analizar el documento carácter por carácter, renderiza cada página como una imagen y permite que un modelo de lenguaje de visión (VLM) lea la página completa, comprendiendo el diseño, las relaciones y el contexto. El resultado es un Markdown limpio y buscable sobre el que tu IA puede razonar.

Por qué la comprensión visual supera a la extracción tradicional

La mayoría de las herramientas de conversión de documentos a Markdown caen en una de tres categorías:

Extracción de formato y texto (como la ruta predeterminada de MarkItDown): Utilizan analizadores específicos de archivo para extraer texto y estructura básica. Funcionan bien para archivos de texto simples, pero fallan en diseños complejos, páginas escaneadas o cualquier cosa con significado visual.
Envoltorios de OCR con modelos de visión (como Zerox): Convierten páginas en imágenes y las envían a una API de visión, pero a menudo están vinculados a un proveedor específico y requieren dependencias adicionales como GraphicsMagick.
Pilas de IA documental dedicadas (como MinerU o Docling): Ejecutan un pipeline de modelos de OCR, diseño, tablas y fórmulas. Son potentes pero pesados: necesitas gestionar múltiples pesos de modelos e infraestructura.

doc7 se salta todo eso. Renderiza cada página a una imagen y la envía a cualquier modelo multimodal compatible con OpenAI que elijas. El modelo ve la página completa—texto, tablas, gráficos, diagramas, incluso las relaciones espaciales entre elementos—y genera Markdown directamente. Esto significa sin pila de OCR, sin tarifas por página y sin dependencia de un servicio de procesamiento de documentos.

Inicio rápido: De cero a Markdown en minutos

Comenzar es sorprendentemente simple. Instala doc7 con una línea, apúntalo a un modelo de visión local (como uno que se ejecute en LM Studio u Ollama) y convierte tu primer documento:

# macOS o Linux
curl -fsSL https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/magicrew/doc7/main/scripts/install.ps1 | iex

# Convertir un documento
doc7 report.pdf

La primera ejecución descubre automáticamente los endpoints de modelos locales (LM Studio y Ollama), te permite elegir un modelo si hay varios disponibles y verifica la comprensión de imágenes antes de guardar tu elección. No se necesita clave API para endpoints locales.

Benchmark del mundo real: doc7 vs. MarkItDown vs. Docling

El proyecto incluye un benchmark abierto que muestra exactamente por qué la comprensión visual importa. Tomaron dos PDFs solo raster (sin capa de texto) y verificaron 15 hechos visuales comprobables por máquina. Usando el mismo modelo qwen3.5-9b a través del mismo endpoint local, doc7 recuperó 15/15 hechos, mientras que MarkItDown con su plugin de OCR obtuvo 9/15, y el pipeline estándar de Docling solo logró 3/15.

Aquí está el desglose:

Sistema	Artículo de atención	Informe visual	Combinado	Markdown crudo
doc7 + qwen3.5-9b	7/7	8/8	15/15	5,293 bytes
MarkItDown 0.1.6 + OCR 0.1.0 + qwen3.5-9b	3/7	6/8	9/15	13,142 bytes
Docling 2.113.0 estándar	1/7	2/8	3/15	2,571,445 bytes
MarkItDown 0.1.6 predeterminado	N/A	N/A	N/A	0 bytes

La ruta predeterminada de MarkItDown devolvió un archivo vacío para ambas entradas solo raster, por eso se marca como N/A. El Markdown crudo de Docling es enorme porque incrusta imágenes de página como Base64—eso no es una puntuación de calidad, solo un diagnóstico.

El benchmark es totalmente reproducible: cada salida cruda, digest SHA-256, regla de puntuación y resultado legible por máquina están comprometidos en el repositorio. Puedes ejecutarlo tú mismo y verificar los resultados.

Un pipeline para cada formato

Una de las fortalezas de doc7 es su cobertura de formatos. Ya sea que estés lidiando con PDF, documentos de Office, escaneos, capturas de pantalla, gráficos, fórmulas o diagramas, todos pasan por el mismo pipeline de comprensión visual. La salida es un único documento Markdown que preserva:

Encabezados, párrafos, listas, citas y código → estructura nativa de Markdown
Tablas y hojas de cálculo → tablas Markdown o HTML con valores y unidades
Notación matemática → LaTeX en línea o en bloque
Gráficos → etiquetas, valores, tendencias y conclusiones como texto buscable
Diagramas y flujos de trabajo → nodos, orden, agrupación y relaciones
Capturas de pantalla y estados de aplicación → estado visible, errores, controles y acciones
Mensajes de correo electrónico → encabezados, cuerpo HTML o texto, imágenes en línea e inventario de adjuntos
Cuadernos Jupyter → celdas Markdown, código fuente, contadores de ejecución, salida de texto, tracebacks y salida visual

Los formatos de entrada admitidos incluyen PDF, DOCX, PPTX, XLSX, EPUB, EML, MHTML, MSG, IPYNB, imágenes (PNG, JPEG, GIF, WebP, BMP, TIFF, SVG) e incluso formatos nativos de texto/datos como Markdown, CSV, JSON, XML y YAML. Los archivos de Office y OpenDocument requieren LibreOffice; el renderizado de PDF usa MuPDF cuando está disponible; HTML, SVG, EPUB y formatos de correo requieren Chrome, Chromium o Edge.

Construido alrededor de la CLI

La interfaz de línea de comandos es el corazón de doc7. Proporciona desde conversión simple hasta características avanzadas como selección de páginas, reanudación y procesamiento por lotes.

Selección de páginas y reanudación

Los documentos largos se pueden procesar en fragmentos, y las páginas fallidas se pueden reintentar sin empezar de nuevo:

# Procesar solo las páginas 5 y 7
doc7 read report.pdf -o report-pages-5-7 --pages 5,7

# Reanudar una ejecución anterior, reintentando páginas fallidas
doc7 read report.pdf -o report-doc7 --resume

El manifiesto registra los recuentos de páginas de origen y la selección de páginas, y las páginas exitosas permanecen byte por byte sin cambios. Si no quedan páginas fallidas, --resume valida los artefactos y reconstruye el Markdown fusionado sin llamar al modelo.

Tuberías y stdin

Puedes canalizar el Markdown fusionado directamente a otra herramienta:

doc7 read report.pdf --stdout > report.md

# O leer desde stdin
cat report.pdf | doc7 read - --stdin-name report.pdf --stdout > report.md

Documentos remotos y directorios

# Leer un directorio recursivamente
doc7 read ./documents -o ./knowledge

# Leer un documento remoto
doc7 read https://example.com/report.pdf -o ./report-doc7

Ejecutar como servicio

Para la integración en sistemas más grandes, doc7 puede ejecutarse como un servicio HTTP asíncrono:

doc7 serve --addr 127.0.0.1:8787 --data-dir ./doc7-server

Envía un documento o archivo ZIP:

curl -F [email protected] http://127.0.0.1:8787/v1/jobs

La respuesta incluye un ID de trabajo. Consulta la URL de estado, luego descarga el Markdown fusionado o el ZIP de artefactos completo:

curl http://127.0.0.1:8787/v1/jobs/<job-id>
curl -o report.md http://127.0.0.1:8787/v1/jobs/<job-id>/markdown
curl -o report-artifacts.zip http://127.0.0.1:8787/v1/jobs/<job-id>/artifacts

Incluso puedes reanudar páginas fallidas en un trabajo:

curl -X POST -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:8787/v1/jobs/<job-id>/resume

La seguridad está integrada: el servicio se ejecuta por defecto en localhost, requiere un token de portador para direcciones de enlace no locales, limita el tamaño de carga y aísla el directorio de cada trabajo.

Uso desde herramientas de IA: Servidor MCP

doc7 incluye un servidor MCP con una herramienta tipada convert_to_markdown. Configura tu cliente MCP para lanzar el binario sobre stdio:

{
  "mcpServers": {
    "doc7": {
      "command": "/ruta/absoluta/a/doc7",
      "args": ["mcp"],
      "env": {
        "DOC7_BASE_URL": "http://127.0.0.1:1234/v1",
        "DOC7_MODEL": "qwen3.5-0.8b",
        "DOC7_CREDENTIAL_STORE": "env"
      }
    }
  }
}

La herramienta acepta una ruta local, directorio, URL HTTP(S) o archivo ZIP y devuelve Markdown más metadatos de conversión estructurados.

Incrustar en Go

El paquete público de Go expone el mismo motor de conversión. Aquí tienes un ejemplo mínimo:

package main

import (
    "context"
    "log"

    "github.com/magicrew/doc7"
)

func main() {
    options := doc7.DefaultReadOptions()
    options.OutputDir = "report-doc7"
    options.BaseURL = "http://127.0.0.1:1234/v1"
    options.Model = "qwen3.5-4b"
    result, err := doc7.Read(context.Background(), "report.pdf", options)
    if err != nil {
        log.Fatal(err)
    }
    if result.Document != nil {
        log.Println(result.Document.MergedMarkdown)
    }
}

También puedes usar Convert y ConvertBatch para APIs explícitas de un solo documento o solo directorio.

Costo y privacidad: Tu modelo, tu infraestructura

doc7 no vende créditos de documentos ni cobra por página. Traes tu propio modelo multimodal—local o privado—y procesas tantos documentos como tu hardware pueda manejar. El costo marginal de otro documento es solo la electricidad y el tiempo de operación.

Esta es una estructura de costos fundamentalmente diferente de las APIs de documentos en la nube:

Opción	Unidad de facturación típica	Costo a medida que crece el volumen de documentos	Ubicación del documento
doc7 + VLM cuantizado local	Sin tarifa por página de doc7	Principalmente hardware existente, electricidad y operaciones	Infraestructura local o privada
AWS Textract	Páginas, con precio por API y característica de análisis	El uso crece con páginas y características	API en la nube
Google Document AI	Páginas, generalmente con precio por procesador y nivel de volumen	El uso crece con páginas y tipo de procesador	API en la nube
Azure Document Intelligence	Páginas, modelo y nivel de precios	El uso crece con páginas y capacidad seleccionada	API en la nube
Alibaba Cloud OCR	Llamadas de pago por uso o paquetes prepagados	El procesamiento continuo consume llamadas o cuota	API en la nube
Tencent Cloud OCR	Llamadas API a través de facturación prepagada o pospagada	El procesamiento continuo consume llamadas o cuota	API en la nube
Baidu AI Cloud OCR	Llamadas API, cuota gratuita y uso pagado	El procesamiento continuo consume llamadas o cuota	API en la nube

Las APIs en la nube siguen siendo útiles cuando quieres capacidad gestionada y no quieres operar un modelo. Pero si quieres eliminar una factura recurrente de analizador de documentos y mantener tus documentos privados, doc7 es el camino.

Características avanzadas

Anclaje de texto

Para PDF y archivos de Office con una capa de texto incrustada, puedes habilitar una verificación opcional de valor exacto:

doc7 read report.pdf --text-grounding

Esto no reemplaza el resultado visual con texto extraído. En cambio, verifica números exactos, códigos e identificadores de la capa de texto incrustada y pide al modelo visual que confirme correcciones candidatas. Está desactivado por defecto y puede hacer solicitudes adicionales al modelo.

Fallbacks de contexto

Si la ventana de contexto del modelo es demasiado pequeña para una página, doc7 reintenta automáticamente con una imagen de menor resolución. Puedes configurar esto con --context-fallbacks y --min-image-dimension. Si se agotan todos los fallbacks, la página se marca como fallida en lugar de escribir Markdown truncado.

Prompts personalizados

Puedes usar un prompt de conversión específico de dominio sin modificar doc7:

doc7 read ./reports --prompt-file ./prompt.md

Docker

La imagen Docker incluye LibreOffice, MuPDF, Chromium y fuentes CJK. Ejecuta el servicio HTTP como usuario no root y persiste la configuración y los trabajos en volúmenes nombrados:

export DOC7_MODEL=qwen3.5-0.8b
export DOC7_SERVER_TOKEN=replace-me
docker compose pull
docker compose up --no-build

La imagen publicada es ghcr.io/magicrew/doc7:latest y soporta tanto linux/amd64 como linux/arm64.

Consideraciones de seguridad

doc7 ejecuta renderizadores locales como LibreOffice y Chrome con los permisos del usuario actual. Trata los archivos de Office no confiables, HTML, SVG, EML, MSG, IPYNB y archivos como entrada activa—usa una cuenta aislada o contenedor para cargas de trabajo no confiables. El HTML de correo y cuadernos se sanitiza, los recursos remotos se eliminan y las imágenes BMP/TIFF incrustadas se normalizan antes del renderizado. Las claves API se envían como credenciales de portador al endpoint configurado, así que verifica el endpoint antes de procesar archivos sensibles.

Conclusión

doc7 es una perspectiva refrescante sobre la conversión de documentos. Al aprovechar la comprensión visual, maneja documentos complejos que los analizadores tradicionales luchan por procesar, y lo hace con un pipeline simple y unificado. Ya sea que estés construyendo un sistema RAG, una base de conocimiento de agentes, o solo necesites hacer tus documentos buscables, doc7 merece una mirada seria. El benchmark abierto y los resultados reproducibles te dan confianza en sus capacidades, y la licencia MIT significa que puedes integrarlo libremente.

Pruébalo con tus propios documentos y observa la diferencia que hace la comprensión visual.

Fuente

magicrew/doc7: Convierte documentos en Markdown listo para IA con comprensión visual