markitdown

MarkItDown

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

MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，以便与 LLM（大语言模型）及相关文本分析流水线配合使用。因此，它与 textract 最为相似，但侧重于将重要的文档结构和内容保留为 Markdown 格式（包括：标题、列表、表格、链接等）。虽然输出结果通常具有合理的可读性和友好性，但其设计目的是供文本分析工具消费——可能不是用于高保真的人类阅读文档转换的最佳选择。

MarkItDown 目前支持从以下格式转换：

• PDF
• PowerPoint
• Word
• Excel
• 图片（EXIF 元数据和 OCR）
• 音频（EXIF 元数据和语音转文字）
• HTML
• 基于文本的格式（CSV、JSON、XML）
• ZIP 文件（遍历内容）
• YouTube 网址
• EPub
• ……以及更多！

为什么选择 Markdown？

Markdown 非常接近纯文本，标记或格式极少，但依然能够表示重要的文档结构。主流 LLM，如 OpenAI 的 GPT-4o，原生“说” Markdown，并且经常在未经提示的情况下在回复中融入 Markdown。这表明它们已经在海量的 Markdown 格式文本上进行过训练，并对其有很好的理解。作为附带好处，Markdown 约定也极具 token 效率。

前提条件

MarkItDown 需要 Python 3.10 或更高版本。建议使用虚拟环境以避免依赖冲突。

使用标准 Python 安装，你可以通过以下命令创建并激活虚拟环境：

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

如果使用 uv，你可以通过以下方式创建虚拟环境：

uv venv --python=3.12 .venv
source .venv/bin/activate
# 注意：请使用 'uv pip install' 而不是 'pip install' 来在此虚拟环境中安装包

如果你使用 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] 安装 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 已用于图片描述的 llm_client / llm_model 模式相同。不需要新的机器学习库或二进制依赖。

安装：

pip install markitdown-ocr
pip install openai  # 或任何兼容 OpenAI 的客户端

用法：

传递与图片描述相同的 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.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

当你的需求超出内置或 Document Intelligence 转换器提供的能力时，Content Understanding 是理想选择：

• 音频和视频文件——CU 是视频的唯一选择，也是音频的更高质量云选项。内置转换器不支持视频，仅提供基础的音频转录。
• 结构化字段提取——预构建或自定义构建的分析器可以提取特定领域的字段（发票金额、收据日期、合同条款），并以 YAML 前置元数据形式序列化。内置和 Doc Intel 集成均不暴露字段。
• 更高质量的文档提取——针对扫描 PDF、复杂表格和多页文档的基于云的布局分析和 OCR。
• 单一 API 处理所有模态——一个 cu_endpoint 即可处理文档、图片、音频和视频，并自动路由分析器。

能力	内置转换器	Azure Document Intelligence	Azure Content Understanding
文档转换	离线、特定格式提取	云布局提取	云多模态提取
结构化字段	不可用	此集成不暴露	来自分析器字段的 YAML 前置元数据
自定义分析器	不可用	此集成不可配置	支持，通过 cu_analyzer_id
音频和视频	基础音频，不支持视频	不支持	音频和视频分析器
成本	仅本地计算	计费的 Azure API 调用	计费的 Azure API 调用

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 -->
# ...

当设置了 cu_analyzer_id，转换器会根据分析器的模态自动将其限定为兼容的文件类型。不兼容的类型（例如，使用文档分析器处理音频文件）会自动路由到默认的预构建分析器。

成本说明： 每次对 CU 路由格式的 convert() 调用都是一次计费的 Azure API 调用。使用 cu_file_types 来限制哪些格式路由到 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 资源的更多信息，请参阅[此处](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 转换：

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：

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

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 开源行为准则。更多信息请参阅行为准则常见问题解答或通过 opencode@microsoft.com 联系，提出任何其他问题或评论。

如何贡献

你可以通过查看 issue 或帮助审核 PR 来提供帮助。任何 issue 或 PR 都欢迎，但我们也标记了一些为“开放贡献”和“开放审核”来促进社区贡献。这些当然只是建议，欢迎你以任何你喜欢的方式贡献。

	全部	尤其需要社区帮助
Issues	所有 Issues	开放贡献的 Issues
PRs	所有 PRs	开放审核的 PRs

运行测试和检查

• 导航到 MarkItDown 包：

  cd packages/markitdown
  

• 在你的环境中安装 hatch 并运行测试：

  pip install hatch  # 其他安装 hatch 的方式：https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  

  （替代方案）使用 Devcontainer，其中已安装所有依赖：

  # 在 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 商标和品牌指南。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 赞助。任何第三方商标或徽标的使用均受这些第三方政策的约束。