MarkItDown
- 추천0
- GitHub 별196K
- 문서라이선스MIT
PDF · 워드 · 엑셀 · 파워포인트 · 이미지 · 오디오 등을 LLM이 읽기 좋은 마크다운으로 바꿔 주는 가벼운 파이썬 도구. MIT
요약
PDF · 워드 · 엑셀 · 파워포인트 · 이미지 · 오디오 등을 LLM이 읽기 좋은 마크다운으로 바꿔 주는 가벼운 파이썬 도구. MIT
설명
MarkItDown
💡 중요 MarkItDown은 현재 프로세스의 권한으로 입출력을 합니다.
open()이나requests.get()처럼, 프로세스가 접근할 수 있는 자원에 접근합니다. 신뢰할 수 없는 환경에서는 입력을 정제하고, 용도에 맞는 가장 좁은convert_*함수(예:convert_stream(),convert_local())를 호출하세요. 더 자세한 내용은 문서의 보안 고려 사항 절을 보세요.
MarkItDown은 다양한 파일을 LLM과 관련 텍스트 분석 파이프라인에서 쓸 수 있도록 마크다운으로 바꿔 주는 가벼운 파이썬 도구입니다. 이 점에서 textract와 가장 비슷하지만, 제목, 목록, 표, 링크 같은 중요한 문서 구조와 내용을 마크다운으로 보존하는 데 초점을 둡니다. 결과물이 대체로 보기 좋고 사람이 읽기에도 괜찮지만, 텍스트 분석 도구가 쓰도록 만든 것이라 사람이 읽을 고품질 문서 변환에는 최선이 아닐 수 있습니다.
MarkItDown은 현재 다음 형식에서 변환할 수 있습니다.
- 파워포인트
- 워드
- 엑셀
- 이미지(EXIF 메타데이터와 캡션)
- 오디오(EXIF 메타데이터와 음성 받아쓰기)
- HTML
- 텍스트 기반 형식(CSV, JSON, XML)
- ZIP 파일(안의 내용을 하나씩 처리)
- YouTube 주소
- EPub
- ... 그 밖에도 더 있습니다!
참고: 이미지 캡션과 음성 받아쓰기는 웹에서 운영되는 서비스에 기댑니다.
왜 마크다운인가요?
마크다운은 순수 텍스트에 매우 가까워 표시나 서식이 최소한이지만, 중요한 문서 구조는 그대로 나타낼 수 있습니다. OpenAI의 GPT-4o 같은 주요 LLM은 마크다운을 자연스럽게 "말하고", 시키지 않아도 답변에 마크다운을 섞어 쓰는 일이 많습니다. 방대한 마크다운 서식 텍스트로 학습했고 이를 잘 이해한다는 뜻입니다. 덤으로 마크다운 규칙은 토큰도 매우 적게 씁니다.
준비물
MarkItDown은 Python 3.10 ~ 3.14가 필요합니다. 의존성 충돌을 피하려면 가상환경을 쓰는 것을 권장합니다.
표준 파이썬 설치라면 다음 명령으로 가상환경을 만들고 켤 수 있습니다.
python -m venv .venv
source .venv/bin/activate
uv를 쓴다면 이렇게 가상환경을 만들 수 있습니다.
uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment
Anaconda를 쓴다면 이렇게 가상환경을 만들 수 있습니다.
conda create -n markitdown python=3.12
conda activate markitdown
설치
MarkItDown을 설치하려면 pip를 쓰세요: pip install 'markitdown[all]'. 소스에서 설치할 수도 있습니다.
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
사용법
명령줄
markitdown path-to-file.pdf > document.md
또는 -o로 출력 파일을 지정하세요.
markitdown path-to-file.pdf -o document.md
내용을 파이프로 넘길 수도 있습니다.
cat path-to-file.pdf | markitdown
선택 의존성
MarkItDown에는 여러 파일 형식을 켜는 선택 의존성이 있습니다. 이 문서 앞에서는 [all] 옵션으로 선택 의존성을 모두 설치했습니다. 하지만 더 세밀하게 조절하려고 하나씩 설치할 수도 있습니다. 예를 들면 다음과 같습니다.
pip install 'markitdown[pdf, docx, pptx]'
이 명령은 PDF, DOCX, PPTX 파일용 의존성만 설치합니다.
지금은 다음 선택 의존성을 쓸 수 있습니다.
[all]모든 선택 의존성을 설치합니다[pptx]파워포인트 파일용 의존성을 설치합니다[docx]워드 파일용 의존성을 설치합니다[xlsx]엑셀 파일용 의존성을 설치합니다[xls]옛 엑셀 파일용 의존성을 설치합니다[pdf]PDF 파일용 의존성을 설치합니다[outlook]아웃룩 메시지용 의존성을 설치합니다[az-doc-intel]Azure Document Intelligence용 의존성을 설치합니다[az-content-understanding]Azure Content Understanding용 의존성을 설치합니다[audio-transcription]wav · mp3 파일의 음성 받아쓰기용 의존성을 설치합니다[youtube-transcription]YouTube 영상 자막을 가져오는 의존성을 설치합니다
플러그인
MarkItDown은 서드파티 플러그인도 지원합니다. 플러그인은 기본으로 꺼져 있습니다. 설치된 플러그인을 보려면 이렇게 하세요.
markitdown --list-plugins
플러그인을 켜려면 이렇게 하세요.
markitdown --use-plugins path-to-file.pdf
쓸 수 있는 플러그인을 찾으려면 GitHub에서 #markitdown-plugin 해시태그를 검색하세요. 플러그인을 개발하려면 packages/markitdown-sample-plugin을 보세요.
markitdown-ocr 플러그인
markitdown-ocr 플러그인은 PDF, DOCX, PPTX, XLSX 변환기에 OCR 지원을 더해, LLM 비전으로 문서에 박힌 이미지 속 글자를 뽑아냅니다. MarkItDown이 이미지 설명에 이미 쓰는 llm_client / llm_model 방식 그대로입니다. 새 머신러닝 라이브러리도, 바이너리 의존성도 필요 없습니다.
설치:
pip install markitdown-ocr
pip install openai # or any OpenAI-compatible client
사용:
이미지 설명에 쓰던 것과 같은 llm_client와 llm_model을 넘기세요.
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.markdown)
llm_client를 주지 않아도 플러그인은 불러오지만 OCR은 조용히 건너뛰고 기본 내장 변환기를 대신 씁니다.
자세한 문서는 packages/markitdown-ocr/README.md를 보세요.
Azure Content Understanding
Azure Content Understanding은 구조화된 필드 추출(YAML 머리말), 멀티모달 지원(문서, 이미지, 오디오, 비디오), 설정할 수 있는 분석기로 더 높은 품질의 변환을 제공합니다.
설치: pip install 'markitdown[az-content-understanding]'
Content Understanding을 쓰면 좋은 때
Content Understanding은 내장 변환기나 Document Intelligence 변환기가 주는 것 이상이 필요할 때 알맞습니다.
- 오디오 · 비디오 파일 — 비디오는 CU뿐이고, 오디오도 CU가 더 품질 높은 클라우드 선택지입니다. 내장 변환기는 비디오를 지원하지 않고 오디오는 기본 받아쓰기만 합니다.
- 구조화된 필드 추출 — 미리 만들어진 분석기나 직접 만든 분석기로 도메인별 필드(송장 금액, 영수증 날짜, 계약 조항)를 뽑아 YAML 머리말로 내보냅니다. 내장 변환기와 Document Intelligence 연동은 필드를 내놓지 않습니다.
- 더 높은 품질의 문서 추출 — 스캔한 PDF, 복잡한 표, 여러 쪽 문서에 대한 클라우드 레이아웃 분석과 OCR.
- 모든 형식을 하나의 API로 —
cu_endpoint하나로 문서, 이미지, 오디오, 비디오를 모두 처리하며 분석기를 자동으로 고릅니다.
| 기능 | 내장 변환기 | Azure Document Intelligence | Azure Content Understanding |
|---|---|---|---|
| 문서 변환 | 오프라인, 형식별 추출 | 클라우드 레이아웃 추출 | 클라우드 멀티모달 추출 |
| 구조화된 필드 | 지원 안 함 | 모델 또는 질의 필드에서 만든 YAML 머리말 | 분석기 필드에서 만든 YAML 머리말 |
| 사용자 분석기/모델 | 지원 안 함 | docintel_model_id로 지원 | cu_analyzer_id로 지원 |
| 오디오와 비디오 | 기본 오디오만, 비디오 없음 | 지원 안 함 | 오디오 · 비디오 분석기 |
| 비용 | 로컬 연산만 | 유료 Azure API 호출 | 유료 Azure API 호출 |
CLI:
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
엔드포인트를 환경 변수로 한 번만 정해 두면, 호출할 때는 --use-cu만 쓰면 됩니다.
export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu
파이썬 API:
from markitdown import MarkItDown
# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf") # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4") # video → prebuilt-videoSearch
result = md.convert("call.wav") # audio → prebuilt-audioSearch
print(result.markdown)
사용자 분석기로(도메인별 필드 추출):
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
# VendorName: CONTOSO LTD.
# InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...
cu_analyzer_id를 정하면, 변환기는 분석기의 형식에 맞는 파일 종류로 범위를 자동으로 좁힙니다. 맞지 않는 종류(예: 문서 분석기에 오디오 파일)는 기본으로 미리 만들어진 분석기로 자동 연결됩니다.
비용 참고: CU로 연결되는 형식은 convert()를 부를 때마다 유료 Azure API 호출입니다. CU로 보낼 형식을 제한하려면 cu_file_types를 쓰세요.
from markitdown.converters import ContentUnderstandingFileType
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_file_types=[ContentUnderstandingFileType.PDF], # only PDFs use CU
)
Azure Content Understanding에 대한 더 많은 정보는 여기에서 볼 수 있습니다.
Azure Document Intelligence
변환에 Microsoft Document Intelligence를 쓰려면 이렇게 하세요.
export AZURE_API_KEY="<document_intelligence_api_key>"
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
엔드포인트를 환경 변수로 한 번만 정해 두면, 호출할 때는 -d만 쓰면 됩니다.
export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown path-to-file.pdf -o document.md -d
AZURE_API_KEY가 정해져 있지 않으면 MarkItDown은 DefaultAzureCredential을 씁니다.
CLI에서 모델을 고르고, 분석 부가 기능을 설정하고, 필드를 요청할 수 있습니다.
markitdown document.pdf --use-docintel \
--endpoint "<document_intelligence_endpoint>" \
--docintel-model-id prebuilt-layout \
--docintel-features "ocrHighResolution,styleFont" \
--docintel-query-fields "Title,Author"
분석 부가 기능은 기본으로 하나도 켜져 있지 않습니다. --docintel-features로 직접 켜거나, 부가 기능을 쓰지 않겠다고 분명히 하려면 --docintel-features none을 쓰세요. 분석 부가 기능과 질의 필드는 PDF와 이미지처럼 OCR을 지원하는 입력에만 적용됩니다.
쓸 수 있는 기능 값은 barcodes, formulas, keyValuePairs, languages, ocrHighResolution, styleFont입니다. formulas, ocrHighResolution, styleFont 기능은 추가 요금이 붙고, 다른 부가 기능과 요금 체계가 다른 queryFields 부가 기능도 마찬가지입니다. 자세한 내용은 Document Intelligence 부가 기능 문서와 가격을 보세요.
Azure Document Intelligence 리소스를 만드는 방법은 여기에서 볼 수 있습니다.
파이썬 API
파이썬의 기본 사용법입니다.
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)
API 키로 파이썬에서 Document Intelligence 변환을 하는 방법입니다.
from azure.core.credentials import AzureKeyCredential
from markitdown import MarkItDown
md = MarkItDown(
docintel_endpoint="<document_intelligence_endpoint>",
docintel_credential=AzureKeyCredential("<document_intelligence_api_key>"),
)
result = md.convert("test.pdf")
print(result.markdown)
docintel_credential을 생략하면 AZURE_API_KEY가 정해져 있을 때는 그것을, 아니면 DefaultAzureCredential을 씁니다.
모델, 분석 부가 기능, 구조화된 질의 필드를 설정합니다.
from azure.ai.documentintelligence.models import DocumentAnalysisFeature
from markitdown import MarkItDown
md = MarkItDown(
docintel_endpoint="<document_intelligence_endpoint>",
docintel_model_id="prebuilt-layout",
docintel_features=[
DocumentAnalysisFeature.OCR_HIGH_RESOLUTION,
DocumentAnalysisFeature.STYLE_FONT,
],
docintel_query_fields=["Title", "Author"],
)
result = md.convert("test.pdf")
print(result.markdown)
docintel_features를 생략하거나 docintel_features=[]로 두면 분석 부가 기능을 요청하지 않습니다. 질의 필드를 주면 MarkItDown이 필요한 queryFields 부가 기능을 자동으로 켭니다. 구조화된 필드를 돌려주는 모델은 그 필드를 YAML 머리말로 마크다운 맨 앞에 붙입니다. 문서가 하나면 최상위 fields 매핑을 쓰고, 서비스가 문서를 여러 개 돌려주면 머리말에 서비스가 돌려준 순서의 documents 목록이 들어가며 문서마다 fields 매핑이 따로 있습니다. 추출한 필드가 없는 문서는 그 목록에 빈 매핑으로 남고, 모든 문서의 필드가 비어 있으면 머리말을 내보내지 않습니다. 선택 그룹은 선택된 값의 목록으로 나타냅니다.
이미지 설명에 대규모 언어 모델을 쓰려면(지금은 pptx와 이미지 파일만), llm_client와 llm_model을 주세요.
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI(max_retries=5)
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.markdown)
max_retries는 다시 시도해 볼 만한 오류에 대한 OpenAI 클라이언트의 자동 재시도 횟수입니다(기본값은 2). 5로 두면 백오프를 두고 최대 여섯 번까지 시도합니다. OpenAI SDK 재시도 문서를 보세요.
한 번이라도 성공하면 이미지 변환은 정상적으로 이어집니다. 클라이언트가 재시도를 다 쓰고도 오류를 내거나 재시도할 수 없는 오류를 만나면, MarkItDown은 적용할 수 있는 다른 변환기를 시도하고, 모두 실패했을 때만 FileConversionException을 던집니다.
Docker
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
기여하기
큰 작업을 시작하기 전에, 이 저장소에서 무엇이 범위 안이고 밖인지 설명하는 무엇을 기여할까를 읽어 주세요.
이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 기여자 라이선스 계약(CLA)에 동의해야 합니다. 기여한 내용을 쓸 권리가 내게 있고 그 권리를 실제로 우리에게 준다는 선언입니다. 자세한 내용은 https://cla.opensource.microsoft.com 을 보세요.
풀 리퀘스트를 내면 CLA 봇이 CLA를 내야 하는지 자동으로 판단하고 PR에 알맞게 표시합니다(상태 확인, 댓글). 봇의 안내를 따르기만 하면 됩니다. CLA를 쓰는 모든 저장소를 통틀어 한 번만 하면 됩니다.
이 프로젝트는 Microsoft 오픈소스 행동 강령을 채택했습니다. 더 자세한 내용은 행동 강령 FAQ를 보거나, 다른 질문이나 의견이 있으면 opencode@microsoft.com으로 연락하세요.
무엇을 기여할까
MarkItDown은 LLM과 관련 텍스트 분석 파이프라인에서 쓰려고 파일을 마크다운으로 바꾸는 파이썬 도구입니다. 이 저장소는 다른 시스템에 넣어 쓸 수 있는 파이썬 라이브러리를 제공하려는 것이지, 그 위에 만든 최종 사용자 애플리케이션이 아닙니다.
범위 안
- 기존 변환기의 충실도 개선(새 형식은 아껴서 추가합니다. 특히 새 의존성이 생길 때는 더 그렇습니다. 대부분은 서드파티 플러그인으로 더 잘 지원할 수 있습니다.)
- 버그 수정, 성능 개선, 보안 수정
markitdown명령줄 인터페이스markitdown-mcp패키지- 테스트, 문서, 개발자 도구
범위 밖
애플리케이션 · 서비스 · 서버는 더 받을 수 없습니다. 다음이 여기에 들어갑니다.
- 웹 서버, REST나 HTTP API, 호스팅하는 변환 서비스
- 웹 프런트엔드와 브라우저 기반 사용자 인터페이스
- 데스크톱 · 모바일 애플리케이션(PyQt, PySide, Tkinter, Electron, Flutter 등)
이런 프로젝트는 정말 유용하고, 돌려보내기보다 잘 자라는 모습을 보고 싶습니다. MarkItDown용 웹 서비스, API, 그래픽 애플리케이션을 제공하고 싶다면, PyPI의 markitdown에 의존하는 별도 패키지나 프로젝트로 유지해 주세요.
이 저장소를 바꾸지 않고 MarkItDown 확장하기
MarkItDown은 서드파티 플러그인을 지원하므로, 새 형식 지원을 이 저장소와 별개로 배포하고 설치할 수 있습니다.
markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf
시작하려면 packages/markitdown-sample-plugin을 보고, 다른 사람이 찾을 수 있도록 내 저장소에 #markitdown-plugin 태그를 다세요.
기여하는 방법
이슈를 살펴보거나 PR 검토를 도와주면 됩니다. 커뮤니티 기여를 쉽게 하려고 일부 이슈에는 'open for contribution', 일부 PR에는 'open for reviewing' 라벨을 달아 두었습니다. 이 라벨은 제안일 뿐이고, 위에 설명한 범위 안의 기여는 모두 환영합니다.
| 전체 | 커뮤니티의 도움이 특히 필요한 것 | |
|---|---|---|
| 이슈 | 모든 이슈 | 기여를 기다리는 이슈 |
| PR | 모든 PR | 검토를 기다리는 PR |
테스트와 점검 실행하기
-
MarkItDown 패키지로 이동합니다.
cd packages/markitdown -
환경에
hatch를 설치하고 테스트를 실행합니다.pip install hatch # Other ways of installing hatch: https://hatch.pypa.io/dev/install/ hatch shell hatch test(다른 방법) 의존성이 모두 설치된 Devcontainer를 쓰세요.
# Reopen the project in Devcontainer and run: hatch test -
PR을 내기 전에 pre-commit 점검을 실행합니다:
pre-commit run --all-files
보안 고려 사항
MarkItDown은 현재 프로세스의 권한으로 입출력을 합니다. open()이나 requests.get()처럼, 프로세스가 접근할 수 있는 자원에 접근합니다.
입력을 정제하세요: 신뢰할 수 없는 입력을 MarkItDown에 그대로 넘기지 마세요. 입력의 일부라도 신뢰할 수 없는 사용자나 시스템이 정할 수 있다면(호스팅 · 서버 쪽 애플리케이션 등), MarkItDown을 부르기 전에 검증하고 제한해야 합니다. 환경에 따라 파일 경로를 제한하고, URI 스킴과 네트워크 목적지를 제한하고, 사설 · 루프백 · 링크 로컬 · 메타데이터 서비스 주소로의 접근을 막는 일이 여기에 들어갈 수 있습니다.
필요한 변환 메서드만 호출하세요: 용도에 맞는 가장 좁은 변환 API를 쓰세요. MarkItDown의 convert() 메서드는 일부러 너그럽게 만들어서 로컬 파일, 원격 URI, 바이트 스트림을 모두 처리합니다. 애플리케이션이 로컬 파일만 읽으면 된다면 convert_local()을 부르세요. URI를 가져오는 과정을 더 통제하고 싶다면 requests.get()을 직접 부르고 그 응답 객체를 convert_response()에 넘기세요. 가장 확실하게 통제하려면 변환할 입력의 스트림을 열고 convert_stream()을 부르세요.
또한 이미지 캡션, 음성 받아쓰기, Azure Document Intelligence, Azure Content Understanding은 웹에서 운영되는 서비스에 기대어 동작합니다. 로컬에서만 쓰려면 필요하고 쓰고 싶은 선택 의존성만 설치하세요.
상표
이 프로젝트에는 프로젝트, 제품, 서비스의 상표나 로고가 들어 있을 수 있습니다. Microsoft 상표나 로고를 승인받아 쓰는 일은 Microsoft 상표 및 브랜드 지침을 따라야 합니다. 이 프로젝트를 고친 버전에서 Microsoft 상표나 로고를 쓸 때는 혼동을 일으키거나 Microsoft가 후원한다는 인상을 주어서는 안 됩니다. 제3자의 상표나 로고를 쓰는 일은 그 제3자의 정책을 따라야 합니다.
평점
- 5점
- 0
- 4점
- 0
- 3점
- 0
- 2점
- 0
- 1점
- 0