MarkItDown : MS 의 문서 파일 변환 도구 (to Markdown)

MarkItDown은 Microsoft에서 개발한 오픈소스 Python 라이브러리 및 CLI(커맨드 라인 인터페이스) 도구로, 다양한 파일 형식을 Markdown 형식으로 변환하는 데 사용됩니다.

이 도구는 PDF, Word, Excel, PowerPoint, HTML, 이미지, 오디오 등 다양한 파일 형식을 처리하여 텍스트 분석, LLM 학습, 또는 인덱싱과 같은 작업에 적합한 Markdown 출력을 생성합니다. 2024년 말 공개 이후 단 2주 만에 GitHub에서 25,000개 이상의 스타를 획득하며 큰 인기를 끌었습니다. MIT 라이선스 하에 배포되며, 확장 가능한 플러그인 아키텍처를 지원합니다. 게다가 MIT 라이선스를 따르고 있어 자유로운 사용, 수정이 가능합니다. 

 

 

주요 특징

 

MarkItDown은 다양한 파일 형식을 처리하고, 확장성과 사용 편의성을 제공하는 여러 기능을 갖추고 있습니다. 주요 특징은 다음과 같습니다:

• 다양한 파일 형식 지원
  • Office 문서: Word (.docx, .doc), Excel (.xlsx), PowerPoint (.pptx)
  • PDF, HTML, 이미지, 오디오 파일
  • YouTube 비디오 자막 추출(YouTube Transcript API 사용)
  • 다중 모달 데이터 처리: OCR(광학 문자 인식) 및 음성 인식(SpeechRecognition 라이브러리)을 활용하여 이미지와 오디오에서 텍스트 추출
• 확장 가능한 플러그인 아키텍처
  • 서드파티 플러그인 지원으로 새로운 파일 형식 변환기 추가 가능
  • 플러그인은 기본적으로 비활성화 상태이며, GitHub에서 #markitdown-plugin 해시태그로 검색 가능
  • 샘플 플러그인(markitdown-sample-plugin)을 참고하여 개발 가능
• 모듈화된 의존성
  • 선택적 기능 그룹(feature-groups)으로 필요한 변환기만 설치 가능
  • 전체 의존성 설치: pip install 'markitdown[all]'
• 메모리 내 처리
  • 임시 파일 생성 없이 스트림 기반으로 파일 처리, 성능 최적화
  • convert_stream()은 바이너리 파일 객체(io.BytesIO 등)만 지원(텍스트 객체는 더 이상 지원하지 않음)
• LLM 통합 가능
  • 이미지 처리 시 LLM(예: GPT-4o)을 활용하여 상세 캡션 생성 가능
  • 예: 바 차트나 그래프를 Markdown 테이블로 변환하는 기능 제안됨
• Docker 지원
  • Docker 이미지를 통해 실행 가능, 로컬 파일 접근을 위한 디렉토리 마운트 지원
  • Claude Desktop과 통합 가능한 MCP 서버 제공
• 한계점:
  • OCR 미지원 PDF는 처리 불가
  • PDF에서 추출된 텍스트는 서식(예: 제목과 본문 구분) 유지 불가
  • 일부 복잡한 PDF 처리에서 성능 저하 가능

 

설치 방식

다음 명령어를 통해 MarkItDown을 설치할 수 있습니다.​

# pip 이용한 설치. 참고로 all은 모든 선택적 의존성을 포함
pip install 'markitdown[all]'

# 소스에서 직접 설치
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

 

Docker를 사용하는 경우,

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

 

플러그인 관리

설치된 플러그인 목록 확인은 다음 커맨드로 합니다. 

markitdown --list-plugins

 

사용 예시

 

커맨드라인 인터페이스(CLI) 사용

다음 명령어를 통해 PDF 파일을 Markdown으로 변환할 수 있습니다.​

# PDF 파일을 Markdown으로 변환하는 예시
markitdown path-to-file.pdf > document.md

# 출력 파일명 지정
markitdown path-to-file.pdf -o document.md

# pipe를 이용한 입력 전달 지원하는 예
cat path-to-file.pdf | markitdown

 

Python 코드로 사용

 

from markitdown import MarkItDown

# MarkItDown 인스턴스 생성
md = MarkItDown()

# 파일 변환
result = md.convert("test.xlsx")  # Excel 파일 변환
print(result.text_content)  # 변환된 텍스트 출력
print(result.markdown)  # Markdown 형식 출력

# URI 변환
result = md.convert_uri("file:///path/to/file.txt")
print(result.markdown)

또는 
result = md.convert_uri("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==")
print(result.markdown)

# LLM 통합 (예: 이미지 캡션 생성)
from openai import OpenAI
client = OpenAI(api_key="your-api-key")
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("image.jpg")
print(result.markdown)

 

 

 

활용 사례

• 문서 분석 파이프라인: LLM을 활용한 문서 요약, 내용 추출, 텍스트 분석 등에 활용
• 교육 자료 변환: PDF나 PowerPoint 형식의 교육 자료를 Markdown 형식으로 변환하여 학습 관리 시스템(LMS)과의 통합에 사용
• 데이터 전처리: CSV, JSON, XML 등의 데이터를 Markdown 형식으로 변환하여 데이터 분석 및 시각화 작업에 활용

 

경쟁 솔루션과의 비교 (vs Docling)

MarkItDown의 경쟁 제품으로는 IBM이 공개한 Docling, Marker 등이 있습니다. 이 가운데 Docling과 비교하면 다음과 같습니다. Docling은 주로 PDF 처리에 특화되어 있다는 것을 알 수 있습니다. 

항목	MarkItDown (Microsoft)	Docling (IBM)
목적	다양한 파일 형식을 Markdown으로 변환하여 LLM 학습 및 텍스트 분석에 활용	PDF 및 기타 문서 형식을 Markdown/JSON으로 변환, LLM 학습과 RAG에 최적화
라이선스	MIT	MIT
공개 시기	2024년 말	2024년 가을
GitHub 인기	2주 만에 25,000+ 스타 획득	1개월 만에 10,000+ 스타 획득
주요 초점	다중 형식 지원, LLM 통합(예: GPT-4o), 간단한 설치 및 사용	PDF 중심의 고정밀 구조적 변환, AI 기반 레이아웃 분석 및 테이블 인식
호스팅	로컬 실행, 클라우드 API 호스팅 가능 (Leapcell, Zapier/n8n 통합)	로컬 실행, LlamaIndex/LangChain 등 AI 프레임워크와 통합
텍스트 추출 품질	텍스트 중심 추출, 서식 손실 가능, 이미지/오디오에서 텍스트 추출 가능	구조적 텍스트 추출, 레이아웃/테이블/메타데이터 유지, OCR 스캔한 PDF 처리 가능
구조적 데이터 유지	제한적 (테이블, 제목 등 기본 구조만 반영)	뛰어남(레이아웃, 읽기 순서, 테이블, 그림 등 상세 구조 유지)
멀티모달 지원	이미지(OCR, LLM 캡션), 오디오(음성인식), Youtube 자막 추출	이미지(OCR), 제한된 멀티모달 지원 (주로 PDF 및 Office 문서 중심)
RAG 워크플로우	Markdown 출력이 LLM 입력으로 적합, 구조적 데이터 부족으로 RAG에서 추가 처리 필요	JSON/Markdown 출력이 RAG에 최적화, LlamaIndex/LangChain 통합으로 즉시 사용 가능
대규모 처리	스트림 처리로 메모리 효율적, ZIP 파일 배치 처리 가능	배치처리 모드 지원, 대규모 PDF 처리 지원
데이터셋 생성	다양한 형식에서 텍스트 추출, 간단한 데이터셋 생성에 적합	구조화된 데이터셋 생성에 유리,  테이블/메타데이터 활용한 지식 베이스 구축에 유리
한계	복잡한 PDF 레이아웃 처리 미흡, 외부 API(OpenAI, Azure 등)에 의존	PDF 및 Office 문서에 촛점, 오디오/Youtube 등 멀티모달 지원 부족

 

 

IBM의 Docling 외에 Marker 까지 포함해서 비교를 하신 분이 있더군요. (Fahd Mirza Youtube, 링크) 해당 영상에서는 다음과 같이 비교하고 있는데 Docling의 품질이나 변환 속도가 MarkItDown보다 더 나은 것으로 평가하고 있습니다. 다만, 이 비교는 실제 업무 시나리오에 따라 달라질 수 있습니다. 

그림 : 세 변환 도구의 성능 비교 (출처: Fahd Mirza Youtube)

---

 

이번에 소개한 MarkItDown은 기존의 문서들을 LLM 학습을 위해 활용할 수 있도록 Markdown이라는 구조화된 텍스트 데이터로 변환하는데 특화된 도구입니다. 마이크로소프트가 만들었고, Office 파일 포맷 전부와 PDF, 이미지, 오디오, HTML 등 다양한 문서를 지원하고 더군다나 MIT 라이선스이므로 기업에서의 활용도는 아주 폭넓을 것 같습니다. 이를 잘 이용하면 꼭 LLM을 위한 것이 아니더라도 다양한 기업용 어플 개발이 가능하다는 얘기가 될테니까요. 

 

MarkItDown은 다양한 파일 형식을 처리해야 할 때, 그리고 LLM 등을 활용해 이미지 캡션이나 데이터의 가공이 필요한 경우에 적합합니다. 반면 Docling은 논문이나 연구보고서, 기술 매뉴얼처럼 레이아웃이 복잡하고 테이블이 많은 문서들에 적합하다고 할 수 있습니다. 이 두 도구의 장점을 잘 살려서 업무에서 함께 혼합해서 사용할 수도 있을 겁니다.