Guía de MinerU: convertir PDF, Office e imágenes en Markdown/JSON listo para RAG

opendatalab/MinerU es una herramienta de análisis de documentos pensada para preparar datos para aplicaciones con modelos grandes. Puede convertir entradas como PDF, imágenes, DOCX, PPTX y XLSX en Markdown, JSON y resultados estructurados intermedios, lo que facilita usarlos después en RAG, extracción de información, construcción de bases de conocimiento o flujos de trabajo con Agent.

El problema que aborda es muy concreto: los documentos reales suelen incluir diseños en varias columnas, tablas, fórmulas, encabezados y pies de página, páginas escaneadas, escritura manual y leyendas de imágenes. Si se envía todo eso directamente a un modelo grande, es fácil obtener orden de lectura incorrecto, pérdida de estructura en tablas, fórmulas ilegibles y demasiado ruido de OCR. MinerU primero analiza diseño, texto, tablas, fórmulas y OCR, y luego produce resultados más cercanos a datos legibles por máquina y al orden de lectura humano.

Qué problemas resuelve mejor

MinerU encaja bien en escenarios como estos:

Convertir artículos, informes, contratos y manuales en Markdown;
Preparar entradas más limpias para dividir documentos en una base de conocimiento RAG;
Extraer texto, tablas y fórmulas desde PDF escaneados o imágenes;
Unificar DOCX, PPTX y XLSX como datos estructurados consumibles por flujos posteriores;
Procesar documentos por lotes en un entorno local o privado;
Preparar datos para LangChain, LlamaIndex, Dify, RAGFlow, FastGPT y otros frameworks.

Si la tarea solo consiste en leer un PDF de texto con formato simple, una herramienta convencional de extracción de PDF quizá sea suficiente. MinerU aporta más valor cuando importan los diseños complejos, las tablas y fórmulas, las entradas en varios formatos y la producción por lotes de datos documentales.

Capacidades principales

Según el README del proyecto, MinerU admite entradas PDF, imágenes, DOCX, PPTX y XLSX. Puede generar Markdown, JSON ordenado por secuencia de lectura y resultados visuales para revisar la calidad del análisis.

Entre sus capacidades clave están:

Eliminar automáticamente encabezados, pies de página, notas al pie, números de página y otros elementos de ruido;
Emitir texto en orden de lectura humano para diseños de una columna, varias columnas y maquetaciones complejas;
Conservar la estructura del documento, como títulos, párrafos y listas;
Extraer imágenes, leyendas, tablas, títulos de tablas y notas al pie;
Reconocer fórmulas y convertirlas a LaTeX;
Reconocer tablas y convertirlas a HTML;
Detectar automáticamente PDF escaneados y PDF con texto dañado, y activar OCR;
Soportar OCR en 109 idiomas;
Ofrecer CLI, FastAPI, Gradio WebUI y mineru-router.

La versión 3.1.0 de abril de 2026 introdujo análisis nativo para PPTX y XLSX, y actualizó el modelo VLM principal a MinerU2.5-Pro-2604-1.2B. La página de releases de GitHub muestra que 3.2.3, publicada el 4 de junio de 2026, añadió detección y salida de superíndices y subíndices, además de un mecanismo post-OCR fallback para tratar texto de áreas de uso privado.

Instalación

Para una prueba local, la ruta oficial recomienda instalar primero uv y luego el paquete completo:

1
2
3


pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

También se puede instalar desde el código fuente:

1
2
3


git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

mineru[all] incluye las funciones principales y se describe como compatible con Windows, Linux y macOS. Hay que tener en cuenta que el análisis de documentos es sensible al hardware y a las dependencias, sobre todo GPU, frameworks de inferencia, versión de Python y entorno del sistema. Antes de desplegar en producción, conviene ejecutar una muestra pequeña y decidir después si pasar al procesamiento por lotes.

Primer análisis de documentos

El comando básico especifica una ruta de entrada y una ruta de salida:

1

mineru -p <input_path> -o <output_path>

Si el dispositivo no cumple los requisitos de aceleración GPU, se puede especificar el backend pipeline para ejecutar una ruta solo con CPU:

1

mineru -p <input_path> -o <output_path> -b pipeline

<input_path> puede ser un único archivo o un directorio. En la práctica, conviene empezar con un directorio pequeño que contenga solo algunos documentos representativos:

1

mineru -p ./samples -o ./output -b pipeline

Así puedes observar calidad de salida, tiempo de ejecución, uso de memoria y estructura de archivos antes de ampliarlo a toda la biblioteca documental.

Cómo usar la salida

La salida de MinerU puede alimentar varios flujos posteriores.

El primero es RAG. Puedes usar Markdown como entrada para segmentación y vectorización, manteniendo títulos, párrafos, listas, tablas y fórmulas lo más cerca posible de la semántica original. Comparado con hacer OCR de todo en un gran bloque de texto, el Markdown estructurado es más fácil de dividir, citar y rastrear.

El segundo es la extracción de información. JSON y los resultados intermedios son adecuados para scripts posteriores, por ejemplo para extraer tablas, fórmulas, leyendas de imágenes o secciones específicas. En escenarios donde se organizan automáticamente informes, artículos o campos de contratos, esto es más estable que trabajar solo con texto plano.

El tercero es la revisión humana. MinerU proporciona resultados visuales de layout y span que ayudan a comprobar si falta contenido, si el orden es razonable y si las tablas se deformaron. Antes de procesar por lotes, lo mejor es revisar una muestra de esas visualizaciones.

Elección de backend

La documentación de MinerU menciona principalmente estas rutas de backend:

pipeline: buena compatibilidad, funciona en CPU o GPU, adecuado para primeras pruebas y procesamiento por lotes común;
vlm-engine: mayor precisión, pero también mayores requisitos de hardware; adecuado para documentos complejos y análisis de alta calidad;
hybrid-engine: combina extracción de texto nativa con análisis de alta precisión, útil cuando se quiere reducir alucinaciones y mejorar la calidad en diseños complejos;
*-http-client: conecta con servicios compatibles con OpenAI API, ya sean locales o remotos.

Si solo quieres validar resultados, empieza por pipeline. Cuando tengas claros los tipos de documento, los requisitos de calidad y el volumen de procesamiento, considera VLM o la ruta híbrida. Para documentos internos de empresa, la elección del backend también depende de si los datos pueden salir del entorno local.

Formas de despliegue

MinerU admite CLI, API local, Gradio WebUI, Docker y mineru-router. Cada entrada encaja con un tipo de equipo:

Prueba personal: CLI es lo más directo;
Usuarios no técnicos: Gradio WebUI es más amigable;
Integración con sistemas existentes: FastAPI o REST API encajan mejor;
Varios servicios, varias GPU y alta concurrencia: considerar mineru-router;
Reducir coste de configuración del entorno: revisar Docker en Linux o WSL2.

El despliegue con Docker actualmente encaja mejor en Linux y Windows con WSL2. En macOS, normalmente se empieza con la ruta de instalación pip / uv.

Diferencias frente a OCR común

Las herramientas OCR comunes se centran sobre todo en reconocer texto dentro de imágenes. Eso es importante, pero no basta para RAG. RAG también necesita orden de párrafos, jerarquía de títulos, estructura de tablas, expresión de fórmulas, contexto de imágenes y trazabilidad.

MinerU se parece más a una herramienta de preprocesamiento para comprensión documental. No es solo OCR: también trata análisis de layout, orden de lectura, tablas en HTML, fórmulas en LaTeX, entradas multiformato y salida estructurada. Es más adecuado para convertir documentos complejos en datos que los modelos posteriores puedan consumir de forma estable.

Esto también significa que más pesado no siempre es mejor. Para facturas simples, imágenes de una página o PDF de texto plano, un OCR ligero o una extracción de texto PDF puede ser más rápida. MinerU encaja mejor cuando la complejidad del documento ya afecta claramente los resultados posteriores.

Cómo elegir entre PaddleOCR, Marker y Unstructured

Estas herramientas se solapan, pero su punto de entrada es distinto.

PaddleOCR se orienta más a capacidades OCR básicas y componentes de reconocimiento de texto, útil si necesitas construir tu propio flujo OCR más granular. Marker se orienta más a convertir PDF en Markdown, útil para transformar documentos rápidamente en Markdown legible. Unstructured se centra más en extracción documental y pipelines de datos empresariales, útil para llevar múltiples tipos de documentos a búsqueda o ETL.

MinerU se caracteriza por preparar datos para LLM, RAG y Agent. Destaca en layouts complejos, tablas, fórmulas, entradas multiformato, doble motor VLM + OCR y despliegue privado. Si tus documentos son principalmente artículos, informes, materiales didácticos, PPT y hojas de cálculo, y luego entrarán en una aplicación con modelos grandes, vale la pena probarlo por separado.

Recomendaciones para lotes

Antes de procesar por lotes en serio, conviene hacer una validación pequeña:

Elegir entre 10 y 20 documentos representativos, cubriendo escaneos, tablas complejas, artículos multicolumna, PPT y Excel.
Analizarlos primero con el backend pipeline, registrando tiempo, memoria, tamaño de salida y muestras fallidas.
Revisar muestras de Markdown, JSON y visualizaciones, con foco en orden de lectura, tablas, fórmulas y leyendas de imágenes.
Para muestras con calidad insuficiente, probar VLM o el backend hybrid.
Tras confirmar la estructura de salida, conectarla con segmentación RAG, vectorización y trazabilidad de citas.

No conviene lanzar toda la biblioteca documental desde el principio. Los fallos de análisis suelen ser muy específicos: cierto tipo de escaneo, cierta tabla, una fuente, una dirección de idioma o contenido que cruza páginas. Primero encuentra los límites y luego escala; ahorra mucho tiempo.

Privacidad y cumplimiento

Si procesas documentos internos de empresa, datos de clientes, contratos, informes financieros o investigación no publicada, confirma primero el modo de despliegue y el flujo de datos.

Puntos que conviene revisar:

Si el contenido de los archivos se envía a un servicio de modelo externo;
Si se usa inferencia local, inferencia remota o un servicio compatible con OpenAI API;
Si los archivos intermedios contienen texto completo, imágenes, tablas o información sensible de negocio;
Si la salida Markdown / JSON entra en logs, almacenamiento de objetos o directorios compartidos;
Si las muestras fallidas del procesamiento por lotes se subirán a issues, comunidades o plataformas externas de depuración.

MinerU admite despliegue privado y sin conexión, pero eso no significa que toda configuración sea automáticamente offline. Antes del despliegue real, conviene dibujar todo el recorrido de datos: archivos de entrada, directorios temporales, inferencia del modelo, directorios de salida y sistema de logs.

Cuándo no usarlo

Puedes no introducir MinerU por ahora en estos casos:

El documento es muy simple y la extracción normal de texto PDF ya basta;
Solo necesitas leer unas pocas páginas una vez y no necesitas salida estructurada;
La máquina actual no tiene recursos suficientes y el coste de análisis supera el beneficio;
La calidad del documento es tan baja que el resultado OCR requerirá mucha corrección manual;
Los documentos privados no pueden entrar en la cadena de inferencia actual;
El equipo todavía no tiene una necesidad clara de RAG, extracción o base de conocimiento.

Una herramienta de análisis documental debe servir a un flujo posterior, no existir solo para analizar. Si no hay un consumidor claro, alinea primero muestras de salida con los requisitos posteriores y decide después si invertir en lotes.

Resumen

MinerU es adecuado para convertir documentos complejos en Markdown y JSON que las aplicaciones con modelos grandes pueden usar con más facilidad. Cubre PDF, imágenes, documentos de Office, tablas, fórmulas, OCR, reconocimiento multilingüe y despliegue local, por lo que encaja especialmente bien en preparación de datos para RAG, bases de conocimiento y flujos Agent.

Una ruta prudente es evaluar la calidad con una demo en línea o una muestra local pequeña, ejecutar el flujo con el backend pipeline y después decidir si cambiar a VLM, hybrid, API o despliegue multiservicio según precisión y throughput. Para documentos complejos puede reducir bastante el coste de preprocesamiento; para documentos simples, conviene no hacer el flujo más pesado de lo necesario.