MarkItDown:微软开源的文档转 Markdown 工具,喂 LLM 之前先过它
做 RAG 或 Agent,第一步常被说成 embedding。但实际跑起来,embedding 之前还有一关:把 PDF、Word、PPT 里的内容整理成模型能稳定吃的文本。
PDF 有多栏、表格、脚注。PPT 里有标题层级和 bullet。Word 还会混入样式信息。直接把原文件交给模型,解析结果很难预测。
微软开源的 MarkItDown 卡在这个位置。它不是给人做格式转换,也不是要做像素级保真,而是把常见文件压成适合 LLM 消费的 Markdown。
项目在 GitHub 上有 174k+ Star(数字随时变化,请以仓库首页为准)。支持的格式包括:
- Word
- Excel
- PowerPoint
- 图片,支持 EXIF 和 OCR
- 音频,支持 EXIF 和语音转写
- HTML、CSV、JSON、XML
- ZIP、EPub
- YouTube 链接
设计目标很明确:输出不是给人类排版用的文档,而是给 LLM 用的结构化文本。
它解决什么问题
Embedding 前通常要做三件事:
- 提取正文。
- 保留标题、列表、表格等结构。
- 把结果切成模型能处理的块。
MarkItDown 主要负责前两步。
同类工具里,textract 太老,输出常是纯文本,结构信息丢得多。pandoc 更强调文档转换和保真,适合需要接近原版式的场景。unstructured 功能也全,但系统更重,抽象也换了一套。
MarkItDown 走的是中间路线:
- 够轻。
- 能保留一部分文档结构。
- 输出 Markdown,对 LLM 友好。
- 有 CLI,也有 Python API。
Markdown 对 LLM 来说通常比复杂 HTML 或带大量格式标记的文本省 token。GPT-4o 这类模型也能原生理解 Markdown 的标题、列表、表格和代码块。
不过 Markdown 不是永远最短的表示。复杂 Word 样式、PDF 的页眉页脚和坐标布局,转换后仍可能产生噪声。但它提供了一个足够稳定的中间格式。后续切块、检索和生成,可以围绕同一份文本展开。
怎么用
Python 3.10+。全功能安装:
pip install 'markitdown[all]'
只处理 PDF:
pip install 'markitdown[pdf]'
还有 [docx]、[pptx]、[xlsx]、[audio] 等分组。没必要把 OCR、音频转写和所有格式都装上。
CLI:
markitdown file.pdf > out.md
Python API:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content[:500])
# 限制输入来源:只读本地文件
from markitdown import MarkItDown, convert_local
result = convert_local("report.pdf")
print(result.text_content[:500])
MarkItDown().convert() 是高层接口,会根据输入选转换方式。convert_local() 接口更窄,只处理本地文件。
安全上要小心。README 顶部明确提醒:MarkItDown 涉及 I/O 操作,权限风险和 Python 的 open()、网络请求中的 requests.get() 同等级。别因为它只是个文档转换库,就把它放进不可信输入、任意网络地址或高权限 Agent 环境里。
它怎么工作
核心结构不复杂:
- 一个
MarkItDown类。 - 多个
Converter子类。 - 按文件扩展名或 MIME 类型派发 Converter。
- 每个 Converter 自己处理一种格式。
PDF → PdfConverter,Word → DocxConverter,PPT → PptxConverter,YouTube 链接 → YoutubeConverter。
这种设计比一个大函数里堆满 if/else 容易扩展。加一种新格式,通常是加一个 Converter,再接上派发逻辑。
三层 API:
- 高层:
MarkItDown().convert() - 中层:
convert_local() - 底层:
convert_stream()
调用层级越低,权限范围越窄,代码能更明确地区分本地文件、外部网络和流式输入。对 Agent 来说,这个区别不是装饰。Agent 一旦能替用户读文件、访问网络或处理不可信链接,权限设计就是核心功能。
图片和音频的路径不太一样。图片可以提 EXIF,按配置用 OCR。音频可以提元数据并做语音转写。这部分通常依赖外部服务。部署前要确认服务、费用和数据流向。
它哪里好 / 哪里不好
做得好的地方
覆盖面广。一个工具处理 PDF、Office、图片、音频、网页、压缩包和 YouTube 链接。
API 是渐进式的。最简单时一行 CLI;要集成时 MarkItDown().convert();要限制输入来源时,下沉到 convert_local() 或 convert_stream()。
安全声明写得很工程化。README 没回避本地文件、网络请求和第三方服务的风险。
安装考虑了依赖体积。全量装简单,按格式装更省环境。
不足
第一,复杂排版保真度不如 pandoc。
PDF 的跨页表格、脚注、浮动图片、复杂页眉、多栏布局,转换后可能出现顺序变化。OCR 也依赖图片文字质量。
第二,图片 OCR 和音频转写可能依赖 Azure、OpenAI 等外部服务。需要纯本地、纯 CPU、不能上传数据的场景,要自己补模型和依赖。
第三,Excel 不适合无脑塞进一个长文件。大型工作簿、合并单元格、公式、隐藏 sheet 都可能让结果变慢,还塞进一堆无关内容。生产环境应该先筛 sheet、限行列、清公式,或者按表切片。
所以 MarkItDown 不是 pandoc 的替代品,也不是一个"所有文档都正确还原"的解析器。它更像 RAG 链路里的第一道清洗器。
我试了下
本地装了 markitdown[pdf,docx,pptx]。挑了三份材料:
- 20 页、带表格的财报 PDF。
- 20 页 PPT。
- 5 页 Word。
结果:
- PDF 表格基本保住,标题层级正确。
- PPT 保留了 bullet 结构。
- Word 输出干净,段落和标题稳定。
- PDF 约 2 秒。
- PPT 约 1 秒。
- Word 不到 1 秒。
速度受文件复杂度影响大。我这台机器上,PDF 解析主要吃在 PyMuPDF 处理页面上;真正拖慢整条链表的,通常是大型 Excel。
要把结果送进 RAG,我会在 result.text_content 之后继续做两件事:先按标题和段落切块,再按表格、页码或文件名补元数据。别直接把一份 500 页 PDF 塞进一次 convert(),然后期待检索质量稳定。
谁该用
适合:
- RAG 的文档预处理。
- Agent 工具链的数据入口。
- 批量文档清洗。
- 需要把 PDF、Word、PPT 统一转成 Markdown 的脚本。
- 在代码里按扩展名或 MIME 类型派发不同转换器的项目。
不太适合:
- 要求像素级或出版级版式保真。
- 必须完全离线的图片 OCR 或音频转写。
- 复杂 Excel 报表的整文件转换。
- 需要坐标级 PDF 定位、阅读顺序还原、严格表格语义的项目。
我的选择很直接:要给 LLM 喂文本时,先试 MarkItDown;要尽量保版式时,用 pandoc;要复杂文档分区和更重的数据处理时,再看 unstructured。
MarkItDown 的价值不在"支持格式数量"本身。它把 Agent 接收世界的方式简化成了一步:文件进来,Markdown 出去。