microsoft/markitdown

MarkItDown – LLM 파이프라인을 위한 파일-투-Markdown 변환

이것이 무엇인가 – 다양한 문서 유형(PDF, Word, PowerPoint, Excel, 이미지, 오디오, HTML, JSON, CSV, ZIP, YouTube 비디오, EPub 등)을 Markdown으로 변환하는 경량 Python 라이브러리 및 CLI입니다. 출력은 제목, 목록, 표, 링크와 같은 구조적 단서를 유지하여 대규모 언어 모델이 쉽게 처리할 수 있습니다.

왜 Markdown인가? – LLM은 Markdown으로 많이 훈련됩니다. 이 형식은 일반 텍스트이면서도 표현력이 뛰어나고 토큰 효율적이므로, 원시 파일을 Markdown으로 변환하면 다운스트림 텍스트 분석 품질이 향상됩니다.

주요 기능

• 일반적인 Office 형식을 위한 로컬 오프라인 변환기.
• 선택적 클라우드 백엔드:
  • Azure Document Intelligence – 레이아웃 인식 추출.
  • Azure Content Understanding – 다중 모달(문서, 이미지, 오디오, 비디오) 변환, 구조화된 필드 추출(YAML front-matter) 및 사용자 정의 분석기 제공.
• LLM 기반 이미지 설명 – OpenAI 호환 클라이언트(예: gpt-4o)를 연결하여 포함된 이미지에 대한 캡션을 생성할 수 있습니다.
• OCR 플러그인(markitdown-ocr)은 LLM 비전 모델을 사용하여 이미지 기반 텍스트를 추출하며 추가 바이너리가 필요 없습니다.
• 플러그인 시스템 – 타사 확장으로 새 형식을 추가할 수 있습니다. #markitdown-plugin 태그로 검색 가능합니다.
• 보안 인식 API – 좁은 변환 함수(convert_local, convert_stream, convert_response)를 통해 호출자가 I/O 범위를 제한할 수 있습니다.

설치

# 핵심 + 모든 선택적 형식 지원
pip install 'markitdown[all]'
# 또는 필요한 것만 선택(예: PDF + DOCX)
pip install 'markitdown[pdf,docx]'

개발 시 저장소를 클론하고 패키지를 편집 가능 모드로 설치합니다:

git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

명령줄 사용

# 간단한 변환, stdout → markdown
markitdown path/to/file.pdf > out.md

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

# 파이프 데이터
cat file.pdf | markitdown > out.md

--use-plugins를 추가하면 설치된 플러그인을 활성화하고, --list-plugins로 사용 가능한 항목을 볼 수 있습니다.

Python API(기본)

from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)   # 플러그인을 로드하려면 True로 설정
result = md.convert('report.xlsx')
print(result.markdown)

Azure Document Intelligence 예시:

md = MarkItDown(docintel_endpoint='https://<resource>.cognitiveservices.azure.com/')
print(md.convert('file.pdf').markdown)

Azure Content Understanding 및 사용자 정의 분석기:

md = MarkItDown(
    cu_endpoint='https://<cu>.cognitiveservices.azure.com/',
    cu_analyzer_id='my-invoice-analyzer'
)
print(md.convert('invoice.pdf').markdown)   # YAML front-matter 포함

LLM 기반 이미지 설명:

from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model='gpt-4o')
print(md.convert('photo.jpg').markdown)

도구 확장

• 타사 플러그인 설치(pip install markitdown-ocr 등).
• packages/markitdown-sample-plugin의 샘플을 따라 자신만의 플러그인을 만들고 저장소에 #markitdown-plugin 태그를 지정합니다.
• 설치할 선택적 종속성을 제어하여 환경을 가볍게 유지합니다.

보안 고려 사항 MarkItDown은 호출 프로세스와 동일한 파일 시스템 및 네트워크 권한으로 실행됩니다. 사용자는 신뢰할 수 없는 입력을 정화하고, 경로/URL을 제한하며, 가장 좁은 변환 함수(convert_local, convert_stream 등)를 사용하여 노출을 제한해야 합니다.

테스트 실행

cd packages/markitdown
pip install hatch
hatch shell
hatch test

또는 제공된 DevContainer를 사용합니다.

라이선스 및 기여 MIT 라이선스의 오픈소스(PyPI 페이지 기준). 기여는 환영하지만 라이브러리 범위 내에 있어야 합니다. 웹 서비스, GUI, 호스팅 API는 허용되지 않습니다. PR에는 Contributor License Agreement가 필요합니다.