Peytontalismanic424/paper-share-skills

PDF → Markdown (MinerU)

Convierte PDFs a Markdown limpio y con estructura preservada usando MinerU (opendatalab/MinerU), el motor de código abierto de mayor fidelidad para artículos académicos. Ejecuta el backend de pipeline en la GPU (CUDA). La salida mantiene la jerarquía de encabezados, ecuaciones LaTeX en línea ($...$), figuras y tablas (como HTML).

Cuándo usarlo

• El usuario pide "convertir / extraer / transformar este PDF a markdown (o texto)".
• Mejor ajuste: artículos académicos — diseños multicolumna, ecuaciones LaTeX, tablas, referencias.
• También maneja imágenes, .docx, .pptx, .xlsx (pasa el archivo directamente).

Cómo ejecutar

MinerU vive en un entorno aislado dedicado y se controla a través del envoltorio convert.py incluido, que llama a la API de Python de MinerU en el mismo proceso.

No uses la CLI de mineru aquí — en la versión 3.4.0 inicia un servidor API local que devuelve 502 Bad Gateway en Windows. El envoltorio lo evita.

"$MINERU_PYTHON" \
  "<SKILLS_DIR>/pdf-to-markdown/convert.py" \
  "<input.pdf>" "<output_dir>" --lang en

• Arg 1 — archivo de entrada (pdf/imagen/docx/pptx/xlsx).
• Arg 2 — directorio de salida.
• --lang — indicación de idioma OCR: en para inglés, ch para chino/mixto (por defecto ch, que también maneja inglés). Solo afecta páginas escaneadas (OCR).
• El script imprime DONE -> <ruta al .md> en caso de éxito.

Estructura de salida

<output_dir>/<nombre>/auto/<nombre>.md       # el markdown
<output_dir>/<nombre>/auto/images/          # figuras extraídas (referenciadas desde el md)
<output_dir>/<nombre>/auto/<nombre>_*.json  # metadatos de diseño/contenido (se pueden ignorar)

Después de convertir

1. Lee la ruta impresa DONE -> ...md e infórmala al usuario.
2. Opcionalmente, muestra una vista previa corta (título + primeros encabezados).
3. Indica dónde se escribieron las imágenes extraídas.
4. La calidad suele ser alta: encabezados como #, ecuaciones en línea como $...$, tablas como <table> HTML (con LaTeX dentro de las celdas). Si un PDF escaneado sale distorsionado, vuelve a ejecutarlo con --method ocr.

Verificación previa / configuración (solo si falta algo)

• Intérprete con MinerU (entorno MINERU_PYTHON, por defecto python).
• Verifica CUDA: $MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())" → True.
• Los modelos están pre-descargados en ~/.cache/huggingface/hub/ (una vez).

Si falta el entorno, recréalo (instala uv primero si es necesario):

uv venv --python 3.12 "<tu-entorno>"
uv pip install --python "<tu-entorno>/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "<tu-entorno>/Scripts/python.exe" -U "mineru[core]"
"<tu-entorno>/Scripts/mineru-models-download.exe" -s huggingface -m pipeline

Luego establece MINERU_PYTHON a <tu-entorno>/Scripts/python.exe (Windows) o <tu-entorno>/bin/python (macOS/Linux). En macOS/Linux el binario de descarga de modelos es mineru-models-download (sin sufijo .exe).

Solución de problemas

• cuda.is_available() es False → reinstala torch desde el índice cu124 (ver configuración). El pipeline aún se ejecuta en CPU si es necesario, solo que más lento.
• La descarga de modelos falla / es lenta → vuelve a ejecutar mineru-models-download con -s modelscope.
• PDF escaneado distorsionado → añade --method ocr a la llamada de convert.py.
• Backends vlm-engine / hybrid-engine → necesitan vLLM/SGLang (Linux); dan 502 en Windows. Quédate con el backend pipeline predeterminado usado por el envoltorio.

Alternativa ligera (documentos simples / de Office)

Para archivos que no sean artículos donde la fidelidad del diseño no importe, MarkItDown de Microsoft es más rápido y simple — pero estropea PDFs académicos de dos columnas y tablas, así que prefiere MinerU para artículos:

"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "<input>" > out.md