PDF → Markdown (MinerU)

O que PDF → Markdown (MinerU) faz?

Converte PDFs em Markdown limpo e preservador de estrutura usando MinerU (opendatalab/MinerU), o motor open-source de maior fidelidade para artigos acadêmicos. Executa o backend do pipeline na GPU (CUDA). A saída mantém a hierarquia de cabeçalhos, matemática LaTeX inline ($...$), figuras e tabelas (como HTML).

Quando usar

• O usuário pede para "converter / extrair / transformar este PDF em markdown (ou texto)."
• Melhor para: artigos acadêmicos — layouts com múltiplas colunas, matemática LaTeX, tabelas, referências.
• Também lida com imagens, .docx, .pptx, .xlsx (passe o arquivo diretamente).

Como executar

O MinerU vive em um ambiente isolado dedicado e é acionado através do wrapper convert.py incluso, que chama a API Python do MinerU em processo.

Não use a CLI mineru aqui — na versão 3.4.0 ela inicia um servidor API local que retorna 502 Bad Gateway no Windows. O wrapper contorna isso.

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

• Arg 1 — arquivo de entrada (pdf/imagem/docx/pptx/xlsx).
• Arg 2 — diretório de saída.
• --lang — dica de idioma OCR: en para inglês, ch para chinês/misto (padrão ch, que também lida com inglês). Afeta apenas páginas escaneadas (OCR).
• O script imprime DONE -> <caminho para .md> em caso de sucesso.

Estrutura de saída

<output_dir>/<nome>/auto/<nome>.md       # o markdown
<output_dir>/<nome>/auto/images/          # figuras extraídas (referenciadas do md)
<output_dir>/<nome>/auto/<nome>_*.json    # metadados de layout/conteúdo (podem ser ignorados)

Após a conversão

1. Leia o caminho DONE -> ...md impresso e informe ao usuário.
2. Opcionalmente, mostre uma prévia curta (título + primeiros cabeçalhos).
3. Anote onde as imagens extraídas foram salvas.
4. A qualidade geralmente é alta: cabeçalhos como #, matemática inline como $...$, tabelas como HTML <table> (com LaTeX dentro das células). Se um PDF escaneado sair ilegível, execute novamente com --method ocr.

Pré-requisitos / configuração (apenas se algo estiver faltando)

• Interpretador com MinerU (env MINERU_PYTHON, padrão python).
• Verifique CUDA: $MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())" → True.
• Modelos são pré-baixados para ~/.cache/huggingface/hub/ (uma vez).

Se o ambiente estiver faltando, recrie-o (instale uv primeiro se necessário):

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

Em seguida, defina MINERU_PYTHON como <seu-env>/Scripts/python.exe (Windows) ou <seu-env>/bin/python (macOS/Linux). No macOS/Linux, o binário de download de modelos é mineru-models-download (sem sufixo .exe).

Solução de problemas

• cuda.is_available() é False → reinstale o torch a partir do índice cu124 (veja configuração). O pipeline ainda roda na CPU se necessário, apenas mais devagar.
• Falha no download de modelos / lento → execute mineru-models-download novamente com -s modelscope.
• PDF escaneado ilegível → adicione --method ocr à chamada do convert.py.
• Backends vlm-engine / hybrid-engine → estes precisam de vLLM/SGLang (Linux); eles geram 502 no Windows. Mantenha o backend pipeline padrão usado pelo wrapper.

Fallback leve (documentos simples / Office)

Para arquivos que não são artigos, onde a fidelidade de layout não importa, o MarkItDown da Microsoft é mais rápido e simples — mas ele danifica PDFs acadêmicos de duas colunas e tabelas, portanto prefira MinerU para artigos:

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