<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/markitdown) · [上游 README](https://github.com/microsoft/markitdown/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# MarkItDown

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

> [!IMPORTANT]
> MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 类似，它会访问进程自身能够访问的资源。在不受信任的环境中请对输入进行清理，并调用你的用例所需的最精简的 `convert_*` 函数（例如 `convert_stream()` 或 `convert_local()`）。更多信息请参阅文档的[安全注意事项](#security-considerations)部分。

MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，以便与 LLM（大语言模型）及相关文本分析流水线配合使用。在这方面，它与 [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 极其接近纯文本，标记和格式极少，但仍能提供一种表示重要文档结构的方式。主流的 LLM，例如 OpenAI 的 GPT-4o，本身就"说" Markdown，并且经常在未经提示的情况下将 Markdown 融入其响应中。这表明它们在海量的 Markdown 格式文本上进行了训练，并对其理解深刻。作为附带好处，Markdown 惯例在 token 效率方面也非常高。

## 前置条件
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: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment
```

如果你使用 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
```

你也可以通过管道传入内容：

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

### 可选依赖
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 文档智能所需的依赖
* `[az-content-understanding]` 安装 Azure 内容理解所需的依赖
* `[audio-transcription]` 安装 wav 和 mp3 文件音频转录所需的依赖
* `[youtube-transcription]` 安装获取 YouTube 视频转录所需的依赖

### 插件

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 支持，使用 LLM Vision 从嵌入图像中提取文本——采用与 MarkItDown 已有的图像描述功能相同的 `llm_client` / `llm_model` 模式。无需新的机器学习库或二进制依赖。

**安装：**

```bash
pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client
```

**使用方法：**

传入与你用于图像描述相同的 `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 会被静默跳过，转而使用标准的内置转换器。

详细文档请参阅 [`packages/markitdown-ocr/README.md`](packages/markitdown-ocr/README.md)。

### Azure 内容理解

[Azure 内容理解](https://learn.microsoft.com/azure/ai-services/content-understanding/) 提供更高质量的转换，支持结构化字段提取（YAML 前置元数据）、多模态支持（文档、图像、音频、视频）以及可配置的分析器。

安装：`pip install 'markitdown[az-content-understanding]'`

#### 何时使用内容理解

当你需要超越内置转换器或文档智能集成所提供的功能时，内容理解是理想之选：

- **音频和视频文件** — CU（内容理解）是视频的唯一选项，也是音频的更高质量云端选项。内置转换器不支持视频，且仅提供基础的音频转录。
- **结构化字段提取** — [预置](https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers) 或[自定义](https://learn.microsoft.com/azure/ai-services/content-understanding/how-to/customize-analyzer-content-understanding-studio?tabs=portal) 分析器可提取领域特定字段（发票金额、收据日期、合同条款），并以 YAML 前置元数据的形式序列化输出。内置转换器和文档智能集成均不公开字段信息。
- **更高质量的文档提取** — 基于云端的布局分析和 OCR，适用于扫描版 PDF、复杂表格和多页文档。
- **所有模态的统一 API** — 一个 `cu_endpoint` 即可处理文档、图像、音频和视频，并自动进行分析器路由。

| 功能 | 内置转换器 | Azure 文档智能 | Azure 内容理解 |
|------------|---------------------|-----------------------------|-----------------------------|
| 文档转换 | 离线、按格式提取 | 云端布局提取 | 云端多模态提取 |
| 结构化字段 | 不可用 | 此集成不公开 | 来自分析器字段的 YAML 前置元数据 |
| 自定义分析器 | 不可用 | 此集成中不可配置 | 支持，使用 `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 — 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)
```

**使用自定义分析器**（用于领域特定字段提取）：

```python
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_file_types`` 可限制哪些格式路由到 CU：

```python
from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # only PDFs use 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) # Set to True to enable plugins
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
```

## 贡献

本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权且确实授予我们使用您贡献的权利。详情请访问 https://cla.opensource.microsoft.com.。

当您提交拉取请求（Pull Request）时，CLA 机器人会自动判断您是否需要提供 CLA，并适当装饰 PR（例如状态检查、评论）。只需按照机器人提供的说明操作即可。您只需在所有使用我们 CLA 的仓库中执行一次。

本项目已采用 [Microsoft 开放源代码行为准则](https://opensource.microsoft.com/codeofconduct/).)。更多信息请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/))，或通过 [opencode@microsoft.com](mailto:opencode@microsoft.com) 联系以提出其他问题或意见。

### 如何贡献

您可以通过查看 Issue 或帮助审核 PR 来提供帮助。任何 Issue 或 PR 都欢迎，但我们也标记了一些"开放供贡献"和"开放供审核"的内容，以方便社区贡献。当然，这些都只是建议，欢迎您以任何方式贡献。

<div align="center">

|            | 全部                                                         | 特别需要社区帮助                                                                                                                          |
| ---------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Issues** | [全部 Issues](https://github.com/microsoft/markitdown/issues))                         | [开放供贡献的 Issues](https://github.com/microsoft/markitdown/issues?q=is%3Aissue+is%3Aopen+label%3A%22open+for+contribution%22))                                |
| **PRs**    | [全部 PRs](https://github.com/microsoft/markitdown/pulls))                            | [开放供审核的 PRs](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``

### 安全注意事项

MarkItDown 以当前进程的权限执行 I/O 操作。与 ``open()`` 或 ``requests.get()`` 类似，它可以访问进程本身能访问的资源。

**对输入进行消毒：** 不要将不受信任的输入直接传递给 MarkItDown。如果输入的任何部分可能受不受信任的用户或系统控制（例如在托管或服务端应用中），则必须在调用 MarkItDown 之前对其进行验证和限制。根据您的环境，这可能包括限制文件路径、限制 URI 方案和网络目标，以及阻止访问私有地址、环回地址、链路本地地址或元数据服务地址。

**仅调用您需要的转换方法：** 优先使用最适合您用例的最小转换 API。MarkItDown 的 ``convert()`` 方法设计上较为宽松，可以处理本地文件、远程 URI 和字节流。如果您的应用程序只需要读取本地文件，请改用 ``convert_local()``。如果您需要对 URI 获取进行更多控制，请自行调用 ``requests.get()``，并将响应对象传递给 ``convert_response()``。如需最大程度的控制，请打开要转换的输入流，然后调用 ``convert_stream()``。

### 贡献第三方插件

您还可以通过创建和分享第三方插件来贡献。更多详情请参见 ``packages/markitdown-sample-plugin``。

## 商标

本项目可能包含项目、产品或服务的商标或徽标。对 Microsoft 商标或徽标的授权使用必须遵守并遵循 [Microsoft 商标与品牌指南](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).)。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何第三方商标或徽标的使用均须遵守第三方的政策。