microsoft/markitdown

MarkItDown – 文件转 Markdown，适用于 LLM 流水线

这是什么 – 一个轻量级 Python 库和 CLI，可将多种文档类型（PDF、Word、PowerPoint、Excel、图片、音频、HTML、JSON、CSV、ZIP、YouTube 视频、EPub 等）转换为 Markdown。输出保留标题、列表、表格和链接等结构线索，让大型语言模型易于处理。

为什么用 Markdown？ – LLM 大量使用 Markdown 训练；此格式为纯文本但具表达力且 token 效率高，因此将原始文件转换为 Markdown 可提升下游文本分析质量。

主要功能

• 常见 Office 格式的本地离线转换器。
• 可选的云端后端：
  • Azure Document Intelligence – 布局感知提取。
  • Azure Content Understanding – 多模态（文档、图片、音频、视频）转换，具结构化字段提取（YAML front-matter）和自定义分析器。
• LLM 驱动的图片描述 – 可插入任何 OpenAI 兼容客户端（例如 gpt-4o）来为嵌入图片生成说明。
• OCR 插件（markitdown-ocr）使用 LLM 视觉模型进行图像文本识别，无需额外二进制文件。
• 插件系统 – 第三方扩展可添加新格式；可通过 #markitdown-plugin 标签发现。
• 安全感知 API – 狭窄的转换函数（convert_local、convert_stream、convert_response）让调用者限制 I/O 范围。

安装

# 核心 + 所有可选格式支持
pip install 'markitdown[all]'
# 或只选所需，例如 PDF + DOCX
pip install 'markitdown[pdf,docx]'

开发时，克隆仓库并以可编辑模式安装包：

git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

命令行使用

# 简单转换，stdout → markdown
markitdown path/to/file.pdf > out.md

# 指定输出文件
markitdown path/to/file.pdf -o out.md

# 管道数据
cat file.pdf | markitdown > out.md

加上 --use-plugins 以启用任何已安装的插件，或 --list-plugins 查看可用项。

Python API（基本）

from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)   # 设为 True 以加载插件
result = md.convert('report.xlsx')
print(result.markdown)

Azure Document Intelligence 示例：

md = MarkItDown(docintel_endpoint='https://<resource>.cognitiveservices.azure.com/')
print(md.convert('file.pdf').markdown)

Azure Content Understanding 搭配自定义分析器：

md = MarkItDown(
    cu_endpoint='https://<cu>.cognitiveservices.azure.com/',
    cu_analyzer_id='my-invoice-analyzer'
)
print(md.convert('invoice.pdf').markdown)   # 包含 YAML front-matter

LLM 驱动的图片描述：

from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model='gpt-4o')
print(md.convert('photo.jpg').markdown)

扩展工具

• 安装第三方插件（pip install markitdown-ocr 等）。
• 按照 packages/markitdown-sample-plugin 中的示例创建自己的插件，并将仓库标记为 #markitdown-plugin。
• 控制安装哪些可选依赖项，以保持环境轻量。

安全考量 MarkItDown 以与调用进程相同的文件系统和网络权限运行。用户必须清理不受信任的输入、限制路径/URL，并偏好使用最狭窄的转换函数（convert_local、convert_stream 等）以限制暴露。

运行测试

cd packages/markitdown
pip install hatch
hatch shell
hatch test

或使用提供的 DevContainer。

许可证与贡献 以 MIT 许可证开源（依 PyPI 页面）。欢迎贡献，但必须保持在库范围内——不接受 Web 服务、GUI 或托管 API。PR 需要贡献者许可协议。