MarkItDown

Microsoft 推出的轻量级 Python 工具，用于将多种格式的文件转换为 Markdown，以供大语言模型（LLM）及相关文本分析流水线使用。

安装

前提条件

• Python 3.10+
• Java 11+（部分转换器需要）

推荐方式：通过 pipx 安装

pipx install 'markitdown[all]'

通过 pip 安装

pip install 'markitdown[all]'

最小化安装（仅指定格式）

pip install 'markitdown[pdf,docx,pptx]'

支持的格式

命令行（CLI）使用方法

基础转换

# PDF 转 Markdown
markitdown document.pdf > output.md

# Word 转 Markdown
markitdown document.docx -o output.md

# PowerPoint 转 Markdown
markitdown presentation.pptx -o output.md

管道输入

cat document.pdf | markitdown

图像 OCR

markitdown screenshot.png -o text.md

YouTube 视频

markitdown "https://youtube.com/watch?v=..." -o transcript.md

Python API 使用方法

from markitdown import MarkItDown

# 初始化
md = MarkItDown()

# 转换文件
result = md.convert("document.pdf")
print(result.text_content)

# 从流中转换
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f)
    print(result.text_content)

选项

MCP Server

MarkItDown 提供 MCP（Model Context Protocol）服务器，便于与 LLM 应用集成：

pip install markitdown-mcp

最佳实践

1. 批量处理：单次调用处理多个文件以提升效率
2. 按需选择格式：若仅需特定格式支持，建议使用最小化安装
3. OCR 质量保障：扫描文档建议分辨率不低于 300 DPI
4. 输出人工复核：对于结构复杂或含大量图表的文档，务必人工校验生成的 Markdown 内容

故障排查

未找到 Java

请安装 Java 11 或更高版本：

# macOS
brew install openjdk@17

# Ubuntu
sudo apt install openjdk-17-jdk

权限被拒绝

建议使用 pipx 或虚拟环境安装：

python3 -m venv ~/.venvs/markitdown
source ~/.venvs/markitdown/bin/activate
pip install 'markitdown[all]'

参考资料

• GitHub：https://github.com/microsoft/markitdown
• PyPI：https://pypi.org/project/markitdown/
• MCP Server：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp