markitdown

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #llm #go #macos #nodejs #awesome #cli #kubernetes #pytorch #security #open-source

(★ 174,077)

파일 및 오피스 문서를 Markdown으로 변환하는 Python 도구입니다.

markitdown 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MarkItDown

[![PyPI](https://img.shields.io/pypi/v/markitdown.svg)](https://pypi.org/project/markitdown/)
![PyPI - Downloads](https://img.shields.io/pypi/dd/markitdown)
[![Built by AutoGen Team](https://img.shields.io/badge/Built%20by-AutoGen%20Team-blue)](https://github.com/microsoft/autogen)

> [!IMPORTANT]
> MarkItDown은 현재 프로세스의 권한으로 I/O를 수행합니다. `open()`이나 `requests.get()`처럼 프로세스 자체가 접근할 수 있는 리소스에 접근합니다. 신뢰할 수 없는 환경에서는 입력을 검증(Sanitize)하고, 사용 사례에 필요한 가장 제한된 `convert_*` 함수(예: `convert_stream()` 또는 `convert_local()`)를 호출하세요. 자세한 내용은 문서의 [Security Considerations](#security-considerations) 섹션을 참조하세요.

MarkItDown은 LLM 및 관련 텍스트 분석 파이프라인에서 사용할 수 있도록 다양한 파일을 Markdown으로 변환하기 위한 경량 Python 유틸리티입니다. 이러한 목적을 위해 [textract](https://github.com/deanmalmgren/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을 자주 포함합니다. 이는 LLM들이 방대한 양의 Markdown 형식 텍스트로 학습되었으며 이를 잘 이해하고 있음을 시사합니다. 부수적인 이점으로, Markdown 규칙은 토큰 효율성도 매우 뛰어납니다.

## 사전 요구 사항
MarkItDown은 Python 3.10 이상이 필요합니다. 의존성 충돌을 방지하기 위해 가상 환경을 사용하는 것을 권장합니다.

표준 Python 설치 환경에서는 다음 명령어를 사용하여 가상 환경을 생성하고 활성화할 수 있습니다:

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

`uv`를 사용하는 경우, 다음 명령어로 가상 환경을 생성할 수 있습니다:

```bash
uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: 이 가상 환경에 패키지를 설치할 때는 단순 'pip install' 대신 'uv pip install'을 사용해야 합니다.
```

Anaconda를 사용하는 경우, 다음 명령어로 가상 환경을 생성할 수 있습니다:

```bash
conda create -n markitdown python=3.12
conda activate markitdown
```

## 설치

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

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

## 사용법

### 커맨드라인

```bash
markitdown path-to-file.pdf > document.md
```

또는 `-o`를 사용하여 출력 파일을 지정할 수 있습니다:

```bash
markitdown path-to-file.pdf -o document.md
```

콘텐츠를 파이프(pipe)로 전달할 수도 있습니다:

```bash
cat path-to-file.pdf | markitdown
```

### 선택적 의존성 (Optional Dependencies)
MarkItDown에는 다양한 파일 형식을 활성화하기 위한 선택적 의존성이 존재합니다. 이 문서의 앞부분에서는 `[all]` 옵션을 사용하여 모든 선택적 의존성을 설치했습니다. 하지만 더 세밀한 제어를 위해 개별적으로 설치할 수도 있습니다. 예를 들면:

```bash
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 동영상 자막(텍스트 변환) 가져오기용 의존성을 설치합니다.

### 플러그인 (Plugins)

MarkItDown은 서드파티 플러그인도 지원합니다. 플러그인은 기본적으로 비활성화되어 있습니다. 설치된 플러그인 목록을 보려면:

```bash
markitdown --list-plugins
```

플러그인을 활성화하려면 다음을 사용하세요:

```bash
markitdown --use-plugins path-to-file.pdf
```

사용 가능한 플러그인을 찾으려면 GitHub에서 `#markitdown-plugin` 해시태그를 검색하세요. 플러그인을 개발하려면 `packages/markitdown-sample-plugin`을 참고하세요.

#### markitdown-ocr 플러그인

`markitdown-ocr` 플러그인은 PDF, DOCX, PPTX, XLSX 변환기에 OCR 지원을 추가하여, MarkItDown이 이미지 설명에 이미 사용하는 것과 동일한 `llm_client` / `llm_model` 패턴을 사용하여 포함된 이미지에서 텍스트를 추출합니다. 새로운 ML 라이브러리나 바이너리 의존성이 필요하지 않습니다.

**설치:**

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

**사용법:**

이미지 설명에 사용할 것과 동일한 `llm_client`와 `llm_model`을 전달하세요:

```python
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은 조용히 건너뛰고 표준 내장 변환기가 대신 사용됩니다.

자세한 dokumentation은 [`packages/markitdown-ocr/README.md`](packages/markitdown-ocr/README.md)를 참조하세요.

### Azure Content Understanding

[Azure Content Understanding](https://learn.microsoft.com/azure/ai-services/content-understanding/)은 구조화된 필드 추출(YAML front matter), 멀티모달 지원(문서, 이미지, 오디오, 비디오), 그리고 설정 가능한 분석기(analyzer)를 통해 더 높은 품질의 변환을 제공합니다.

설치: `pip install 'markitdown[az-content-understanding]'`

#### Content Understanding을 사용해야 하는 시기

Content Understanding은 기본 제공 변환기나 Document Intelligence가 제공하는 것 이상의 기능이 필요할 때 이상적입니다:

- **오디오 및 비디오 파일** — 비디오의 경우 CU가 유일한 옵션이며, 오디오의 경우 더 높은 품질의 클라우드 옵션입니다. 기본 제공 변환기는 비디오를 지원하지 않으며 기본적인 오디오 전사(transcription)만 제공합니다.
- **구조화된 필드 추출** — [사전 구축된(Prebuilt)](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers) 또는 [사용자 지정(Custom-built)](https://learn.microsoft.com/azure/ai-services/content-understanding/how-to/customize-analyzer-content-understanding-studio?tabs=portal) 분석기가 YAML front matter로 직렬화된 도메인별 필드(송장 금액, 영수증 날짜, 계약 조항 등)를 추출합니다. 기본 제공 또는 Doc Intel 통합 기능은 필드를 노출하지 않습니다.
- **더 높은 품질의 문서 추출** — 스캔된 PDF, 복잡한 표, 다페이지 문서에 대한 클라우드 기반 레이아웃 분석 및 OCR.
- **모든 모달리티를 위한 단일 API** — 하나의 `cu_endpoint`가 자동 분석기 라우팅을 통해 문서, 이미지, 오디오, 비디오를 모두 처리합니다.

| 기능 | 기본 제공 변환기 | Azure Document Intelligence | Azure Content Understanding |
|------------|---------------------|-----------------------------|-----------------------------|
| 문서 변환 | 오프라인, 형식별 추출 | 클라우드 레이아웃 추출 | 클라우드 멀티모달 추출 |
| 구조화된 필드 | 사용할 수 없음 | 이 통합에서는 노출되지 않음 | 분석기 필드로부터의 YAML front matter |
| 사용자 지정 분석기 | 사용할 수 없음 | 이 통합에서는 설정할 수 없음 | `cu_analyzer_id` 지원 |
| 오디오 및 비디오 | 기본 오디오, 비디오 미지원 | 지원되지 않음 | 오디오 및 비디오 분석기 |
| 비용 | 로컬 컴퓨팅 전용 | 유료 Azure API 호출 | 유료 Azure API 호출 |

**CLI:**

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

**Python API:**

```python
from markitdown import MarkItDown

# 제로 구성(Zero-config) — 파일 형식별 분석기 자동 선택
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)
```

**사용자 지정 분석기 사용 시** (도메인별 필드 추출):

```python
md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# 출력에는 추출된 필드가 포함된 YAML front matter가 포함됩니다:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# 
# ...
```

`cu_analyzer_id`가 설정되면, 변환기는 분석기의 모달리티에 기반하여 호환되는 파일 형식으로 범위를 자동으로 지정합니다. 호환되지 않는 형식(예: 문서 분석기가 지정된 오디오 파일)은 기본 사전 구축 분석기로 자동 라우팅됩니다.

**비용 참고 사항:** CU로 라우팅되는 형식에 대한 각 `convert()` 호출은 유료 Azure API 호출입니다. CU로 라우팅할 형식을 제한하려면 `cu_file_types`를 사용하세요:

```python
from markitdown.converters import ContentUnderstandingFileType

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

Azure Content Understanding에 대한 자세한 정보는 [여기](https://learn.microsoft.com/azure/ai-services/content-understanding/)에서 확인할 수 있습니다.

### Azure Document Intelligence

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

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

Azure Document Intelligence 리소스를 설정하는 방법에 대한 자세한 정보는 [여기](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/create-document-intelligence-resource?view=doc-intel-4.0.0)에서 확인할 수 있습니다.

### Python API

Python에서의 기본 사용법:

```python
from markitdown import MarkItDown

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

Python에서의 Document Intelligence 변환:

```python
from markitdown import MarkItDown

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

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

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

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)
```

### Docker

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

## 기여하기 (Contributing)

이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 귀하에게 기여를 사용할 권리가 있고 실제로 우리에게 부여한다는 것을 선언하는 기여자 라이선스 계약(CLA)에 동의할 것을 요구합니다. 자세한 내용은 https://cla.opensource.microsoft.com을 방문하세요.

풀 리퀘스트(PR)를 제출하면 CLA 봇이 CLA 제공이 필요한지 자동으로 판단하고 PR을 적절히 표시합니다(예: 상태 검사, 댓글). 봇이 제공하는 안내를 따르기만 하면 됩니다. 이 작업은 당사의 CLA를 사용하는 모든 저장소를 통틀어 한 번만 수행하면 됩니다.

이 프로젝트는 [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)를 채택했습니다.
자세한 내용은 [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)를참조하거나 추가 질문이나 의견이 있는 경우 [opencode@microsoft.com](mailto:opencode@microsoft.com)으로 문의하세요.

### 기여하는 방법

이슈를 살펴보거나 PR 리뷰를 도와주어 기여할 수 있습니다. 어떤 이슈나 PR이든 환영하지만, 커뮤니티 기여를 촉진하기 위해 일부 이슈에는 'open for contribution' 및 'open for reviewing' 라벨을 지정해 두었습니다. 이는 물론 제안일 뿐이며 원하시는 방식으로 자유롭게 기여해 주시면 됩니다.

|            | 전체                                                          | 커뮤니티의 도움이 특히 필요한 항목                                                                                                      |
| ---------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Issues** | [모든 이슈](https://github.com/microsoft/markitdown/issues) | [기여 열린 이슈](https://github.com/microsoft/markitdown/issues?q=is%3Aissue+is%3Aopen+label%3A%22open+for+contribution%22) |
| **PRs**    | [모든 PR](https://github.com/microsoft/markitdown/pulls)     | [리뷰 열린 PR](https://github.com/microsoft/markitdown/pulls?q=is%3Apr+is%3Aopen+label%3A%22open+for+reviewing%22)              |

</div>

### 테스트 및 검사 실행

- MarkItDown 패키지로 이동합니다:

```sh
  cd packages/markitdown
  ```

- 환경에 `hatch`를 설치하고 테스트를 실행합니다:

```sh
  pip install hatch  # hatch 설치의 다른 방법: https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  ```

(대안) 모든 의존성이 설치되어 있는 Devcontainer를 사용합니다:

```sh
  # Devcontainer에서 프로젝트를 다시 열고 다음을 실행하세요:
  hatch test
  ```

- PR을 제출하기 전에 pre-commit 검사를 실행합니다: `pre-commit run --all-files`

### 보안 고려사항 (Security Considerations)

MarkItDown은 현재 프로세스의 권한으로 I/O를 수행합니다. `open()`이나 `requests.get()`처럼 프로세스 자체가 접근할 수 있는 리소스에 접근합니다.

**입력을 검증하세요:** 신뢰할 수 없는 입력을 MarkItDown에 직접 전달하지 마십시오. 호스팅 또는 서버 측 애플리케이션 등에서 입력의 일부가 신뢰할 수 없는 사용자나 시스템에 의해 제어될 수 있는 경우, MarkItDown을 호출하기 전에 반드시 검증하고 제한해야 합니다. 환경에 따라 파일 경로 제한, URI 스키마 및 네트워크 목적지 제한, 사설(private), 루프백(loopback), 링크 로컬(link-local) 또는 메타데이터 서비스 주소에 대한 접근 차단 등이 이에 포함될 수 있습니다.

**필요한 변환 메서드만 호출하세요:** 사용 사례에 맞는 가장 제한된 변환 API를 선호하십시오. MarkItDown의 `convert()` 메서드는 의도적으로 허용 범위가 넓어 로컬 파일, 원격 URI, 바이트 스트림을 모두 처리할 수 있습니다. 애플리케이션이 로컬 파일 읽기만 필요한 경우, 대신 `convert_local()`을 호출하십시오. URI 가져오기에 대해 더 많은 제어가 필요한 경우, 직접 `requests.get()`을 호출하고 응답 객체를 `convert_response()`에 전달하십시오. 최대의 제어가 필요한 경우, 변환하려는 입력에 대한 스트림을 열고 `convert_stream()`을 호출하십시오.

### 서드파티 플러그인 기여하기

서드파티 플러그인을 만들고 공유하여 기여할 수도 있습니다. 자세한 내용은 `packages/markitdown-sample-plugin`을 참조하세요.

## 상표 (Trademarks)

이 프로젝트에는 프로젝트, 제품 또는 서비스에 대한 상표나 로고가 포함될 수 있습니다. Microsoft 상표 또는 로고의 허가된 사용은 [Microsoft의 Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)를 따르고 이를 준수해야 합니다. 이 프로젝트의 수정된 버전에서 Microsoft 상표나 로고를 사용하는 것은 혼동을 야기하거나 Microsoft의 후원을 암시해서는 안 됩니다.
제3자 상표 또는 로고의 모든 사용은 해당 제3자의 정책을 따릅니다.

markitdown

markitdown 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

markitdown

markitdown 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README