PDF → 마크다운 (MinerU)
MinerU (opendatalab/MinerU)를 사용하여 PDF를 깔끔하고 구조가 보존된 마크다운으로 변환합니다. 학술 논문에 가장 적합한 고충실도 오픈소스 엔진입니다. 파이프라인 백엔드는 GPU(CUDA)에서 실행됩니다. 출력에는 제목 계층, 인라인 LaTeX 수식($...$), 그림, 표(HTML)가 유지됩니다.
사용 시기
- 사용자가 "이 PDF를 마크다운(또는 텍스트)으로 변환/추출/바꿔줘"라고 요청할 때.
- 학술 논문에 가장 적합 — 다단 레이아웃, LaTeX 수식, 표, 참고문헌.
- 이미지,
.docx,.pptx,.xlsx도 처리 가능 (파일을 직접 전달).
실행 방법
MinerU는 전용 격리 환경에 있으며, 번들로 제공되는 convert.py 래퍼를 통해 구동됩니다. 이 래퍼는 MinerU의 Python API를 프로세스 내에서 직접 호출합니다.
여기서
mineruCLI를 사용하지 마세요 — 3.4.0 버전에서는 로컬 API 서버를 실행하여 Windows에서502 Bad Gateway오류를 반환합니다. 래퍼가 이를 우회합니다.
"$MINERU_PYTHON" \
"<SKILLS_DIR>/pdf-to-markdown/convert.py" \
"<input.pdf>" "<output_dir>" --lang en
- 인수 1 — 입력 파일 (pdf/image/docx/pptx/xlsx).
- 인수 2 — 출력 디렉터리.
--lang— OCR 언어 힌트:en(영어),ch(중국어/혼합, 기본값ch이며 영어도 처리 가능). 스캔된(OCR) 페이지에만 영향을 줍니다.- 스크립트는 성공 시
DONE -> <마크다운 파일 경로>를 출력합니다.
출력 구조
<output_dir>/<name>/auto/<name>.md # 마크다운 파일
<output_dir>/<name>/auto/images/ # 추출된 그림 (마크다운에서 참조)
<output_dir>/<name>/auto/<name>_*.json # 레이아웃/콘텐츠 메타데이터 (무시 가능)
변환 후
- 출력된
DONE -> ...md경로를 읽고 사용자에게 알립니다. - 필요시 짧은 미리보기(제목 + 첫 번째 제목들)를 보여줍니다.
- 추출된 이미지가 저장된 위치를 안내합니다.
- 품질은 일반적으로 높습니다: 제목은
#, 인라인 수식은$...$, 표는<table>HTML(셀 내 LaTeX 포함). 스캔된 PDF가 깨져 나오면--method ocr로 재실행하세요.
사전 확인/설정 (누락된 항목이 있을 때만)
- MinerU가 설치된 인터프리터 (환경 변수
MINERU_PYTHON, 기본값python). - CUDA 확인:
$MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())"→True. - 모델은
~/.cache/huggingface/hub/에 사전 다운로드되어 있습니다 (최초 1회).
환경이 없으면 다시 생성하세요 (필요시 uv 먼저 설치):
uv venv --python 3.12 "<your-env>"
uv pip install --python "<your-env>/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "<your-env>/Scripts/python.exe" -U "mineru[core]"
"<your-env>/Scripts/mineru-models-download.exe" -s huggingface -m pipeline
그런 다음 MINERU_PYTHON을 <your-env>/Scripts/python.exe(Windows) 또는 <your-env>/bin/python(macOS/Linux)으로 설정하세요. macOS/Linux에서 모델 다운로드 바이너리는 mineru-models-download입니다 (.exe 접미사 없음).
문제 해결
cuda.is_available()이 False인 경우 →cu124인덱스에서 torch 재설치 (설정 참조). 필요시 파이프라인이 CPU에서도 실행되지만 느립니다.- 모델 다운로드 실패/느린 경우 →
mineru-models-download를-s modelscope와 함께 재실행. - 스캔된 PDF가 깨지는 경우 →
convert.py호출에--method ocr추가. vlm-engine/hybrid-engine백엔드 → vLLM/SGLang(Linux)이 필요하며 Windows에서는 502 오류 발생. 래퍼에서 사용하는 기본pipeline백엔드를 계속 사용하세요.
경량 대체 (단순/Office 문서)
레이아웃 충실도가 중요하지 않은 비논문 파일의 경우 Microsoft의 MarkItDown이 더 빠르고 간단하지만, 학술용 2단 PDF와 표를 망가뜨리므로 논문에는 MinerU를 선호하세요:
"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "<input>" > out.md