PyMuPDF4LLM - 경량 GNN으로 GPU 없이 가장 빠른 PDF 파서

개요

기술 배경

PyMuPDF / MuPDF / PyMuPDF4LLM 관계

MuPDF (C 라이브러리, Artifex)
  └── PyMuPDF (Python 바인딩)
       ├── pymupdf-layout (레이아웃 분석 모듈)
       └── PyMuPDF4LLM (LLM/RAG용 Markdown 변환)

• MuPDF: Artifex Software가 개발한 경량 PDF/XPS 렌더링 엔진 (C 언어)
• PyMuPDF (fitz): MuPDF의 Python 바인딩. PDF 읽기/쓰기/렌더링
• pymupdf-layout: PDF 텍스트 레이아웃 분석 확장 모듈 (다단 감지, 읽기 순서)
• PyMuPDF4LLM: 위 세 라이브러리를 활용하여 LLM/RAG에 최적화된 Markdown 출력 생성

핵심 특징: 경량 ML + 규칙 기반 하이브리드

PDF 내부 구조를 직접 활용하되, 레이아웃 분석에는 경량 ML을 사용한다:

• 텍스트 추출: PDF 텍스트 객체에서 직접 추출 — 규칙 기반 (OCR 불필요, 텍스트 PDF인 경우)
• 레이아웃 분석: pymupdf-layout의 GNN(Graph Neural Network) 모델 — 텍스트 박스를 노드, 공간 관계를 엣지로 처리하여 제목/단락/표/그림 패턴 학습. ONNX Runtime으로 CPU 추론 (GPU 불필요)
• 헤딩 감지: 폰트 크기와 볼드 여부로 판별 — 규칙 기반
• 테이블 감지: PDF 내부의 선(line) 객체와 텍스트 좌표로 테이블 구조 추론 — 규칙 기반
• 이미지 추출: PDF 내장 이미지 객체 직접 추출 — 규칙 기반
• 다단 감지: GNN 레이아웃 분석 + XY-Cut 알고리즘

"Heuristics do the heavy lifting upfront, so the model doesn't have to" — 휴리스틱이 특성을 먼저 추출하고, GNN은 패턴 분류만 수행하는 구조다.

내부 파이프라인

PDF 입력
  → pymupdf.open() (PDF 파싱)
  → StructTreeRoot 제거 (성능 최적화)
  → 페이지별 처리:
      ├── OCR 필요 여부 판단 (analyze_page)
      ├── (필요시) OCR 실행 (Tesseract/PaddleOCR/RapidOCR)
      ├── pymupdf-layout으로 레이아웃 분석 (GNN + ONNX Runtime)
      │   ├── 텍스트 블록 → 그래프 노드/엣지 변환
      │   ├── GNN 모델로 블록 분류 (title/text/table/picture)
      │   ├── 다단 감지 (Stripe-based Column Clustering)
      │   └── 읽기 순서 결정
      ├── 폰트 크기 기반 헤딩 감지
      ├── 선(line) + 가상선(virtual line) 기반 테이블 감지
      └── 이미지 객체 추출
  → ParsedDocument 생성
  → to_markdown() / to_json() / to_text() 변환

OCR 모드

PyMuPDF4LLM은 기본적으로 텍스트 PDF에서 직접 추출하지만, 스캔 문서를 위한 OCR 폴백을 지원한다:

지원 OCR 엔진: Tesseract, PaddleOCR, RapidOCR

설치 및 사용법

uv venv pymupdf-env --python 3.12
source pymupdf-env/bin/activate
uv pip install pymupdf4llm
 
# OCR 기능 추가 시
uv pip install "pymupdf4llm[ocr]"       # Tesseract
uv pip install "pymupdf4llm[layout]"    # 레이아웃 분석 강화

Python API

import pymupdf4llm
 
# 기본 사용
md = pymupdf4llm.to_markdown("input.pdf")
 
# 이미지 추출 포함
md = pymupdf4llm.to_markdown("input.pdf", write_images=True, image_path="./images")
 
# 페이지별 청크
chunks = pymupdf4llm.to_markdown("input.pdf", page_chunks=True)
 
# JSON 출력
data = pymupdf4llm.to_json("input.pdf")
 
# OCR 강제 적용
md = pymupdf4llm.to_markdown("input.pdf", force_ocr=True, ocr_language="kor")

주요 파라미터

Attention Is All You Need 파싱 결과

원본 PDF 1페이지

PyMuPDF4LLM의 Markdown 출력

테스트 결과

테스트 환경

속도 측정

4개 문서 × 3설정 = 12회 테스트 총합: ~45초. MinerU로 영문 논문 1개 파싱하는 시간(1분 50초)보다 12회 테스트 전체가 더 빠르다.

콘텐츠 추출 비교

헤딩 처리

PyMuPDF4LLM은 PDF의 폰트 크기와 볼드 여부를 기반으로 헤딩을 감지한다. PDF의 TOC(Table of Contents)도 참조한다.

## **Abstract**                    ← H2로 처리
## **1 Introduction**              ← H2로 처리
## **2 Background**                ← H2로 처리
## **3 Model Architecture**        ← H2로 처리
## **3.1 Encoder and Decoder**     ← H2로 처리 (H3이어야 함)

MinerU가 전부 H1으로 처리하는 것과 달리 H2를 기본으로 사용하지만, 하위 섹션(3.1, 2.1.1 등)도 H2로 처리하여 계층 구분이 안 되는 건 동일한 한계다.

테이블 처리

Markdown pipe 테이블 형식으로 변환한다:

|Layer Type|Complexity per Layer|Sequential|Maximum Path Length|
|---|---|---|---|
|||Operations||
|Self-Attention|_O_(_n_2 _· d_)|_O_(1)|_O_(1)|

HTML <table> 대신 순수 Markdown을 사용하므로 rowspan/colspan은 지원하지 않는다. 복잡한 병합 셀은 빈 셀이나 중복 텍스트로 대체된다.

수식 처리

수식 LaTeX 변환을 지원하지 않는다. 수식은 텍스트 그대로 추출된다:

# MinerU 출력 (LaTeX):
$$( \mathcal V _ { j } , \mathcal E _ { j } ) = R ( d _ { j } ^ { \mathrm { c h u n k } } )$$

# PyMuPDF4LLM 출력 (텍스트):
_O_(_n_2 _· d_)
divide each by √dk, and apply a softmax function

수식이 많은 학술 논문에서는 이 한계가 크다.

이미지 처리

기본 설정에서는 이미지를 건너뛰고 ==> picture [W x H] intentionally omitted <== 메시지를 남긴다.

write_images=True로 설정하면 PDF 내장 이미지 객체를 직접 추출한다. OCR이나 레이아웃 감지로 이미지를 찾는 게 아니라 PDF 내부 이미지 참조를 그대로 가져오므로 추출 속도가 빠르고 원본 품질이 보존된다.

PPT 슬라이드에서는 92개의 이미지가 추출되었다 — 슬라이드 내 모든 다이어그램, 아이콘이 개별 이미지 객체로 분리되어 있기 때문.

한국어 처리

텍스트 기반 PDF의 경우 한국어 추출이 잘 된다 (OCR 불필요):

## < 요 약 문 >
|사업명|사업명|...|KISTEP 일반사업|...|

한글 텍스트가 정상 추출되고, 테이블 구조도 보존된다. 단, 스캔 문서에서 한국어 OCR이 필요한 경우 Tesseract ocr_language="kor" 설정이 필요하다.

PPT 슬라이드 처리

PPT 스타일 PDF에서 특이한 기능이 있다 — 이미지 내 텍스트를 picture text로 추출한다:

**==> picture [849 x 287] intentionally omitted <==**
**----- Start of picture text -----**
Translation
The      protests  escalated    over         the      weekend
...
**----- End of picture text -----**

다이어그램 안의 텍스트까지 추출하는 건 독특한 장점이다.

생태계

LangChain / LlamaIndex 연동

• LlamaIndex: LlamaMarkdownReader 내장 (pymupdf4llm에 포함)
• LangChain: PyMuPDFLoader 공식 지원

# LlamaIndex
from pymupdf4llm import LlamaMarkdownReader
reader = LlamaMarkdownReader()
documents = reader.load_data("input.pdf")
 
# LangChain
from langchain_community.document_loaders import PyMuPDFLoader
loader = PyMuPDFLoader("input.pdf")
docs = loader.load()

출력 형식

• to_markdown() → Markdown 문자열 또는 페이지별 청크 리스트
• to_json() → JSON (레이아웃 정보 포함)
• to_text() → 순수 텍스트 (tabulate 포맷 테이블)

장단점 분석

장점

• 압도적 속도: 0.050.25초/페이지, ML 파서 대비 10100배 빠름
• GPU 불필요: CPU만으로 동작, 서버/CI 환경에서 유리
• 모델 다운로드 없음: 설치 즉시 사용 가능 (~50MB)
• 원본 품질 보존: PDF 내장 객체 직접 추출 (텍스트, 이미지)
• 한국어 지원: 텍스트 PDF에서 즉시 한글 추출
• PPT 이미지 텍스트: 다이어그램 내 텍스트도 추출
• LangChain/LlamaIndex 공식 연동
• 상용 라이선스 구매 가능: AGPL이 불편하면 상용 라이선스 옵션 존재

단점

• 수식 LaTeX 변환 불가: 수식이 텍스트로만 추출됨
• 헤딩 레벨 부정확: 모든 헤딩이 H2, 계층 구분 안 됨
• rowspan/colspan 미지원: 복잡한 테이블 구조 손실
• 스캔 문서 한계: OCR 폴백은 있지만 Tesseract 기반이라 정확도가 ML 파서보다 낮음
• 레이아웃 분석 한계: 규칙 기반이라 비정형 레이아웃에서 읽기 순서 오류 가능
• AGPL-3.0 라이선스: 기본은 AGPL (PyMuPDF 의존성)

추천 사용처

MinerU와의 비교

| 항목 | PyMuPDF4LLM | MinerU |
|---|---|---|
| 속도 (18p 논문) | 4.5초 | 1분 50초 (MPS) |
| 수식 LaTeX | X | O (UniMERNet) |
| 테이블 형식 | Markdown pipe | HTML (rowspan/colspan) |
| 이미지 추출 | PDF 내장 직접 | 레이아웃 감지 기반 |
| 헤딩 레벨 | 전부 H2 | 전부 H1 |
| OCR | Tesseract 폴백 | PytorchPaddleOCR (109언어) |
| GPU | 불필요 | 선택 (MPS/CUDA) |
| 모델 크기 | 0 | ~2GB |
| 라이선스 | AGPL-3.0 | AGPL-3.0 |

정리

PyMuPDF4LLM은 "충분히 좋은 품질을 미친 속도로" 제공하는 파서다. 수식 변환이나 복잡한 테이블 구조가 필요 없는 일반 문서 처리에서는 ML 파서를 쓸 이유가 없을 정도로 빠르고 간편하다. 대량 PDF 배치 처리, CI/CD 파이프라인 내 문서 인덱싱, 서버 리소스가 제한된 환경에서 특히 강력하다.

다만 학술 논문의 수식, 복잡한 테이블 병합, 스캔 문서 OCR이 중요하다면 MinerU나 Docling 같은 ML 기반 파서가 필요하다.

이 파서의 헤딩/테이블/수식/이미지 처리 결과를 다른 파서와 직접 비교한 글: PDF 파서 5종 비교 분석

참고

• PyMuPDF4LLM GitHub
• PyMuPDF 공식 문서
• Artifex Software
• MinerU - PDF Parser — MinerU 1.x 분석
• 2026-03-23-MinerU-2x-파이프라인-분석 — MinerU 2.x 파이프라인 분석