MarkItDown

[!TIP]
MarkItDown 现在提供了一个 MCP（Model Context Protocol）服务器，用于与像 Claude Desktop 这样的 LLM 应用程序集成。更多信息请参见 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 格式，以便与 LLM 和相关的文本分析管道一起使用。在这方面，它最类似于 textract，但专注于保留重要的文档结构和内容作为 Markdown（包括：标题、列表、表格、链接等）。虽然输出通常相当美观且对人类友好，但它旨在被文本分析工具消费——可能不是适合高保真度文档转换供人类阅读的最佳选项。

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

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

为什么选择 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

注意：确保使用 'uv pip install' 而不仅仅是 '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

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

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 Document Intelligence 所需的依赖项
• [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。

Azure Document Intelligence

要使用 Microsoft Document Intelligence 进行转换：

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

有关如何设置 Azure Document Intelligence 资源的更多信息，请参阅这里。

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)

要使用大型语言模型进行图像描述，请提供 llm_client 和 llm_model：

python
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
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。

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

本项目采用了 Microsoft 开源行为准则。更多详细信息，请参阅 行为准则常见问题解答 或通过 opencode@microsoft.com 联系我们提出任何其他问题或评论。

如何贡献

您可以帮助查看问题或帮助审查 PR。任何问题或 PR 都是受欢迎的，但我们也标记了一些为“开放供贡献”和“开放供审查”，以帮助促进社区贡献。当然，这些建议仅供参考，欢迎您以任何方式贡献。

	全部	特别需要社区帮助
Issues	所有 Issues	开放贡献的 Issues
PRs	所有 PRs	开放审阅的 PRs

运行测试和检查

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

贡献第三方插件

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

商标

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