opendatalab/MinerU 딥다이브
— PDF·오피스 문서를 LLM이 먹을 수 있는 마크다운으로 변환하는 문서 파싱 엔진

1프로젝트 한줄 요약

MinerU가 무엇을 해결하는가.

2왜 주목받는가

트렌딩 이유 · 기존 PDF 파서 대비 차이점.

PDF 파싱은 오래된 문제다. 그런데 왜 지금 MinerU가 ★26k를 넘겼을까? 세 가지 흐름이 겹쳤다.

① RAG·에이전트 붐 — 기업들이 사내 PDF 문서를 LLM에 먹이려다 "파싱이 병목"임을 깨달았다. 기존 pymupdf, pdfminer 같은 텍스트 추출 도구는 이미지 기반 PDF나 수식이 있으면 손을 못 댄다. ② 정확도 격차 — OmniDocBench 기준 pipeline 백엔드 86.47점, hybrid/vlm 백엔드 95점 이상. 유사 상용 도구와 비교해도 상위권이다. ③ 라이선스 전환 — 2026년 4월 AGPLv3에서 Apache 2.0 기반 커스텀 라이선스로 전환해 기업 도입 장벽이 낮아졌다.

3기술 스택 전체 지도

어떤 기술들이 조합되어 있나.

파이프라인 레이어

VLM 백엔드 레이어

API·인프라 레이어

오피스 문서 파싱 레이어

4아키텍처 심화 분석

문서가 Markdown이 되기까지 — 파이프라인 내부 구조.

전체 시스템 구조도

핵심 설계 패턴

5디렉토리 구조 해부

어디에 무엇이 있는가.

중요한 파일 3개를 집중 파악하면 구조 전체가 보인다.

6학습 포인트 (기술별)

MinerU를 통해 무엇을 배울 수 있는가.

문서 AI / Document Understanding

MinerU는 현대 문서 AI 파이프라인의 교과서다. 레이아웃 분석(Document Layout Analysis)이 핵심인데, 이는 컴퓨터 비전의 객체 탐지를 문서 도메인에 적용한 것이다. PP-DocLayoutV2 소스(PaddleOCR 생태계)를 읽으면 YOLO 계열 모델이 어떻게 문서 블록 좌표를 예측하는지, 그 예측을 어떻게 읽기 순서로 변환하는지 배울 수 있다.

OCR 엔지니어링

MinerU는 PaddleOCR을 PyTorch로 포팅한 pytorch_paddle.py를 쓴다. 이것이 흥미로운 이유: 원본 PaddleOCR은 PaddlePaddle 프레임워크 의존성이 있어 배포가 까다로운데, PyTorch 포트를 직접 만들어 의존성을 제거했다. 프레임워크 이식(porting)의 실제 사례로 공부할 수 있다. PP-OCRv6는 3.4에서 정확도가 11% 개선됐고 처리 속도가 2배 빨라졌다.

수식 인식 (Mathematical Formula Recognition)

수식 인식은 이미지 → LaTeX 변환 문제다. MinerU는 두 가지 모델을 지원한다: UnimerNet(이미지 encoder + LaTeX decoder, Transformer 기반)과 PP-FormulaNet-Plus-M(PaddleOCR 계열). 환경변수 MINERU_FORMULA_CH_SUPPORT로 선택한다. 중국어 수식이 많으면 PP-FormulaNet이 더 낫다.

표 구조 인식 (Table Structure Recognition)

표 인식은 두 단계다: ① 표인지 그림인지 분류(표 타입 분류 모델), ② 셀 구조 파악(SLANet-Plus 또는 UNet). MinerU는 ONNX Runtime으로 이 모델들을 실행해 PyTorch 없이도 가볍게 돌릴 수 있다. ONNX를 통한 교차 프레임워크 모델 서빙의 실전 예시다.

FastAPI 비동기 서버 설계

mineru-api는 동기 엔드포인트(POST /file_parse)와 비동기 작업 엔드포인트(POST /tasks + 폴링)를 함께 제공한다. 대용량 문서 파싱처럼 오래 걸리는 작업을 비동기로 처리하고 클라이언트는 상태를 폴링하는 패턴을 직접 코드로 볼 수 있다.

실습 아이디어

• 직접 학술 논문 PDF를 MinerU로 파싱 → 수식 LaTeX가 제대로 나오는지 확인
• pipeline과 hybrid 백엔드 결과를 같은 문서로 비교해 정확도 차이 체감
• LangChain UnstructuredMarkdownLoader로 MinerU 결과를 RAG 파이프라인에 연결
• Gradio WebUI 소스(gradio_app.py)를 읽으며 Gradio 컴포넌트 학습
• ONNX로 내보낸 표 인식 모델을 직접 로드해 추론 실험

7시스템 요구사항 · 설치

어떤 환경에서 어떻게 시작하나.

하드웨어 요구사항 (백엔드별)

설치 방법

방법 1 — pip/uv (권장)

# pip 최신화 후 uv로 설치 (uv가 훨씬 빠름)
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

# 모델 다운로드 (최초 1회, ~10~20 GB)
mineru-models-download -s huggingface -m all
# 중국 환경이면: mineru-models-download -s modelscope -m all

방법 2 — 소스 설치 (개발/기여용)

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

방법 3 — Docker (Linux/WSL2)

# GPU 버전 (NVIDIA, Compute Capability 7.0 이상)
# docker/global/Dockerfile 기반 이미지 사용
# compose.yaml으로 실행:
cd docker/global
docker compose up -d

기본 사용법

# GPU 있을 때 (기본 hybrid-medium 백엔드)
mineru -p input.pdf -o output/

# CPU만 있을 때
mineru -p input.pdf -o output/ -b pipeline

# 특정 백엔드 + 언어 지정
mineru -p scan_doc.pdf -o output/ -b pipeline --lang ja

# 배치 처리 (디렉토리)
mineru -p ./docs/ -o output/

# API 서버 시작
mineru-api --host 0.0.0.0 --port 8888

8직접 해볼 수 있는 실습 과제

난이도별 3~5단계 — 손을 움직여야 몸이 기억한다.

pip install uv
uv pip install -U "mineru[all]"
mineru-models-download -s huggingface -m pipeline
# arXiv 논문 다운로드 (예: Attention Is All You Need)
curl -L https://arxiv.org/pdf/1706.03762 -o transformer.pdf
mineru -p transformer.pdf -o ./output/ -b pipeline
# output/transformer/ 폴더에 transformer.md, content_list.json 생성됨
cat output/transformer/transformer.md | head -50

pip install langchain langchain-community langchain-openai faiss-cpu
python3 <<'EOF'
from langchain.document_loaders import UnstructuredMarkdownLoader
from langchain.text_splitter import MarkdownHeaderTextSplitter
from langchain.vectorstores import FAISS
from langchain.embeddings import OpenAIEmbeddings
from langchain.chains import RetrievalQA
from langchain.chat_models import ChatOpenAI

# MinerU 출력 Markdown 로드
loader = UnstructuredMarkdownLoader("output/transformer/transformer.md")
docs = loader.load()

# 헤더 기준으로 청킹
splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=[("#","H1"),("##","H2"),("###","H3")]
)
splits = splitter.split_text(docs[0].page_content)

# 벡터 DB 생성 및 RAG 체인
vectorstore = FAISS.from_documents(splits, OpenAIEmbeddings())
qa = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(model="gpt-4o-mini"),
    retriever=vectorstore.as_retriever()
)
print(qa.run("What is the main contribution of this paper?"))
EOF

# 터미널 1: API 서버 시작
mineru-api --host 0.0.0.0 --port 8888

# 터미널 2: 비동기 작업 제출 및 폴링
python3 <<'EOF'
import httpx, time

BASE = "http://localhost:8888"

# 파일 업로드 + 작업 제출
with open("transformer.pdf", "rb") as f:
    r = httpx.post(f"{BASE}/tasks", files={"file": f})
task_id = r.json()["task_id"]
print(f"Task ID: {task_id}")

# 완료 대기 (폴링)
while True:
    status = httpx.get(f"{BASE}/tasks/{task_id}").json()
    print(f"Status: {status['status']}")
    if status['status'] in ('done', 'failed'):
        break
    time.sleep(2)

# 결과 다운로드
result = httpx.get(f"{BASE}/tasks/{task_id}/result")
print(result.json()['markdown'][:500])
EOF

# GPU 0에서 API 서버 1
CUDA_VISIBLE_DEVICES=0 mineru-api --port 8881 &

# GPU 1에서 API 서버 2
CUDA_VISIBLE_DEVICES=1 mineru-api --port 8882 &

# 라우터 (두 서버를 묶어 하나의 엔드포인트 제공)
mineru-router --backends http://localhost:8881,http://localhost:8882 --port 8888

9관련 기술 심화 학습 로드맵

MinerU를 이해하고 활용하기 위한 주차별 공부 순서.

10핵심 키워드 사전

처음 마주치면 당황스러운 용어 정리.

11참고 링크

더 깊이 파고들고 싶다면.