PDF2MD - 고성능 PDF to Markdown 변환기

PyMuPDF를 사용한 빠르고 정확한 PDF to Markdown CLI 유틸리티입니다.

🚀 주요 특징

• 초고속 변환: 446페이지를 2초에 처리 (222 페이지/초, 32만 문자/초)
• 높은 정확도: 텍스트 추출 성공률 99.8%
• 순수 텍스트 추출: 불필요한 이미지 변환 없음
• 크기 최적화: 원본 대비 95% 크기 감소 (12.5MB → 0.6MB)
• 간편한 사용: 직관적인 CLI 인터페이스
• 유연한 옵션: 페이지 선택, 변환 방법 선택 등

📊 실제 성능 테스트

테스트 PDF: The Staff Engineer's Path (446페이지, 12.54MB)

개선된 변환기 (PyMuPDF 직접 사용) - 권장 ✅

• ✅ 텍스트 추출 성공률: 99.8% (445/446 페이지)
• ✅ 생성 파일: 1개 (Markdown만)
• ✅ 출력 크기: 0.62MB (순수 텍스트)
• ✅ 처리 속도: 222.9 페이지/초, 319,969 문자/초
• ✅ 소요 시간: 2.00초
• ✅ 크기 감소: 95.0%

기존 방식 (PyMuPDF4LLM) - 비권장 ❌

• ❌ 텍스트 추출 실패: 대부분의 페이지가 이미지로 변환
• ❌ 생성 파일: 381개 (이미지 파일)
• ❌ 출력 크기: 78MB (대부분 PNG)
• ❌ 실용성: 낮음

설치

# 프로젝트 디렉토리로 이동
cd ~/Documents/Projects/pdf2md

# 개발 모드로 설치
pip install -e .

# 또는 테스트 도구 포함 설치
pip install -e ".[dev]"

사용법

기본 변환 (권장)

# 개선된 변환기 사용 (기본값)
pdf2md document.pdf

입력 파일과 같은 디렉토리에 document.md 파일이 생성됩니다.

출력 파일 지정

pdf2md document.pdf -o output.md

특정 페이지만 변환

# 1-10페이지와 15페이지만 변환
pdf2md document.pdf -p "1-10,15"

# 첫 50페이지만 변환
pdf2md document.pdf -p "1-50"

변환 방법 선택

# 개선된 변환기 사용 (기본값, 권장)
pdf2md document.pdf --method direct

# 기존 PyMuPDF4LLM 사용
pdf2md document.pdf --method pymupdf4llm

# 자동 선택 (현재는 direct와 동일)
pdf2md document.pdf --method auto

상세 출력 모드

pdf2md document.pdf -v

PDF 정보 확인

pdf2md document.pdf --info

CLI 옵션

• PDF_PATH: 변환할 PDF 파일 경로 (필수)
• -o, --output PATH: 출력 Markdown 파일 경로 (기본: 입력파일명.md)
• -p, --pages RANGE: 변환할 페이지 범위 (예: "1-5,7,9-12")
• --method [auto|direct|pymupdf4llm]: 변환 방법 선택 (기본: direct)
• --with-images / --no-images: 이미지 추출 여부 (기본: no-images)
• -v, --verbose: 상세 출력 모드
• --info: PDF 정보만 출력

변환 방법 비교

Direct (PyMuPDF 직접 사용) - 권장 ✅

장점:

• 텍스트 추출 정확도 매우 높음 (99.8%)
• 빠른 처리 속도 (222 페이지/초)
• 불필요한 이미지 파일 생성 안 함
• 작은 출력 파일 크기

단점:

• 기본적인 Markdown 포맷팅
• 이미지는 별도 추출 필요

적합한 경우:

• 텍스트 중심의 PDF (책, 논문, 문서)
• 빠른 변환이 필요한 경우
• 저장 공간이 제한적인 경우

PyMuPDF4LLM

장점:

• LLM 친화적인 Markdown 구조

단점:

• 일부 PDF에서 텍스트 추출 실패
• 모든 페이지를 이미지로 변환할 수 있음
• 느린 처리 속도
• 큰 출력 파일 크기

적합한 경우:

• 특정 형식의 PDF에만 권장
• LLM 입력용 최적화가 필요한 경우

성능 벤치마크

PDF 크기	페이지 수	변환 시간 (Direct)	처리 속도
12.5MB	446	2.00초	222 페이지/초
예상 1MB	10	~0.04초	~250 페이지/초
예상 10MB	100	~0.45초	~222 페이지/초
예상 50MB	500	~2.25초	~222 페이지/초

개발

프로젝트 구조

pdf2md/
├── pdf2md/
│   ├── __init__.py          # 패키지 초기화
│   ├── __main__.py          # CLI 진입점
│   ├── cli.py               # CLI 인터페이스
│   ├── converter.py         # 기존 변환기 (PyMuPDF4LLM)
│   ├── converter_v2.py      # 개선된 변환기 (PyMuPDF 직접)
│   ├── utils.py             # 유틸리티 함수
│   └── config.py            # 설정 상수
├── tests/
│   ├── test_converter.py    # 변환기 테스트
│   └── test_utils.py        # 유틸리티 테스트
├── pyproject.toml           # 프로젝트 설정
└── README.md                # 문서

테스트 실행

# 전체 테스트
pytest tests/ -v

# 커버리지 포함
pytest tests/ --cov=pdf2md --cov-report=html

# 특정 테스트만
pytest tests/test_utils.py -v

테스트 결과

21 passed, 7 skipped (실제 PDF 파일 필요)

기술 스택

• PyMuPDF (fitz): 고성능 PDF 처리 라이브러리
• PyMuPDF4LLM: LLM 친화적 Markdown 변환 (옵션)
• Click: CLI 프레임워크
• Rich: 터미널 출력 포맷팅
• pytest: 테스트 프레임워크

라이선스

MIT License

기여

이슈 및 Pull Request를 환영합니다!

향후 계획

• 더 나은 Markdown 포맷팅 (제목, 리스트 등 자동 감지)
• 표 추출 및 변환
• 이미지 추출 옵션 개선
• 병렬 처리 지원 (대용량 PDF)
• OCR 지원 (스캔 PDF)
• 배치 변환 기능

문제 해결

PyMuPDF4LLM으로 텍스트가 추출되지 않는 경우

# 개선된 변환기 사용 (기본값)
pdf2md document.pdf --method direct

메모리 부족 오류

# 페이지 범위를 나누어 변환
pdf2md large.pdf -p "1-100" -o part1.md
pdf2md large.pdf -p "101-200" -o part2.md

참고 자료

• PyMuPDF 공식 문서
• PyMuPDF4LLM GitHub
• Click 문서