PyMuPDF4LLM

PyMuPDF4LLM은 PyMuPDF(fitz) 기반의 PDF 전용 변환 도구로, PDF를 LLM에 최적화된 Markdown으로 변환합니다. 빠른 속도와 정확한 텍스트 추출이 강점입니다.

pip install pymupdf4llm

기본 변환
이미지 추출 (Markdown 링크)
페이지별 변환
표 추출

import pymupdf4llm

# PDF -> Markdown 변환
md_text = pymupdf4llm.to_markdown("document.pdf")
print(md_text)

write_images=True 옵션으로 PDF 내 이미지를 별도 파일로 추출하고, Markdown에서 ![]()로 참조합니다.

import pymupdf4llm
from pathlib import Path

# 이미지 저장 디렉토리 생성
image_dir = Path("output/images")
image_dir.mkdir(parents=True, exist_ok=True)

# 이미지 추출 + Markdown 변환
md_text = pymupdf4llm.to_markdown(
    "document.pdf",
    write_images=True,           # 이미지를 파일로 저장
    image_path=str(image_dir),   # 이미지 저장 경로
    image_format="png",          # 이미지 형식 (png, jpg)
    dpi=150,                     # 이미지 해상도
)

# Markdown 저장
output_path = Path("output/document.md")
output_path.write_text(md_text, encoding="utf-8")

생성된 Markdown 파일 내에서 이미지는 다음과 같이 참조됩니다:

# Introduction

This paper presents a novel approach to...

![output/images/document.pdf-1-0.png](output/images/document.pdf-1-0.png)

The architecture shown above demonstrates...

## Related Work

Previous studies have explored...

![output/images/document.pdf-2-0.png](output/images/document.pdf-2-0.png)

이미지 파일명은 {pdf파일명}-{페이지번호}-{이미지인덱스}.{확장자} 형태로 자동 생성됩니다.

특정 페이지만 선택적으로 변환할 수 있습니다.

import pymupdf4llm

# 특정 페이지만 변환 (0-indexed)
md_text = pymupdf4llm.to_markdown(
    "document.pdf",
    pages=[0, 1, 2],  # 첫 3페이지만
)

# 페이지 단위로 분리된 결과 (LangChain Document 형태)
docs = pymupdf4llm.to_markdown(
    "document.pdf",
    page_chunks=True,  # 페이지별 분리
)

for doc in docs:
    print(f"Page {doc['metadata']['page']}: {len(doc['text'])} chars")

PyMuPDF4LLM은 PDF 내 표를 Markdown 표 형식으로 변환합니다.

import pymupdf4llm

md_text = pymupdf4llm.to_markdown(
    "report.pdf",
    show_progress=True,  # 변환 진행률 표시
)

# 변환된 Markdown에서 표가 자동으로 감지됨:
# | Column A | Column B | Column C |
# |----------|----------|----------|
# | Value 1  | Value 2  | Value 3  |

PyMuPDF4LLM + 청킹 파이프라인

변환된 Markdown을 LangChain 또는 Chonkie로 청킹하는 전체 파이프라인입니다.

import pymupdf4llm
from langchain_text_splitters import MarkdownHeaderTextSplitter
from langchain_core.documents import Document
from pathlib import Path

# 1. PDF -> Markdown 변환 (이미지 포함)
image_dir = Path("output/images")
image_dir.mkdir(parents=True, exist_ok=True)

md_text = pymupdf4llm.to_markdown(
    "document.pdf",
    write_images=True,
    image_path=str(image_dir),
    image_format="png",
    dpi=150,
)

# 2. Markdown 헤딩 기반 청킹
splitter = MarkdownHeaderTextSplitter(
    headers_to_split_on=[
        ("#", "h1"),
        ("##", "h2"),
        ("###", "h3"),
    ],
)
chunks = splitter.split_text(md_text)

# 3. 이미지 링크가 포함된 청크 확인
for chunk in chunks:
    has_image = "![" in chunk.page_content
    print(f"[{chunk.metadata}] {'(이미지 포함)' if has_image else ''}")
    print(chunk.page_content[:200])
    print("---")

이미지 링크가 포함된 청크는 멀티모달 RAG 파이프라인에서 활용할 수 있습니다. 이미지 경로를 메타데이터로 추출하여, 검색 시 관련 이미지를 함께 제공하면 답변 품질이 향상됩니다.

주요 옵션

옵션	설명	기본값
`write_images`	이미지를 파일로 추출	`False`
`image_path`	이미지 저장 디렉토리	`"."`
`image_format`	이미지 형식 (`"png"`, `"jpg"`)	`"png"`
`dpi`	이미지 해상도 (DPI)	`150`
`pages`	변환할 페이지 목록 (0-indexed)	전체
`page_chunks`	페이지별 분리 반환	`False`
`show_progress`	진행률 표시	`False`

학습 목표

이 문서의 핵심 개념을 실제 프로젝트 시나리오로 연결할 수 있습니다.
최소 1개 실습 과제를 수행하고 결과를 비교할 수 있습니다.
다음 단계에서 필요한 입력 데이터/도구를 준비할 수 있습니다.

00. RAG 개요

01. RAG 개발 단계

02. RAG 성능 최적화

03. RAG 아키텍처 계보

PyMuPDF4LLM + 청킹 파이프라인

주요 옵션

학습 목표

실무 적용 체크리스트

다음 문서

다음: 청킹 전략

00. RAG 개요

01. RAG 개발 단계

02. RAG 성능 최적화

03. RAG 아키텍처 계보

​PyMuPDF4LLM + 청킹 파이프라인

​주요 옵션

​학습 목표

​실무 적용 체크리스트

​다음 문서

다음: 청킹 전략

PyMuPDF4LLM + 청킹 파이프라인

주요 옵션

학습 목표

실무 적용 체크리스트

다음 문서