微软MarkItDown：文档转Markdown的Python工具链

MarkItDown 会以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 类似，它只能访问进程本身可访问的资源。在不受信任的环境中请对输入进行净化，并调用所需范围最窄的转换函数（如 convert_stream() 或 convert_local()）。更多详情请参阅文档的安全注意事项部分。

MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，以供 LLM 及相关文本分析流程使用。在这一目标上，它最 comparable to textract，但更注重将重要文档结构和内容保留为 Markdown 格式（包括：标题、列表、表格、链接等）。虽然输出通常具有相当的可读性、对人类友好，但它是为文本分析工具设计的——对于需要高精度文档转换供人类阅读的场景，可能并非最佳选择。

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

• 图片（EXIF 元数据和 OCR）
• 音频（EXIF 元数据和语音转录）
• 基于文本的格式（CSV、JSON、XML）
• ZIP 文件（遍历其内容）

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 上搜索 hashtag #markitdown-plugin。开发插件请参阅 packages/markitdown-sample-plugin。

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加了 OCR 支持，使用 LLM Vision 从嵌入图片中提取文本——与 MarkItDown 已有的图片描述功能使用相同的 llm_client / llm_model 模式。无需新的 ML 库或二进制依赖。

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

如果不提供 llm_client，插件仍会加载，但 OCR 会被静默跳过，使用标准内置转换器代替。

详细文档请参阅 packages/markitdown-ocr/README.md。

Azure Content Understanding

Azure Content Understanding 提供更高质量的转换，支持结构化字段提取（YAML front matter）、多模态支持（文档、图片、音频、视频）以及可配置的分析器。

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

当需要内置或 Document Intelligence 转换器无法提供的功能时，Content Understanding 是理想选择：

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

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

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 front matter：
# ---
# 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>"

端点也可以在环境中设置一次，这样调用者只需使用 -d：

export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown path-to-file.pdf -o document.md -d

有关如何设置 Azure Document Intelligence 资源的更多信息可在此处找到

Python 基本用法：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # 设为 True 以启用插件
result = md.convert("test.xlsx")
print(result.markdown)

Python 中使用 Document Intelligence 转换：

from markitdown import MarkItDown

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

若要使用大语言模型进行图片描述（目前仅支持 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.markdown)

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

在开始重要工作之前，请阅读 What to Contribute，它描述了本仓库的范围边界——什么在范围内，什么不在。

本项目欢迎贡献和建议。大多数贡献需要你同意 Contributor License Agreement (CLA)，声明你有权并且确实向我们授予使用你的贡献的权利。详情请访问 https://cla.opensource.microsoft.com。

当你提交 pull request 时，CLA bot 会自动判断你是否需要提供 CLA，并相应地装饰 PR（如状态检查、评论）。只需按照 bot 提供的说明操作即可。在使用我们 CLA 的所有仓库中，你只需执行一次。

本项目采用 Microsoft Open Source Code of Conduct。更多信息请参阅 Code of Conduct FAQ 或发送邮件至 opencode@microsoft.com 提出任何其他问题或评论。

MarkItDown 是一个用于将文件转换为 Markdown 的 Python 工具，以供 LLM 及相关文本分析流程使用。本仓库旨在提供可整合到其他系统中的 Python 库——而不是基于它们构建的最终用户应用程序。

在范围内：

• 提升现有转换器的保真度（谨慎添加新格式——尤其是会引入新依赖的格式。大多数情况下，新格式可以通过第三方插件获得更好的支持。）
• Bug 修复、性能改进和安全修复
• markitdown 命令行接口
• markitdown-mcp 包
• 测试、文档和开发者工具

我们无法接受额外的应用程序、服务或服务器，包括：

• Web 服务器、REST 或 HTTP API 以及托管转换服务
• Web 前端和基于浏览器的用户界面
• 桌面和移动应用程序（PyQt、PySide、Tkinter、Electron、Flutter 及类似框架）

这类项目确实有用，我们宁愿看到它们蓬勃发展也不愿将它们拒之门外。如果你有兴趣为 MarkItDown 提供 Web 服务、API 或图形应用程序，请将其作为依赖 markitdown（从 PyPI）的独立包或项目来维护。

在不修改本仓库的情况下扩展 MarkItDown

MarkItDown 支持第三方插件，因此对新格式的支持可以独立于本仓库发布和安装：

markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf

参阅 packages/markitdown-sample-plugin 开始开发，并给你的仓库打上 #markitdown-plugin 标签，以便其他人可以找到它。

你可以通过查看 issue 或帮助审查 PR 来提供帮助。我们还将一些 issue 标记为"open for contribution"，将一些 PR 标记为"open for reviewing"，以促进社区贡献。这些标签只是建议；欢迎提交符合上述范围描述的贡献。

运行测试和检查

导航到 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()。

本项目可能包含项目的商标或标识。Microsoft 商标或标识的授权使用必须遵守并遵循 Microsoft 的商标和品牌指南。在本项目的修改版本中使用 Microsoft 商标或标识不得造成混淆或暗示 Microsoft 赞助。第三方商标或标识的使用须遵守这些第三方的政策。