왜 임베딩 전에 변환기가 필요한가
RAG나 Agent를 구축할 때 보통 '임베딩'이 첫 단계라고 설명하지만, 실제로 돌려 보면 그 앞에 한 단계를 더 거쳐야 한다. PDF, Word, PPT 안에 들어 있는 내용을 모델이 안정적으로 소화할 수 있는 텍스트로 가공하는 일이다.
PDF는 다단 편집, 표, 각주가 섞여 있고, PPT에는 제목 단계와 불릿이 존재하며, Word에는 스타일 정보가 끼어든다. 원본 파일을 그대로 모델에 넘기면 파싱 결과를 예측하기 어렵다.
마이크로소프트가 오픈소스로 공개한 MarkItDown이 바로 이 지점을 담당한다. 사람을 위한 포맷 변환 도구가 아니며, 픽셀 단위 충실도를 보장하는 도구도 아니다. 흔히 쓰는 파일들을 LLM이 소비하기 좋은 Markdown으로 압축해 주는 것이 목표다.
GitHub에서 174k 이상의 Star를 기록하고 있다(수치는 변동 가능하니 저장소首页를 기준으로 확인). 지원하는 포맷은 다음과 같다.
- Word
- Excel
- PowerPoint
- 이미지 (EXIF, OCR 지원)
- 오디오 (EXIF, 음성 전사 지원)
- HTML, CSV, JSON, XML
- ZIP, EPub
- YouTube 링크
설계 목표는 명확하다. 출력은 사람이 보기 좋게 레이아웃된 문서가 아니라, LLM이 다루기 좋은 구조화된 텍스트여야 한다.
해결하려는 문제
임베딩 직전에는 보통 세 가지 작업이 필요하다.
- 본문 추출
- 제목, 목록, 표 등 구조 보존
- 모델이 처리할 수 있는 크기로 청크 분리
MarkItDown은 주로 앞 두 단계를 담당한다.
유사 도구들을 비교해 보면, textract은 노후화되었고 출력이 대개 순수 텍스트라 구조 정보가 많이 유실된다. pandoc은 문서 변환과 충실도에 강점이 있어 원본 레이아웃에 가깝게 보존해야 할 때 적합하다. unstructured도 기능이 풍부하지만 시스템이 무겁고 추상화 방식이 다르다.
MarkItDown은 중간 지점을 택했다.
- 가볍다.
- 문서 구조를 일정 부분 보존한다.
- Markdown으로 출력해 LLM 친화적이다.
- CLI와 Python API를 모두 제공한다.
Markdown은 일반적으로 복잡한 HTML이나 포맷 태그가 잔뜩 달린 텍스트보다 LLM 입장에서 토큰을 덜 소모한다. GPT-4o 같은 모델은 Markdown의 제목, 목록, 표, 코드 블록도 네이티브로 이해한다.
다만 Markdown이 항상 가장 짧은 표현은 아니다. 복잡한 Word 스타일이나 PDF의 머리글·바닥글, 좌표 기반 레이아웃은 변환 후에도 노이즈를 남길 수 있다. 그럼에도 충분히 안정적인 중간 포맷을 제공한다는 점에서 의의가 있다. 이후 청킹·검색·생성 단계가 동일한 텍스트를 기준으로 흘러갈 수 있다.
사용 방법
Python 3.10 이상에서 동작한다. 전체 기능 설치:
pip install 'markitdown[all]'PDF만 처리하는 경우:
pip install 'markitdown[pdf]'[docx], [pptx], [xlsx], [audio] 같은 그룹도 제공한다. OCR, 음성 전사, 모든 포맷을 다 깔아야 할 이유는 없다.
CLI:
markitdown file.pdf > out.mdPython API:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content[:500])
# 입력 출처 제한: 로컬 파일만 허용
from markitdown import MarkItDown, convert_local
result = convert_local("report.pdf")
print(result.text_content[:500])MarkItDown().convert()는 입력에 따라 변환 방식을 자동 선택하는 고수준 인터페이스다. convert_local()은 범위가 더 좁아서 로컬 파일만 처리한다.
보안 측면에서는 주의가 필요하다. README 상단에 명시된 대로 MarkItDown은 I/O 작업을 수반하므로, 권한 위험 수준은 Python의 open()이나 네트워크 요청의 requests.get()과 같다. 단순한 문서 변환 라이브러리라고 해서 신뢰할 수 없는 입력, 임의의 네트워크 주소, 높은 권한을 가진 Agent 환경에 그대로 두면 안 된다.
동작 방식
핵심 구조는 복잡하지 않다.
- 하나의
MarkItDown클래스 - 여러
Converter서브클래스 - 파일 확장자 또는 MIME 타입에 따라 Converter로 디스패치
- 각 Converter가 자기 포맷을 직접 처리
PDF는 PdfConverter, Word는 DocxConverter, PPT는 PptxConverter, YouTube 링크는 YoutubeConverter가 담당한다.
이런 설계는 하나의 큰 함수에 if/else를 잔뜩 쌓는 것보다 확장이 쉽다. 새 포맷을 추가하려면 보통 Converter 하나를 더하고 디스패치 로직만 연결하면 된다.
API는 세 단계로 나뉜다.
- 고수준:
MarkItDown().convert() - 중간 단계:
convert_local() - 저수준:
convert_stream()
호출 계층이 낮아질수록 권한 범위가 좁아지며, 로컬 파일·외부 네트워크·스트림 입력을 코드에서 명확히 구분할 수 있다. Agent에게 이 구분은 단순한 장식이 아니다. Agent가 사용자를 대신해 파일을 읽고, 네트워크에 접근하고, 신뢰할 수 없는 링크를 다루기 시작하는 순간, 권한 설계 자체가 핵심 기능이 된다.
이미지와 오디오 경로는 조금 다르다. 이미지는 EXIF를 추출하고 설정에 따라 OCR을 수행한다. 오디오는 메타데이터 추출과 음성 전사를 거친다. 이 부분은 보통 외부 서비스에 의존하므로, 배포 전에 서비스 사양, 비용, 데이터 흐름을 반드시 확인해야 한다.
장점과 한계
잘한 점
커버리지가 넓다. PDF, Office, 이미지, 오디오, 웹, 압축 파일, YouTube 링크를 하나의 도구로 다룬다.
API가 점진적이다. 가장 단순할 땐 CLI 한 줄로 끝나고, 통합이 필요하면 MarkItDown().convert()를 쓰고, 입력 출처를 제한해야 한다면 convert_local() 또는 convert_stream()까지 내려가면 된다.
보안 주의사항이 엔지니어링 관점에서 정직하게 적혀 있다. README가 로컬 파일, 네트워크 요청, 외부 서비스의 위험을 회피하지 않고 명시한다.
설치 시 의존성 크기를 고려한다. 전체 설치는 간편하고, 포맷별 설치는 환경을 가볍게 유지한다.
부족한 부분
첫째, 복잡한 레이아웃의 충실도는 pandoc에 미치지 못한다. PDF의 표가 페이지를 넘기는 경우, 각주, 떠 있는 이미지, 복잡한 머리글, 다단 레이아웃은 변환 후 순서가 흐트러질 수 있다. OCR 역시 이미지 품질에 좌우된다.
둘째, 이미지 OCR과 오디오 전사가 Azure, OpenAI 같은 외부 서비스에 의존할 수 있다. 완전한 로컬, CPU 전용, 데이터 반출 불가 환경이 필수라면 모델과 의존성을 직접 채워야 한다.
셋째, Excel은 통째로 한 파일에 우겨 넣기에 적합하지 않다. 대용량 워크북, 병합된 셀, 수식, 숨겨진 시트는 결과를 느리게 만들고 관련 없는 내용까지 끌어들인다. 운영 환경에서는 시트를 먼저 걸러내고, 행·열 범위를 제한하고, 수식을 비우거나, 표 단위로 쪼개는 전처리가 필요하다.
따라서 MarkItDown은 pandoc의 대체재가 아니며, '모든 문서를 완벽히 복원하는' 파서도 아니다. RAG 파이프라인의 첫 번째 세탁기에 더 가깝다.
실제로 돌려 봤다
로컬에 markitdown[pdf,docx,pptx]를 설치하고 세 종류 자료를 골랐다.
- 표가 포함된 20쪽 분량의 재무제표 PDF
- 20쪽짜리 PPT
- 5쪽짜리 Word
결과는 다음과 같았다.
- PDF의 표는 거의 보존되었고, 제목 단계도 정확했다.
- PPT는 불릿 구조가 유지됐다.
- Word 출력은 깔끔했고, 문단과 제목이 안정적이었다.
- PDF는 약 2초.
- PPT는 약 1초.
- Word는 1초 미만.
속도는 파일 복잡도에 크게 좌우된다. 이 환경에서 PDF 파싱은 PyMuPDF의 페이지 처리에서 시간을 잡아먹었다. 전체 파이프라인을 가장 늦추는 건 보통 거대한 Excel이다.
결과를 RAG에 넣으려면 result.text_content 이후에 두 가지 작업을 추가로 했다. 먼저 제목과 문단 단위로 청크를 나누고, 표·페이지 번호·파일명을 메타데이터로 붙였다. 500쪽짜리 PDF를 한 번의 convert()에 그대로 넣고 검색 품질이 안정적이길 기대하지 않는 게 좋다.
이런 사용자에게 추천한다
적합한 경우:
- RAG 문서 전처리
- Agent 툴체인의 데이터 진입점
- 대량 문서 정제
- PDF, Word, PPT를 Markdown으로 일괄 변환하는 스크립트
- 확장자나 MIME 타입에 따라 컨버터를 디스패치해야 하는 프로젝트
덜 적합한 경우:
- 픽셀 단위, 출판 수준의 레이아웃 충실도가 필요한 경우
- 반드시 오프라인으로 동작해야 하는 이미지 OCR 또는 음성 전사
- 복잡한 Excel 리포트의 통째 변환
- 좌표 단위 PDF 위치 추적, 읽기 순서 복원, 엄격한 표 의미 보존이 필요한 프로젝트
선택 기준은 단순하다. LLM에 텍스트를 먹이고 싶다면 먼저 MarkItDown을 시도하고, 레이아웃을 최대한 보존하고 싶다면 pandoc을, 무거운 문서 구역 분석과 데이터 처리가 필요하다면 unstructured를 살펴본다.
MarkItDown의 가치는 '지원하는 포맷 수' 자체에 있지 않다. Agent가 세상으로부터 입력받는 방식을 한 단계로 단순화한다. 파일이 들어오면 Markdown이 나간다.