Herramientas de IA

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

Resumen práctico de opendatalab/MinerU: capacidades, instalación, uso por CLI, opciones de despliegue y límites para convertir PDF, documentos de Office e imágenes en Markdown/JSON para flujos RAG y Agent.

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:

  1. Elegir entre 10 y 20 documentos representativos, cubriendo escaneos, tablas complejas, artículos multicolumna, PPT y Excel.
  2. Analizarlos primero con el backend pipeline, registrando tiempo, memoria, tamaño de salida y muestras fallidas.
  3. Revisar muestras de Markdown, JSON y visualizaciones, con foco en orden de lectura, tablas, fórmulas y leyendas de imágenes.
  4. Para muestras con calidad insuficiente, probar VLM o el backend hybrid.
  5. 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.

Diagnóstico de CUDA cuando MinerU no utiliza la GPU

Si al revisar PyTorch en tu entorno de MinerU ves algo como esto:

1
2
3
4
5

PyTorch: 2.8.0+cpu
PyTorch CUDA: None
CUDA available: False
GPU count: 0
GPU: 未检测到

prácticamente queda confirmado que ese entorno tiene instalada la versión CPU de PyTorch, así que MinerU no usará la GPU NVIDIA. Aunque el equipo tenga una RTX 4060, mientras el torch de ese entorno Python sea la versión CPU, MinerU solo podrá usar CPU.

La solución es directa: en el mismo .venv, cambia torch y torchvision por la versión CUDA. Para PyTorch 2.8.0, existen ruedas oficiales para CUDA 12.8, así que puedes instalar directamente la compilación cu128.

Primero confirma que el driver NVIDIA funciona

Ejecuta en PowerShell:

1

nvidia-smi

Normalmente deberías ver algo parecido a:

1
2
3

NVIDIA GeForce RTX 4060
Driver Version: ...
CUDA Version: 12.x

El CUDA Version que aparece aquí es la versión máxima de CUDA admitida por el driver actual. Si nvidia-smi detecta bien la GPU, normalmente no hace falta instalar por separado el CUDA Toolkit completo.

Si nvidia-smi ni siquiera reconoce la GPU, no empieces por PyTorch. Primero actualiza o reinstala el driver NVIDIA.

Entra en el entorno virtual que usa MinerU

Primero entra en el directorio donde está MinerU. Aquí usamos C:\Work\test como ejemplo:

1

cd C:\Work\test

Si el proyecto usa .venv, actívalo:

1

.\.venv\Scripts\Activate.ps1

Confirma la ruta actual de Python:

1

python -c "import sys; print(sys.executable)"

Debería apuntar a algo parecido a:

1

C:\Work\test\.venv\Scripts\python.exe

Este paso es importante. Debes reemplazar PyTorch en el entorno Python que MinerU usa realmente, no en el Python del sistema, otro entorno Conda o un intérprete elegido al azar por VS Code.

Desinstala la versión CPU de PyTorch

Después de confirmar que .venv está activo, desinstala la versión CPU actual:

1

uv pip uninstall torch torchvision

Si no usas uv, también puedes hacerlo con pip, pero dentro de un mismo entorno conviene no mezclar herramientas sin necesidad. Aquí seguimos con uv pip.

Instala PyTorch con CUDA 12.8

Instala la versión CUDA 12.8 correspondiente a PyTorch 2.8.0:

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

La combinación oficial es:

1
2
3

torch 2.8.0
torchvision 0.23.0
CUDA 12.8

La descarga de PyTorch con CUDA puede ser grande, normalmente varios GB. Si la red es lenta, toca esperar.

Si uv indica que ya está instalado, pero la comprobación sigue mostrando la versión CPU, fuerza la reinstalación:

1

uv pip install --reinstall torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

Verifica que CUDA esté disponible

Ejecuta:

1

python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA build:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available()); print('GPU count:', torch.cuda.device_count()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else '未检测到')"

El resultado correcto debería parecerse a:

1
2
3
4
5

PyTorch: 2.8.0+cu128
CUDA build: 12.8
CUDA available: True
GPU count: 1
GPU: NVIDIA GeForce RTX 4060

La línea más importante es:

1

CUDA available: True

Si sigue siendo False, PyTorch todavía no puede usar CUDA. Las causas típicas son: instalación en el entorno equivocado, seguir teniendo la versión CPU de torch, problemas con el driver NVIDIA o usar un intérprete Python distinto del .venv de MinerU.

Haz una operación real en GPU

Ver CUDA available: True ayuda, pero también puedes ejecutar una operación CUDA real:

1

python -c "import torch; x=torch.randn(4096,4096,device='cuda'); y=x@x; torch.cuda.synchronize(); print('设备:', y.device); print('显存:', round(torch.cuda.memory_allocated()/1024**2,1), 'MB')"

Un resultado normal sería:

1
2

设备: cuda:0
显存: 128.0 MB

Esto indica que PyTorch no solo detecta la GPU, sino que realmente puede ejecutar cómputo CUDA en la RTX 4060.

Observa la GPU al ejecutar MinerU

Abre una segunda ventana de PowerShell y monitoriza la GPU:

1

nvidia-smi -l 1

Luego ejecuta MinerU en la primera ventana:

1

mineru -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

Si el entorno virtual no está activado, llama directamente al ejecutable dentro de .venv:

1

.\.venv\Scripts\mineru.exe -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

Observa nvidia-smi. Si aparecen estas señales, probablemente MinerU ya está usando la RTX 4060:

  1. Aparece python.exe.
  2. Aumenta el uso de VRAM.
  3. GPU-Util sube durante la inferencia.
  4. La VRAM se libera al terminar MinerU.

Cómo entender RTX 4060 y los modos de MinerU

La RTX 4060 pertenece a la serie 40 de NVIDIA, es decir, a la arquitectura Ada Lovelace, dentro del rango de hardware compatible con aceleración GPU en MinerU. Después de instalar correctamente PyTorch con CUDA, el comando normal mineru puede usar la GPU.

Si especificas explícitamente:

1

mineru -p "input.pdf" -o "output" -b pipeline

ese modo prioriza estabilidad y compatibilidad, y también sirve para retorno a CPU o escenarios con poca VRAM. Si quieres usar modos como hybrid-engine o vlm-engine, que dependen más de VLM, es todavía más importante confirmar que PyTorch CUDA se instaló correctamente.

Errores comunes

Primero, instalar en el entorno equivocado. Lo más común es instalar PyTorch CUDA en un entorno Python, pero MinerU se ejecuta realmente en otro .venv. Por eso siempre revisa:

1

python -c "import sys; print(sys.executable)"

Segundo, mirar solo el driver y no PyTorch. Que nvidia-smi funcione solo demuestra que el driver reconoce la GPU. No demuestra que PyTorch dentro de Python admita CUDA. La comprobación final sigue siendo:

1

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

Tercero, confundir CUDA Toolkit con PyTorch CUDA. En la mayoría de usos normales no hace falta instalar el CUDA Toolkit completo. Si el driver NVIDIA funciona, basta con instalar la rueda oficial de PyTorch con CUDA.

Cuarto, tener la VRAM ocupada por otros programas. La RTX 4060 8GB puede ejecutar estas cargas, pero no sobra demasiado margen. Antes de ejecutar MinerU, cierra juegos, aceleración por hardware del navegador, otros programas de inferencia IA y software que ocupe VRAM.

Resumen en una frase

Si ves:

1
2

PyTorch: 2.8.0+cpu
CUDA available: False

MinerU no puede usar la RTX 4060 en ese entorno. La forma correcta es desinstalar las versiones CPU de torch y torchvision dentro del mismo .venv, y luego instalar:

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

Cuando la verificación cambie a:

1
2
3

PyTorch: 2.8.0+cu128
CUDA available: True
GPU: NVIDIA GeForce RTX 4060

vuelve a ejecutar MinerU y usa nvidia-smi -l 1 para observar python.exe, la VRAM y la utilización de GPU. Así confirmas si la aceleración GPU está realmente activa.

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.

Referencias