MarkItDown 的目标是成为文档转换为 LLM 友好格式的轻量级工具。与 textract 类似，但它更注重保留文档结构（如标题、列表、表格、链接）并输出为 Markdown。

支持的格式：

  • 文档类：PDF、PowerPoint (PPTX)、Word (DOCX)、Excel (XLSX/XLS)、EPUB、HTML。
  • 媒体类：图像（提取 EXIF 和 OCR）、音频（提取 EXIF 和语音转录）、YouTube 视频（转录）。
  • 数据类：CSV、JSON、XML 等文本格式。
  • 压缩包：ZIP 文件（遍历内容）。

核心特点：

  • 轻量级：专注于常用格式的快速转换。
  • 结构保留：输出 Markdown 包含标题、列表、表格、链接等结构信息。
  • 可扩展：支持第三方插件（如 OCR 插件）。
  • 云集成：可选集成 Azure 文档智能（Document Intelligence）和 Azure 内容理解（Content Understanding）以获得更高精度。

📦 安装

前提要求

  • Python 版本：需要 Python 3.10 或更高版本。
  • 虚拟环境：强烈建议使用虚拟环境。

安装命令

安装完整版本（包含所有可选依赖）：

1
pip install 'markitdown[all]'

按需安装特定格式支持：

1
pip install 'markitdown[pdf, docx, pptx]'  # 仅安装 PDF、Word、PPT 支持

从源码安装：

1
2
3
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

🚀 快速使用

命令行（CLI）用法

1
2
3
4
5
6
7
8
9
10
11
# 基本转换：输出到终端
markitdown path-to-file.pdf

# 输出到文件
markitdown path-to-file.pdf -o document.md

# 从管道输入
cat path-to-file.pdf | markitdown

# 使用 Azure 文档智能
markitdown path-to-file.pdf -o document.md -d -e "<文档智能终结点>"

Python API 用法

1
2
3
4
5
6
from markitdown import MarkItDown

# 基础用法
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)

启用插件：

1
2
md = MarkItDown(enable_plugins=True)
result = md.convert("document.docx")

使用 LLM 进行图像描述（适用于 PPTX 和图像文件）：

1
2
3
4
5
6
7
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)

⚙️ 高级集成与配置

1. Azure 内容理解（Content Understanding）

当需要更高质量的结构化提取（如从发票中提取字段）或处理音视频时，可集成 Azure 内容理解。

1
2
3
4
5
6
from markitdown import MarkItDown

# 使用默认预建分析器
md = MarkItDown(cu_endpoint="<你的终结点>")
result = md.convert("report.pdf")
print(result.markdown)  # 输出包含 YAML front matter 和内容

2. 第三方插件：OCR 插件示例

markitdown-ocr 插件可为 PDF、DOCX 等添加 OCR 功能，提取图像中的文字。

1
pip install markitdown-ocr

在代码中启用：

1
2
3
4
5
6
7
8
9
from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("scanned_document.pdf")

3. Docker 运行

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

📋 常用命令与配置

命令/操作 说明
markitdown --list-plugins 列出已安装的插件
markitdown --use-plugins file.pdf 启用插件进行转换
markitdown --use-cu file.pdf 启用 Azure 内容理解转换
markitdown <file> -o <output.md> 指定输出文件

🔒 安全注意事项

  • 权限：MarkItDown 以当前进程的权限执行 I/O，能访问进程可访问的所有资源。
  • 输入净化：不要将不受信任的输入直接传递给 convert() 函数。在调用前，必须对输入进行验证和限制（如限制文件路径、URI scheme、网络目标）。
  • 最小权限原则：优先使用最窄的转换 API：
    • convert_local()：仅用于本地文件。
    • convert_response()：用于你已通过 requests 获取的响应对象。
    • convert_stream()：用于你已打开的流。

❓ 常见问题

  • 转换质量不佳？ MarkItDown 为 LLM 管道优化，而非人类阅读。对于高保真需求，可考虑 Azure 内容理解或文档智能。
  • 缺少特定格式支持？ 安装对应的可选依赖（如 [xlsx]、[pdf]）。如需新格式，可考虑开发插件。
  • 如何开发插件？ 查看仓库中的 packages/markitdown-sample-plugin 示例。

总结

MarkItDown 是一个专为 AI 工作流设计的、轻量且灵活的文档转换工具。强烈建议从 pip install 'markitdown[all]' 开始，以获得最完整的格式支持。日常使用可通过 CLI 快速转换单个文件，或通过 Python API 将其集成到数据处理管道中。如果你需要处理扫描件或复杂表格，可以探索其 Azure 集成 或 OCR 插件。使用时请务必留意其安全注意事项，特别是处理不可信输入时。