microsoft/markitdown

MarkItDown

[!IMPORTANT]

MarkItDown은 현재 프로세스의 권한으로 I/O를 수행합니다. open() 또는 requests.get()과 마찬가지로 프로세스 자체가 액세스할 수 있는 리소스에 액세스합니다. 신뢰할 수 없는 환경에서는 입력을 삭제하고, 사용 사례에 필요한 가장 좁은 convert* 함수(예: convertstream() 또는 convert_local())를 호출하세요. 자세한 내용은 문서의 보안 고려 사항 섹션을 참조하세요.

MarkItDown은 다양한 파일을 Markdown으로 변환하여 LLM 및 관련 텍스트 분석 파이프라인에서 사용할 수 있도록 하는 경량 Python 유틸리티입니다. 이러한 점에서 textract와 가장 유사하지만, 중요한 문서 구조와 콘텐츠(제목, 목록, 표, 링크 등)를 Markdown으로 보존하는 데 중점을 둡니다. 출력은 종종 합리적으로 보기 좋고 사람이 읽기 편하지만, 텍스트 분석 도구에서 사용하기 위한 것이며 사람이 읽기 위한 고충실도 문서 변환에는 최선의 선택이 아닐 수 있습니다.

MarkItDown은 현재 다음 형식의 변환을 지원합니다:

• PDF
• PowerPoint
• Word
• Excel
• 이미지 (EXIF 메타데이터 및 OCR)
• 오디오 (EXIF 메타데이터 및 음성 전사)
• HTML
• 텍스트 기반 형식 (CSV, JSON, XML)
• ZIP 파일 (내용 반복)
• YouTube URL
• EPub

-... 그리고 더 많은 형식!

왜 Markdown인가?

Markdown은 일반 텍스트에 매우 가깝고 최소한의 마크업 또는 서식만 있지만 중요한 문서 구조를 표현하는 방법을 제공합니다. OpenAI의 GPT-4o와 같은 주류 LLM은 기본적으로 Markdown을 "말하며", 종종 프롬프트 없이도 응답에 Markdown을 통합합니다. 이는 방대한 양의 Markdown 형식 텍스트로 훈련되었으며 이를 잘 이해하고 있음을 시사합니다. 부수적인 이점으로 Markdown 규칙은 토큰 효율성도 매우 높습니다.

전제 조건

MarkItDown은 Python 3.10 이상이 필요합니다. 종속성 충돌을 피하기 위해 가상 환경을 사용하는 것이 좋습니다.

표준 Python 설치를 사용하면 다음 명령을 사용하여 가상 환경을 만들고 활성화할 수 있습니다:

python -m venv.venv
source.venv/bin/activate

uv를 사용하는 경우 다음을 사용하여 가상 환경을 만들 수 있습니다:

uv venv --python=3.12.venv
source.venv/bin/activate
# 참고: 이 가상 환경에 패키지를 설치하려면 'pip install' 대신 'uv pip install'을 사용하세요.

Anaconda를 사용하는 경우 다음을 사용하여 가상 환경을 만들 수 있습니다:

conda create -n markitdown python=3.12
conda activate markitdown

설치

MarkItDown을 설치하려면 pip를 사용하세요: pip install 'markitdown[all]'. 또는 소스에서 설치할 수 있습니다:

git clone [email protected]: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] PowerPoint 파일 종속성 설치
• [docx] Word 파일 종속성 설치
• [xlsx] Excel 파일 종속성 설치
• [xls] 이전 Excel 파일 종속성 설치
• [pdf] PDF 파일 종속성 설치
• [outlook] 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 Vision(이미지 설명에 MarkItDown이 이미 사용하는 것과 동일한 llmclient / llmmodel 패턴)을 사용하여 포함된 이미지에서 텍스트를 추출합니다. 새로운 ML 라이브러리나 바이너리 종속성이 필요하지 않습니다.

설치:

pip install markitdown-ocr
pip install openai  # 또는 OpenAI 호환 클라이언트

사용법:

이미지 설명에 사용할 것과 동일한 llmclient 및 llmmodel을 전달합니다:

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.text_content)

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는 비디오에 유일한 옵션이며 오디오에 더 높은 품질의 클라우드 옵션입니다. 내장 변환기는 비디오를 지원하지 않으며 기본 오디오 전사만 제공합니다.
• 구조화된 필드 추출 — 미리 빌드된 또는 사용자 지정 분석기는 도메인별 필드(송장 금액, 영수증 날짜, 계약 조항)를 추출하여 YAML 머리말로 직렬화합니다. 내장 변환기나 Doc Intel 통합은 필드를 노출하지 않습니다.
• 더 높은 품질의 문서 추출 — 스캔된 PDF, 복잡한 표 및 여러 페이지 문서에 대한 클라우드 기반 레이아웃 분석 및 OCR.
• 모든 양식에 대한 단일 API — 하나의 cu_endpoint가 자동 분석기 라우팅으로 문서, 이미지, 오디오 및 비디오를 처리합니다.

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

Python API:

from markitdown import MarkItDown

# 제로 구성 — 파일 유형별로 분석기 자동 선택
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # 문서 → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # 비디오 → prebuilt-videoSearch
result = md.convert("call.wav")     # 오디오 → 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)
# 출력에는 추출된 필드가 포함된 YAML 머리말이 포함됩니다:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
#...

cuanalyzerid가 설정되면 변환기는 분석기의 모드에 따라 호환되는 파일 형식으로 자동 범위를 지정합니다. 호환되지 않는 형식(예: 문서 분석기가 있는 오디오 파일)은 기본 미리 빌드된 분석기로 자동 라우팅됩니다.

비용 참고: CU 라우팅 형식에 대한 각 convert() 호출은 청구 가능한 Azure API 호출입니다. cufiletypes를 사용하여 CU로 라우팅할 형식을 제한하세요:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # PDF만 CU 사용
)

Azure Content Understanding에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

Azure Document Intelligence

변환에 Microsoft Document Intelligence를 사용하려면:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Azure Document Intelligence 리소스를 설정하는 방법에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

Python API

Python에서 기본 사용법:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # 플러그인을 활성화하려면 True로 설정
result = md.convert("test.xlsx")
print(result.text_content)

Python에서 Document Intelligence 변환:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

이미지 설명에 대규모 언어 모델을 사용하려면(현재 pptx 및 이미지 파일에만 해당) llmclient 및 llmmodel을 제공하세요:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="선택적 사용자 정의 프롬프트")
result = md.convert("example.jpg")
print(result.text_content)

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를 참조하거나 추가 질문이나 의견이 있으면 [email protected]으로 문의하세요.

기여 방법

이슈를 살펴보거나 PR 검토를 도와 기여할 수 있습니다. 모든 이슈나 PR을 환영하지만, 또한 [...]