MarkItDown

[!TIP] MarkItDown 现在提供了一个 MCP（模型上下文协议）服务器，用于与像 Claude Desktop 这样的大语言模型应用程序集成。更多信息请参见 markitdown-mcp。

[!IMPORTANT] 从 0.0.1 到 0.1.0 的重大变更：

• 依赖项现在被组织成可选的功能组（详情如下）。使用 pip install 'markitdown[all]' 来获得向后兼容的行为。
• convert_stream() 现在需要一个二进制文件对象（例如，以二进制模式打开的文件或 io.BytesIO 对象）。这与之前接受文本文件对象（如 io.StringIO）的版本相比是一个重大变更。
• DocumentConverter 类接口已更改为从文件流读取而不是文件路径。不再创建临时文件。如果你是插件或自定义 DocumentConverter 的维护者，可能需要更新你的代码。否则，如果仅使用 MarkItDown 类或 CLI（如这些示例），则无需更改任何内容。

MarkItDown 是一个轻量级的 Python 工具，用于将各种文件转换为 Markdown，以便与大语言模型和相关文本分析管道一起使用。为此，它最类似于 textract，但重点在于将重要的文档结构和内容作为 Markdown 保存（包括：标题、列表、表格、链接等）。虽然输出通常具有合理的呈现效果且易于人类阅读，但它旨在供文本分析工具使用——对于高保真度的人类文档转换来说，可能不是最佳选择。

MarkItDown 目前支持以下文件类型的转换：

• PDF
• PowerPoint
• Word
• Excel
• 图像（EXIF 元数据和 OCR）
• 音频（EXIF 元数据和语音转录）
• HTML
• 文本格式（CSV、JSON、XML）
• ZIP 文件（迭代内容）
• YouTube URL
• EPubs
• …等等！

为什么是 Markdown？

Markdown 非常接近纯文本，具有最少的标记或格式化，但仍提供了一种表示重要文档结构的方法。主流的大语言模型，如 OpenAI 的 GPT-4o，原生地“说”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
# 注意：确保使用 '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 文档智能的依赖项
• [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。

Azure 文档智能

要使用 Microsoft 文档智能进行转换：

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

有关如何设置 Azure 文档智能资源的更多信息，请参见 这里

Python API

Python 中的基本使用：

from markitdown import MarkItDown

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

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：

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 或联系 opencode@microsoft.com 以获取任何额外的问题或评论。

如何贡献

你可以通过查看问题或帮助审查 PR 来做出贡献。任何问题或 PR 都受欢迎，但我们也标记了一些为“开放贡献”和“开放审查”，以帮助促进社区贡献。当然，这些建议仅供参考，你可以根据自己的喜好做出贡献。

<div align="center">

	所有	尤其需要社区帮助
问题	所有问题	开放贡献的问题
PR	所有 PR	开放审查的 PR

</div>

运行测试和检查

• 导航到 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 run --all-files

贡献第三方插件

你还可以通过创建和分享第三方插件来做出贡献。请参阅 packages/markitdown-sample-plugin 获取更多详细信息。

商标

本项目可能包含其他项目、产品或服务的商标或徽标。授权使用 Microsoft 商标或徽标必须遵循并遵守 Microsoft 的商标及品牌指南。在修改版本的项目中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何使用第三方商标或徽标的都受该第三方政策的约束。