Conversion PDF → Markdown (MinerU)

PDF → Markdown (MinerU)

Convertit des PDFs en Markdown propre et structuré en utilisant MinerU (opendatalab/MinerU), le moteur open-source de plus haute fidélité pour les articles académiques. Exécute le pipeline backend sur le GPU (CUDA). La sortie conserve la hiérarchie des titres, les équations LaTeX en ligne ($...$), les figures et les tableaux (sous forme de HTML).

Quand l'utiliser

• L'utilisateur demande de « convertir / extraire / transformer ce PDF en markdown (ou texte). »
• Idéal pour : articles académiques — mises en page multi-colonnes, équations LaTeX, tableaux, références.
• Gère également les images, .docx, .pptx, .xlsx (transmettez le fichier directement).

Comment exécuter

MinerU réside dans un environnement isolé dédié et est piloté via le wrapper convert.py fourni, qui appelle l'API Python de MinerU en processus.

N'utilisez pas le CLI mineru ici — dans la version 3.4.0, il lance un serveur API local qui retourne 502 Bad Gateway sur Windows. Le wrapper contourne ce problème.

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

• Arg 1 — fichier d'entrée (pdf/image/docx/pptx/xlsx).
• Arg 2 — dossier de sortie.
• --lang — langue pour l'OCR : en pour l'anglais, ch pour le chinois/mélangé (par défaut ch, qui gère aussi l'anglais). N'affecte que les pages scannées (OCR).
• Le script affiche DONE -> <chemin du .md> en cas de succès.

Structure de sortie

<output_dir>/<name>/auto/<name>.md       # le markdown
<output_dir>/<name>/auto/images/          # figures extraites (référencées depuis le md)
<output_dir>/<name>/auto/<name>_*.json    # métadonnées de mise en page/contenu (ignorables)

Après la conversion

1. Lisez le chemin DONE -> ...md affiché et signalez-le à l'utilisateur.
2. Montrez éventuellement un court aperçu (titre + premiers titres).
3. Indiquez où ont été écrites les images extraites.
4. La qualité est généralement élevée : titres en #, équations en ligne en $...$, tableaux sous forme de HTML <table> (avec LaTeX dans les cellules). Si un PDF scanné sort déformé, réexécutez-le avec --method ocr.

Pré-vérification / configuration (uniquement si quelque chose manque)

• Interpréteur avec MinerU (env MINERU_PYTHON, par défaut python).
• Vérifiez CUDA : $MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())" → True.
• Les modèles sont pré-téléchargés dans ~/.cache/huggingface/hub/ (une seule fois).

Si l'environnement est manquant, recréez-le (installez uv d'abord si nécessaire) :

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

Définissez ensuite MINERU_PYTHON sur <votre-env>/Scripts/python.exe (Windows) ou <votre-env>/bin/python (macOS/Linux). Sous macOS/Linux, le binaire de téléchargement de modèles est mineru-models-download (sans suffixe .exe).

Dépannage

• cuda.is_available() est False → réinstallez torch depuis l'index cu124 (voir configuration). Le pipeline s'exécute quand même sur le CPU si nécessaire, mais plus lentement.
• Le téléchargement du modèle échoue / est lent → relancez mineru-models-download avec -s modelscope.
• PDF scanné déformé → ajoutez --method ocr à l'appel de convert.py.
• Backends vlm-engine / hybrid-engine → nécessitent vLLM/SGLang (Linux) ; ils renvoient 502 sur Windows. Utilisez le backend pipeline par défaut du wrapper.

Alternative légère (documents simples / Office)

Pour les fichiers non-académiques où la haute fidélité de mise en page n'est pas cruciale, MarkItDown de Microsoft est plus rapide et plus simple — mais il détruit les PDFs académiques à deux colonnes et les tableaux, donc préférez MinerU pour les articles :

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