파이썬으로 PDF를 Markdown으로 변환하는 방법

왜 Markdown인가, 그리고 왜 보기보다 어려운가

LLM은 Markdown을 매우 잘 다룹니다: 제목이 섹션 경계를 표시하고, 파이프 표가 표 형식 데이터를 정렬된 채로 유지하며, 목록은 목록으로 남습니다. PDF에서 그냥 추출한 원시 텍스트를 모델에 입력하면 이 모든 것이 사라지고, PDF 바이너리를 입력하는 것은 대부분의 파이프라인에서 선택지가 아닙니다. 그래서 진지한 RAG 스택은 거의 모두 청킹과 임베딩 전에 문서를 Markdown으로 변환합니다.

어려운 이유는 PDF에 구조가 없기 때문입니다 — PDF에는 x/y 좌표에 배치된 문자들만 들어 있습니다. 변환기는 어떤 줄이 제목인지(글꼴 크기로), 어떤 단어들이 표를 이루는지(정렬로), 읽기 순서가 무엇인지(레이아웃 분석으로) 역으로 추론해야 합니다. 라이브러리마다 이 작업의 완성도가 크게 다르기 때문에 선택이 중요합니다.

두 번째 문제도 있습니다: 스캔된 PDF에는 텍스트가 전혀 없고 페이지 이미지만 있습니다. 아래 선택지 중 일부만 OCR을 통해 이를 처리합니다.

선택지 1: PyMuPDF4LLM — 빠르고 가볍다

PyMuPDF4LLM은 LLM 파이프라인 전용으로 만들어진 PyMuPDF(fitz) 위의 얇은 레이어입니다: pip install pymupdf4llm 후 md = pymupdf4llm.to_markdown("doc.pdf") — 한 줄이면 되고, 대부분의 문서를 1초도 안 되어 처리할 만큼 매우 빠릅니다.

글꼴 크기로 제목을 감지하고, 표를 파이프 표로 렌더링하며, LlamaIndex나 LangChain에 바로 넣을 수 있는 메타데이터 포함 페이지 청크를 출력할 수 있습니다. 레이아웃이 단순한 디지털 원본 PDF — 보고서, 문서, 특이한 서식이 없는 논문 — 에는 훌륭한 기본 선택입니다.

한계: OCR이 없어 스캔 페이지는 빈 채로 돌아옵니다. 복잡한 다단 레이아웃과 정교한 표는 뒤섞여 나올 수 있는데, 내부 휴리스틱이 깊은 레이아웃 분석보다 속도를 우선하기 때문입니다. 라이선스 참고: PyMuPDF는 AGPL입니다 — 내부 도구에는 문제없지만, 상용 제품에 포함해 배포하기 전에 법무팀과 확인하세요.

선택지 2: Marker — 최고 품질, GPU 필요

Marker는 레이아웃 감지, 읽기 순서, 표 구조에 딥러닝 모델 파이프라인을 사용하며, 오픈소스 중 가장 충실한 Markdown을 생성합니다 — 다단 학술 논문, 복잡한 표, 심지어 수식까지 처리합니다.

대가는 인프라입니다: 수 기가바이트의 모델 가중치, 적정 속도를 위한 GPU(CPU도 되지만 느립니다 — 문서당 수십 초가 걸리기도 합니다), 그리고 프로덕션이나 서버리스 환경에 배포하려면 상당한 노력이 드는 무거운 의존성 트리입니다.

어려운 문서의 출력 품질이 최우선이고 하드웨어가 있다면 Marker를 선택하세요 — GPU 장비에서 학술 코퍼스를 대량 변환하는 것이 최적의 용도입니다. 가벼운 서비스나 서버리스 함수라면 운영 부담 때문에 보통 제외됩니다.

선택지 3: MarkItDown — Microsoft의 만능 변환기

MarkItDown은 '모든 것을 Markdown으로' 바꾸는 Microsoft의 오픈소스 라이브러리입니다: pip install markitdown 후 MarkItDown().convert("doc.pdf").text_content. 강점은 폭입니다 — 같은 API로 PDF, DOCX, PPTX, XLSX, HTML 등을 변환할 수 있어 LLM 데이터 준비용으로 크게 유행했습니다.

PDF에 한해서는 추출 방식이 전용 도구들보다 단순합니다: 기본 텍스트 추출에 의존하므로 제목 감지와 표 충실도가 PyMuPDF4LLM과 Marker에 못 미치고, 스캔 PDF에는 별도의 OCR 설정이 필요합니다.

여러 파일 형식을 하나의 의존성으로 중간 품질에 처리해야 할 때 — '사람들이 올리는 무엇이든' 받아야 하는 내부 수집 스크립트 같은 경우 — MarkItDown을 선택하세요. 최상의 PDF 출력이 목표라면 적합하지 않습니다.

선택지 4: 호스팅 API — 의존성 제로

네 번째 선택지는 변환을 로컬에서 돌리지 않는 것입니다: PDF를 파싱 API에 POST하고 Markdown을 받으세요. ParseJet 기준: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — JSON 응답의 "text" 필드가 Markdown입니다.

이 경로는 스캔 페이지용 OCR이 내장되어 있고, 설치할 모델 가중치나 네이티브 라이브러리가 없으며, 서버리스 함수·컨테이너·노트북 어디서든 동일하게 작동합니다. AGPL 문제도 완전히 비켜 갑니다. 트레이드오프는 네트워크 왕복과 무료 티어 이후의 문서당 비용입니다(월 300 크레딧 무료, PDF 1건 3 크레딧).

파이프라인을 오늘 바로 돌리고 싶을 때, PDF에 스캔본이 섞여 있을 때, 무거운 의존성이 부담스러운 곳 — Lambda, Cloud Run, Vercel — 에 배포할 때 API를 선택하세요.

무엇을 써야 할까?

디지털 원본 PDF에 단순~중간 레이아웃이고 속도가 중요하다면: PyMuPDF4LLM. 순수 파이썬에서 노력 대비 품질이 가장 좋습니다.

어려운 문서(다단 논문, 복잡한 표)이고 GPU가 있다면: Marker. 출력 품질에서 이를 능가하는 오픈소스는 없습니다.

여러 파일 형식을 하나의 라이브러리로 처리하고 중간 품질이면 충분하다면: MarkItDown.

스캔 PDF가 섞여 있거나, 서버리스에 배포하거나, 의존성 관리를 아예 하고 싶지 않다면: 호스팅 API. HTTP 호출 한 번, OCR 포함, 모든 문서에 동일한 출력 스키마입니다.

전체 예제: PDF 폴더를 Markdown 파일로

어떤 경로를 택하든 파이프라인 모양은 같습니다 — 반복, 변환, 저장. 다음은 API 버전입니다(로컬로 돌리려면 안쪽 호출을 pymupdf4llm.to_markdown()으로 바꾸세요):

import httpx; from pathlib import Path — 그다음 Path("pdfs/").glob("*.pdf")의 각 pdf에 대해: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

RAG 수집에서는 Markdown을 고정 글자 수가 아니라 제목 기준으로 청킹하세요 — 제목을 인식하는 청크는 섹션을 온전히 유지해 검색 품질이 극적으로 좋아집니다. 그 구조적 충실도가 바로 변환 단계를 정성 들여 할 가치가 있었던 이유입니다.