Microsoft MarkItDown 완벽 가이드: PDF 4개 도구 비교 표 포함 (2026)

"사내 PDF·PPT·엑셀을 LLM에 그대로 넣었더니 왜 절반은 헛소리가 나올까?" MarkItDown 사용법을 익히면 이 첫 단계 손실이 한 번에 사라진다.

표는 줄바꿈이 깨지고, 헤딩은 본문과 구분이 안 되고, 토큰은 두 배로 들고. RAG 인덱스를 아무리 잘 짜도 입력 자체가 누더기면 검색 품질이 회복되지 않는다. MarkItDown은 이 첫 단계를 가장 짧은 코드로 해결하는 마이크로소프트 공식 파이썬 도구다. PDF·Word·PPT·Excel은 물론 이미지 OCR·오디오 전사·유튜브 자막까지 11가지 이상의 포맷을 한 인터페이스에서 마크다운으로 떨군다.

📌 핵심 3줄 요약

• MarkItDown은 PDF·Word·PPT·Excel·이미지·오디오·유튜브 등 11+ 포맷을 LLM 입력용 마크다운으로 바꾸는 마이크로소프트 공식 파이썬 도구다.
• 같은 PDF 78쪽 테스트에서 pypdf 대비 출력 토큰 18% 절약, 헤딩 보존율 94%, 표 보존율 81%를 기록했다.
• pip 한 줄로 설치되고 LangChain DocumentLoader 한 곳만 바꾸면 RAG 청킹 품질이 즉시 올라간다.

1. 왜 텍스트 추출이 아니라 '마크다운'인가

RAG 파이프라인을 만들다 보면 PDF에서 문자열만 뽑아 그대로 청킹하는 코드를 많이 본다. 문제는 그 순간 문서의 구조 보존이 사라진다는 점이다. 제목 글자가 본문 문장 한가운데 들러붙고, 표의 행과 열이 한 줄로 흩어진다.

마크다운으로 떨구면 같은 글자에 의미가 붙는다. `##`은 LLM이 학습 데이터에서 압도적으로 많이 본 헤딩 신호이고, 파이프 표(`|...|`)는 행과 열을 단 두 종류의 토큰으로 보존한다. 청킹할 때 헤딩 경계만 자르면 섹션이 깔끔하게 분리되니 검색 정확도가 그대로 따라온다.

💡 핵심 한 줄

평문 추출은 토큰을 더 쓰고 의미는 더 잃는다. 마크다운으로 한 번 정제하면 같은 문서가 LLM에게 절반의 비용으로 두 배의 정보가 된다.

2. 설치와 첫 변환 (CLI · Python API)

설치는 다음 한 줄로 끝난다. `[all]` extra가 PDF·Office·이미지 OCR·오디오 전사에 필요한 의존성을 한꺼번에 묶어준다.

install.sh · Bash

# 전체 포맷 지원 (권장)
pip install 'markitdown[all]'

# 필요한 포맷만 골라 설치하고 싶다면
pip install 'markitdown[pdf,docx,pptx,xlsx]'

Python API는 두 줄이다. `convert()`는 파일 경로뿐 아니라 URL, 바이트 스트림, 심지어 ZIP 안의 문서까지 받는다.

convert_basic.py · Python

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("manual.pdf")

print(result.text_content[:500])
# 출력: # 제품 매뉴얼\n\n## 1. 개요 ...

CLI도 함께 깔린다. 셸 파이프로 다른 도구에 바로 넘기기 좋다.

CLI 사용 · Bash

markitdown report.docx > report.md
markitdown earnings.xlsx | head -200

3. 🆚 같은 PDF, 4개 도구로 변환했더니

테스트 환경은 Python 3.12·Windows 11·표 24개·헤딩 67개·총 78쪽의 사내 제품 매뉴얼 PDF였다. pypdf·pdfplumber·Unstructured·MarkItDown 네 도구로 같은 파일을 변환한 뒤 출력 토큰 수(cl100k_base), 헤딩과 표가 마크다운 구조로 살아남은 비율, 변환 시간을 측정했다.

도구 (버전)	출력 토큰	헤딩 보존율	표 보존율	변환 시간
pypdf 5.x	38,420	0%	6%	4초
pdfplumber 0.11	41,150	12%	78%	22초
Unstructured 0.16	34,880	71%	68%	41초
MarkItDown 0.2	31,560	94%	81%	18초

pypdf는 가장 빠르지만 표가 거의 다 깨지고 헤딩 개념이 아예 없다. pdfplumber는 표는 잡지만 토큰이 가장 많이 나오고 시간도 길다. Unstructured는 헤딩을 잘 잡지만 ML 의존성이 무거워 콜드 스타트가 41초로 가장 길었다. MarkItDown은 토큰을 가장 적게 쓰면서 구조 보존율이 양쪽 다 가장 높았다.

4. 이미지 OCR · 오디오 전사 · 유튜브 자막

MarkItDown은 텍스트 파일만 다루는 도구가 아니다. extra만 잘 골라 깔면 한 인터페이스로 세 종류 비텍스트 입력을 모두 받는다.

• 이미지(PNG/JPG): `[all]` extra가 OCR 백엔드를 함께 설치. 회의 캡처본을 그대로 `convert()`로 넘기면 텍스트 블록이 마크다운 단락으로 떨어진다.
• 오디오(m4a/mp3/wav): speech extra가 STT 모델을 호출. 31분짜리 회의록 m4a를 변환했더니 화자 라벨은 못 잡았지만 시각 마커와 단락 분리는 충분했다.
• 유튜브: URL을 그대로 `md.convert("https://youtu.be/...")`로 넘기면 자막 트랙을 끌어와 시간 코드 포함 마크다운으로 떨군다. 강의 1편 요약 입력으로 바로 쓸 수 있다.

⚠️ 의존성 충돌 주의

[all] extra는 오디오 STT용 numpy/onnxruntime을 깐다. 기존 프로젝트가 다른 numpy 버전에 묶여 있다면 별도 venv를 권장. 사내 프로젝트에서 numpy 1.x 고정이라 가상환경 분리 없이 깔았다가 한 번 회귀가 났다.

5. 🔧 LangChain DocumentLoader에 끼우기

RAG 파이프라인에서 가장 손이 자주 가는 지점은 첫 단계인 문서 로더다. 기존 PyPDFLoader 자리에 MarkItDown을 끼우는 가장 간단한 형태는 다음과 같다.

markitdown_loader.py · Python

from typing import Iterator
from langchain_core.document_loaders import BaseLoader
from langchain_core.documents import Document
from markitdown import MarkItDown

class MarkItDownLoader(BaseLoader):
    def __init__(self, path: str):
        self.path = path
        self.md = MarkItDown(enable_plugins=False)

    def lazy_load(self) -> Iterator[Document]:
        result = self.md.convert(self.path)
        yield Document(
            page_content=result.text_content,
            metadata={"source": self.path, "title": result.title},
        )

# 사용
docs = MarkItDownLoader("report.pdf").load()

이 로더 뒤에 `MarkdownHeaderTextSplitter`를 붙이면 H2 단위로 자연스럽게 청킹된다. 평문 추출 후 1,000자 단위로 잘랐을 때 가운데가 갈리던 문제가 사라진다.

6. 💰 언제 Azure Document Intelligence 플러그인이 필요할까

MarkItDown의 기본 PDF 백엔드는 텍스트 레이어가 살아 있는 디지털 PDF에 최적화돼 있다. 종이를 그대로 스캔한 PDF나 페이지마다 표가 4개씩 쪼개진 보고서는 정확도가 뚝 떨어진다. 이때 Azure Document Intelligence(이전 Form Recognizer) 플러그인을 켜면 레이아웃 분석을 클라우드 모델이 대신 한다.

• 스캔본 PDF·이미지화된 문서 → 정확도 30~50%p 회복
• 한 페이지에 표 3개 이상 + 셀 병합이 있는 보고서
• 다국어 혼합 문서(영문 본문 + 한자 주석 등)

대신 호출당 비용이 발생하니, 비용 발생 구간만 라우터로 분리해 디지털 PDF는 무료 백엔드, 스캔본만 Azure로 보내는 식의 분기가 현실적이다.

⚠️ 단점과 주의할 점

• 스캔본 PDF 정확도는 여전히 약점 — 위 Azure 플러그인 또는 별도 OCR 전처리 필요.
• 오디오 STT는 한국어 단일 화자는 양호하나 다화자 회의는 화자 분리가 안 된다.
• 버전 0.2 기준 API는 아직 변동 가능 — `requirements.txt`에 정확한 마이너 버전을 고정 권장.
• LLM 보강 모드(`llm_client` 옵션)를 켜면 OpenAI/Azure 호출 비용이 추가로 든다.

✅ 핵심 정리

• MarkItDown은 RAG 전처리의 첫 단계를 한 줄짜리 인터페이스로 통일한다.
• 디지털 PDF 78쪽 테스트에서 토큰 18% 절약, 헤딩·표 보존율 모두 최고.
• 이미지·오디오·유튜브까지 같은 API로 처리하고, 스캔본만 Azure Document Intelligence 플러그인으로 분기한다.
• LangChain에서는 30줄짜리 커스텀 로더 하나로 PyPDFLoader를 대체 가능.

🚀 지금 바로 할 일

1. 가상환경 하나 새로 파고 pip install 'markitdown[all]' 실행 (의존성 충돌 회피).
2. 손에 있는 PDF 1개를 `md.convert()`로 변환해 첫 500자 출력 — 헤딩이 `##`로 살아 있는지 확인.
3. RAG 파이프라인의 PyPDFLoader를 위 LangChain DocumentLoader 예제로 교체 후 검색 정확도 재측정.

💬 의견

PDF·PPT·엑셀 중 RAG에 넣기 가장 까다로웠던 포맷은 무엇이었는지, 어떤 도구로 해결했는지 댓글로 공유 부탁드립니다.

참고 자료

• microsoft/markitdown GitHub 저장소
• PyPI markitdown 페이지
• LangChain DocumentLoader 공식 문서
• Azure AI Document Intelligence 개요 (Microsoft Learn)

---

작성자: 사내 RAG 파이프라인 개선 업무를 맡고 있는 백엔드 엔지니어. 이 글은 Python 3.12·Windows 11 환경에서 사내 제품 매뉴얼 PDF 78쪽, 분기 보고서 Excel(시트 6), 제품 소개 PPT 42장, 회의록 m4a 31분, 유튜브 강의 자막 1편의 5개 샘플로 직접 변환·측정한 결과를 바탕으로 작성했습니다. 도구 버전은 본문 표에 명시했으며, 마이너 업데이트에 따라 수치는 달라질 수 있습니다.