MarkItDown AI RAG 문서 변환 활용 - PDF·Office를 Markdown으로 바꾸는 오픈소스 리뷰

 

microsoft/markitdown - PDF·Office·이미지 파일을 Markdown으로 바꾸는 문서 변환 도구 Stories

AI News

MarkItDown 리뷰 - PDF·Office 문서를 AI가 읽기 쉬운 Markdown으로 바꾸는 Microsoft 오픈소스

설치부터 RAG 파이프라인 연결, 플러그인 OCR, 대안 비교까지

microsoft/markitdown - PDF·Office·이미지 파일을 Markdown으로 바꾸는 문서 변환 도구

 

MarkItDown이란? - PDF·Office 문서를 AI용 Markdown으로 바꾸는 Microsoft 오픈소스

 

MarkItDown은 Microsoft AutoGen 팀이 만든 Python 도구로, PDF·Word·PowerPoint·Excel·이미지·오디오 등 15개 이상의 파일을 LLM이 바로 읽을 수 있는 Markdown으로 변환합니다.

RAG나 AI 에이전트를 만들 때 가장 먼저 부딪히는 병목이 문서 전처리입니다. PDF에서 텍스트를 깔끔하게 빼내는 것도 까다로운데, PowerPoint 슬라이드와 Excel 표까지 한 파이프라인에 넣어야 하는 경우가 흔합니다.

MarkItDown은 원래 Microsoft Research의 AutoGen(멀티 에이전트 프레임워크) 팀이 GAIA 벤치마크 평가를 위해 만든 전처리 도구에서 출발했습니다. 2024년 12월 오픈소스로 공개된 이후 꾸준히 성장해 2026년 5월 9일 기준 GitHub 스타 121,948개를 기록 중입니다. MIT 라이선스라 상업 프로젝트에서도 제약 없이 쓸 수 있고요.

제가 보기에 MarkItDown AI RAG 문서 변환 활용에서 실질적 가치는 "입력 포맷이 뭐든 하나의 `convert()` 호출로 Markdown을 뽑아낸다"는 단순함에 있습니다. 포맷별로 다른 라이브러리를 붙여 쓸 필요가 줄어드니 전처리 코드 자체가 짧아집니다.

 

 

어떤 파일을 변환할 수 있나요? - 지원 형식 15종 정리

 

PDF, DOCX, PPTX, XLSX, 이미지(JPG/PNG), 오디오(WAV/MP3), HTML, CSV, JSON, XML, ZIP, YouTube URL, ePub, Outlook MSG 등 15개 이상의 입력 형식을 단일 API로 처리합니다.

v0.1.5 기준으로 정리하면 이렇습니다.

카테고리	지원 형식
문서	PDF, DOCX, PPTX, XLSX, XLS, CSV
웹/데이터	HTML, JSON, XML
미디어	JPG/PNG(EXIF + OCR), WAV/MP3(메타데이터 + 전사)
아카이브	ZIP(내부 파일 순회)
기타	YouTube URL(자막 추출), ePub, Outlook MSG

v0.1.5에서 도입된 선택적 의존성(feature group) 시스템이 실용적입니다. `pip install 'markitdown[all]'`로 전체 설치하거나, `markitdown[pdf,docx,pptx]`처럼 필요한 변환기만 골라 설치하는 방식입니다. 프로덕션 환경에서 컨테이너 이미지 크기를 줄이고 싶다면 이 선택 설치가 유용합니다.

가용 feature group: `all`, `pdf`, `docx`, `pptx`, `xlsx`, `xls`, `audio-transcription`, `az-doc-intel`, `outlook`, `youtube-transcription`.

> 여기서 볼 부분은 HWP(한글) 형식입니다. 코어에서는 지원하지 않습니다. 커뮤니티의 `markitdown-hwp` 플러그인이나 별도 도구 `kordoc`를 써야 하는데, 성숙도는 아직 확인이 필요한 상태입니다.

 

설치부터 첫 변환까지 - pip install 한 줄이면 됩니다

 

Python 3.10 이상 환경에서 `pip install 'markitdown[all]'` 한 줄이면 전체 설치가 끝납니다. `markitdown sample.pdf` 명령 하나로 변환 결과를 바로 확인해볼 수 있습니다.

먼저 Python 버전을 확인합니다. MarkItDown은 Python 3.10 이상을 요구합니다.

```bash
# Python 버전 확인
python --version

# 전체 설치 (모든 변환기 포함)
pip install 'markitdown[all]'

# 또는 필요한 포맷만 선택 설치
pip install 'markitdown[pdf,docx,pptx,xlsx]'
```

설치 후 CLI로 첫 변환을 테스트합니다.

```bash
# PDF를 Markdown으로 변환 (터미널 출력)
markitdown sample.pdf

# 결과를 파일로 저장
markitdown sample.pdf -o output.md
```

한국 사용자 입장에서는 사내에 굴러다니는 PDF 보고서 하나를 넣어보는 게 가장 빠른 검증입니다. 텍스트 기반 PDF라면 몇 초 안에 결과가 나옵니다. 이때 변환된 `.md` 파일에서 원본의 제목·본문·표 구조가 어느 정도 유지되는지 직접 확인하는 과정을 꼭 거치세요. PDF마다 구조 보존 품질이 다르기 때문입니다.

 

CLI와 Python API, 각각 언제 쓰나요?

 

빠른 단건 변환이나 셸 스크립트 체이닝에는 CLI, 배치 처리나 RAG 파이프라인 통합에는 Python API가 적합합니다.

CLI 쪽은 파일 하나를 빠르게 변환하거나, `curl`·`wget`과 파이프로 엮을 때 편합니다.

```bash
# URL에서 직접 변환 (stdin 파이프)
curl https://example.com/report.pdf | markitdown -x .pdf > report.md

# 파일 타입 힌트 제공
markitdown unknown_file --mime-type application/pdf
```

Python API는 여러 파일을 순회하거나, 변환 결과를 코드 안에서 바로 다음 단계로 넘길 때 씁니다.

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("quarterly_report.pdf")
print(result.text_content) # 변환된 Markdown 텍스트
```

4줄이면 끝입니다. `DocumentConverterResult` 객체의 `text_content` 속성에 Markdown이 담기는 구조입니다.

LLM 비전 모델과 연동하면 이미지 안의 내용을 텍스트 설명으로 뽑아내는 것도 됩니다.

```python
from openai import OpenAI
from markitdown import MarkItDown

md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o")
result = md.convert("diagram.png")
print(result.text_content) # 이미지에 대한 텍스트 설명
```

다만 이 LLM 연동에는 OpenAI API 키가 필요하고 호출당 비용이 발생합니다. 기본 텍스트 변환만 쓸 때는 API 키 없이 로컬에서 동작하니 구분해두세요.

 

RAG 파이프라인에서 MarkItDown은 어떤 역할을 하나요?

 

문서 입력 → MarkItDown Markdown 변환 → H2/H3 기준 시맨틱 청킹 → 임베딩 → 벡터 DB 저장 순서에서, 첫 번째 변환 단계를 담당합니다.

Markdown이 RAG 전처리에서 강점을 갖는 이유는 구조 정보 때문입니다. H1~H6 헤딩, 목록, 표 같은 시맨틱 마커가 유지되므로 임의 토큰 수로 자르는 것보다 H2/H3 경계로 청킹했을 때 벡터 검색 정확도가 올라간다는 분석이 있습니다.

MarkItDown AI RAG 문서 변환 활용의 전형적인 흐름은 이렇습니다.

1. 입력: 사내 PDF, PPTX, XLSX 문서를 `convert()`로 Markdown 변환
2. 청킹: H2/H3 경계를 기준으로 논리적 단위 분할
3. 임베딩: OpenAI, Cohere 등 임베딩 모델로 벡터화
4. 저장: ChromaDB, Pinecone, Qdrant 등 벡터 DB에 적재
5. 검색: 사용자 질문 → 유사 벡터 검색 → LLM에 컨텍스트 전달

LangChain이나 LlamaIndex를 이미 쓰고 있다면 Document Loader 자리에 `result.text_content`를 문자열로 전달하면 됩니다. 별도 어댑터가 필요 없습니다.

실제로 확인할 부분은 PDF 변환 결과의 구조 보존 품질입니다. pdfminer 기반이라 원본에 따라 제목/본문 구분이 사라질 수 있으므로, 변환 후 청킹 전에 결과물을 한 번 훑어보는 과정을 넣는 게 안전합니다.

 

 

 

v0.1.5 플러그인 시스템과 markitdown-ocr은 어떻게 쓰나요?

 

v0.1.5부터 Python entry_points 기반 플러그인을 지원하며, `markitdown-ocr` 플러그인으로 GPT-4o나 Claude 비전 모델을 활용한 이미지 OCR이 가능합니다. Python API에서 `enable_plugins=True`로 활성화합니다.

2026년 2월에 나온 v0.1.5는 MarkItDown의 내부 구조를 상당히 바꾼 릴리스입니다.

1. 플러그인 아키텍처

`pyproject.toml`의 `entry_points`에 `markitdown.plugin` 그룹으로 등록하면 서드파티 변환기를 붙일 수 있게 됐습니다. 플러그인은 기본 비활성이므로 명시적으로 켜야 합니다.

```python
md = MarkItDown(enable_plugins=True)
```

CLI에서는 `--use-plugins` 플래그를 추가합니다.

2. markitdown-ocr 플러그인

PDF, DOCX, PPTX, XLSX 안에 포함된 이미지에서 텍스트를 뽑아주는 공식 플러그인입니다. GPT-4o, Claude 등 LLM 비전 모델을 호출하는 방식이라 API 키 설정과 호출 비용이 따릅니다.

```bash
pip install markitdown-ocr
```

3. 인메모리 변환으로 전환

v0.1.5부터 모든 변환이 메모리 안에서 처리됩니다. 임시 파일을 디스크에 쓰지 않으므로 보안과 클린업 면에서 개선됐지만, 대용량 파일(100MB 이상) 처리 시에는 프로세스 메모리 사용량을 모니터링해야 합니다.

 

대안 비교 - Docling, PyMuPDF4LLM과 어떤 상황에서 뭘 선택하나요?

 

다양한 포맷을 하나로 통합하려면 MarkItDown, PDF 레이아웃·표 추출 정밀도가 중요하면 Docling, 네이티브 PDF를 빠르게 처리하려면 PyMuPDF4LLM을 선택하세요.

MarkItDown AI RAG 문서 변환 활용을 검토할 때 가장 자주 비교되는 세 도구를 표로 정리합니다.

기준	MarkItDown	Docling (IBM)	PyMuPDF4LLM
핵심 강점	15+ 포맷 통합, 경량	PDF 레이아웃·표 정밀도	네이티브 PDF 속도
설치 크기	가벼움	HF 모델 다운로드 필요	가벼움
PDF 표 추출	기본 수준(pdfminer)	TableFormer로 우수	중간
다국어 OCR	외부 LLM 연동 필요	다국어 OCR 내장	미지원
Office 포맷	DOCX/PPTX/XLSX 지원	PDF 중심	PDF 전용
라이선스	MIT	MIT	AGPL

한국 사용자 입장에서 체크할 점이 두 가지 있습니다. PyMuPDF4LLM은 AGPL 라이선스라 상업 프로젝트에서 제약이 생길 수 있고, Docling은 Hugging Face 모델 초기 다운로드와 GPU 권장 환경이 부담될 수 있습니다.

결국 판단 기준은 "사내에 PDF만 있는가, 아니면 Office 파일도 섞여 있는가"입니다. PDF만 다룬다면 PyMuPDF4LLM이나 Docling이 구조 보존에서 낫습니다. 여러 포맷이 섞여 있다면 MarkItDown이 전처리 코드를 가장 짧게 만들어줍니다.

 

 

 

실무 도입 시뮬레이션 - 설치부터 운영, 호환 도구, 건너뛰기 조건

 

`pip install 'markitdown[all]'` 실행 후 `markitdown sample.pdf` 명령으로 3분 안에 첫 변환 결과를 확인할 수 있습니다. 이후 feature group 선택 설치로 프로덕션 의존성을 줄이는 순서로 도입합니다.

### Step 1 — 설치와 환경 확인

```bash
python --version # 3.10 이상인지 확인
pip install 'markitdown[all]'
markitdown --help # CLI 등록 확인
```

### Step 2 — 첫 테스트 (3분 검증)

사내 PDF 보고서나 PPTX 발표 자료 하나를 변환해봅니다.

```bash
markitdown company_report.pdf -o test_output.md
cat test_output.md # 제목, 본문, 표 구조 확인
```

### Step 3 — Python API 배치 변환

```python
import glob
from markitdown import MarkItDown

md = MarkItDown()
for path in glob.glob("docs/*.pdf"):
result = md.convert(path)
out = path.replace(".pdf", ".md")
with open(out, "w") as f:
f.write(result.text_content)
```

### Step 4 — 프로덕션 운영 체크리스트

• feature group 선택 설치(`markitdown[pdf,docx]`)로 의존성 줄이기
• 인메모리 변환이므로 대용량 파일(100MB+) 처리 시 메모리 모니터링
• `markitdown==0.1.5`로 버전 고정, 업데이트 전 테스트 환경에서 검증
• 외부 업로드 파일은 `convert_local()` API 사용 또는 Docker 격리
• 플러그인 필요 시 `enable_plugins=True`(Python) / `--use-plugins`(CLI) 명시

### 호환 도구

• microsoft/autogen: MarkItDown의 원래 탄생 프로젝트. 멀티 에이전트가 문서를 읽을 때 자연스러운 전처리 조합
• LangChain / LlamaIndex: `text_content`를 Document 객체로 감싸 RAG 파이프라인에 바로 투입
• ChromaDB / Qdrant: 변환된 Markdown 청크를 벡터화하여 저장하는 벡터 DB
• chrisryugj/kordoc: HWP/HWPX 한글 문서 변환 보완 도구. CLI와 MCP 서버를 지원하며, MarkItDown이 처리하지 못하는 한글 포맷을 커버

### 건너뛰기 조건

아래 상황이라면 MarkItDown AI RAG 문서 변환 활용 대신 다른 도구부터 검토하세요.

• 스캔 이미지 PDF가 주요 입력 → `markitdown-ocr`(유료 LLM API) 또는 Docling/Marker
• PDF 레이아웃·표 구조의 정밀 재현이 핵심 → Docling(DocLayNet + TableFormer)
• HWP 문서만 처리하는 환경 → `kordoc` 단독이 더 직접적
• 이미 PyMuPDF4LLM·Docling 파이프라인이 안정 운영 중 → 전환 이점 미미
• Python 3.10 미만 레거시 환경
• API 변경 리스크를 감수하기 어려운 핵심 프로덕션 → 1.0 릴리스 대기 또는 CI에 통합 테스트 포함

 

 

 

자주 묻는 질문

 

Q. 한글(HWP) 문서도 MarkItDown으로 변환할 수 있나요?
A. 코어에서는 HWP를 지원하지 않습니다. 커뮤니티의 markitdown-hwp 플러그인(Docpler 기반)이 있으나 성숙도를 별도로 확인해야 합니다. 현실적인 대안으로는 kordoc(HWP/HWPX/PDF→Markdown 변환, CLI와 MCP 서버 제공)가 있고, MarkItDown과 조합하면 한국 사내 문서 환경을 대부분 커버할 수 있습니다.

Q. 스캔된 이미지 PDF도 MarkItDown으로 변환되나요?
A. 기본 설정으로는 안 됩니다. 텍스트 레이어가 없는 이미지 PDF에서는 내용이 추출되지 않습니다. markitdown-ocr 플러그인을 설치하고 OpenAI 등 LLM API 키를 설정하면 GPT-4o 비전 모델이 이미지 안의 텍스트를 인식합니다. 이미지 한 장당 API 호출 비용이 발생하므로 대량 처리 시 비용 계산을 먼저 해보세요.

Q. v0.1.x 단계인데 프로덕션에 넣어도 괜찮나요?
A. 텍스트 변환 자체는 안정적으로 동작하지만, 마이너 버전 업데이트 시 API 시그니처가 바뀔 수 있습니다. markitdown==0.1.5처럼 버전을 고정하고, 업데이트 전에 테스트 환경에서 기존 파이프라인이 정상 동작하는지 먼저 돌려보세요. 의존성이 무거운 프로덕션일수록 버전 핀 전략이 중요합니다.

Q. MCP 서버로 Claude Desktop에서 MarkItDown을 바로 호출할 수 있나요?
A. 네, FastMCP 프레임워크 기반 MCP 서버를 지원합니다. Claude Desktop의 claude_desktop_config.json에 MCP 서버를 등록하면 대화 중 문서 변환을 직접 호출하는 방식입니다. 구체적인 설정 코드는 공식 저장소의 MCP 섹션에 예시가 있습니다.

참조 링크

 

• GitHub - microsoft/markitdown 공식 저장소 — 소스 코드, README, 지원 포맷 목록, 사용 예제, MCP 서버 안내
• markitdown - PyPI 패키지 페이지 — 설치 명령어, 버전 정보, feature group 의존성
• microsoft/markitdown Releases (v0.1.4, v0.1.5) — v0.1.5 플러그인 아키텍처 도입, 인메모리 변환, 보안 API 추가 이력
• markitdown-ocr 공식 OCR 플러그인 — LLM 비전 기반 OCR 플러그인 설치 및 설정 안내
• Improved RAG Document Processing With Markdown — Markdown 시맨틱 청킹이 RAG 벡터 검색 정확도에 미치는 영향 분석

microsoft/markitdown - PDF·Office·이미지 파일을 Markdown으로 바꾸는 문서 변환 도구 이 글은 실제 사례를 바탕으로 작성되었습니다