MarkItDown:把 PDF、Word、PPT 丢进去,出来一份 AI 读得懂的 Markdown

大家好，我是小武！

每个月月底都有二十几份季度报告要合到一起看，docx 和 pdf 混着，格式还各家不一样。想让模型帮我做个横向对比，最省事的办法是开个对话框，一份一份拖进去。

拖到第十份就烦了。下个月还得再来一遍。

真想把这活写成脚本，麻烦在格式上。模型吃不了 docx 的二进制，也读不出 PDF 里那层排版。得先转成纯文本，还得让「哪句是标题、哪块是表格」留在文本里。

MarkItDown 干的就是这一步。微软维护，19 万 star，MIT 许可，一份文件进去，一份 Markdown 出来。

它把什么变成什么

支持名单拉得很长：PDF、Word、PowerPoint、Excel、图片、音频、HTML、CSV、JSON、XML、压缩包、EPub、Outlook 邮件，还有 YouTube 链接。压缩包会挨个文件拆开转，YouTube 取的是字幕。

先看 Word。一份带两级标题、项目符号、六行表格、结尾还有一句加粗的季度复盘，转出来是这样：

# 顶住大标题，## 管二级，项目符号变成 *，表格成了管道表。原来那句加粗还留着两颗星。粘进任何模型的上下文，它分得清哪句是标题、哪几个数在同一行。

PPT 的转法更直接，一页一张幻灯片，页与页之间留一行注释标着第几页：

页里的表格变成一张表，图表也被拉平成「类目 + 系列」两列。幻灯片 3 那条带长串 ID 的行，原件里是合并单元格，转完把 ID 摊在中间。

Excel 是每个工作表一个小标题加一张表，图片写进 EXIF 里的拍摄信息和一句描述，音频转成文字。后两样要靠网络上的服务，不是本地跑的。

底下没有模型，只有解析器

它没有「理解」这回事，底下是一堆现成的解析器，各管一段。

magika 先看文件内容判断真实类型，改过后缀也骗不过去；Word 走 mammoth，PDF 走 pdfminer.six，PowerPoint 走 python-pptx，Excel 走 openpyxl。各自把标题、段落、列表、表格的层级吐出来，再统一拼成 Markdown。

整条链里只有两件事会叫模型：给图片写一句描述、把音频转成文字。这两个是可选的，要在代码里传 llm_client 和 llm_model 才走，不传就只出结构。

整个过程不叫模型、不联网，也不花接口费。它认的是结构，不认内容：一份排版混乱、字却都在的 PDF，转出来一堆字，顺序是乱的。

两条命令开始用

第一条装全量依赖，第二条把文件转成 .md。不想装那么大，可以按格式挑：pip install 'markitdown[pdf,docx,pptx]' 只装这三种。Python 要 3.10 到 3.14。

想在代码里调，四行：

还有一个 markitdown-mcp，装完能让 AI 客户端直接读你本机上的文件，不用先手动转一遍。

卡住的地方

最狠的一个是扫描件。一份 276 KB 的病历扫描，转完 0 字节，连一个空格都没有。

它读的是文字层，扫进去的页面只有像素。要它认字得装 markitdown-ocr 插件走模型视觉，或者接 Azure 的文档智能，两条路都要额外花钱。

带框线的表转得干净。合并单元格一多，无边框的表就散架，一行被切成好几条记录：

SKU-8847 在原件里跨了四格，转出来先是一条只有编号和库位，再一条只剩实际数和差额。数字一个没丢，行和行的对应关系得自己接。

Excel 那边栽在公式上。=SUM(B2:C2) 这种格子，它取的是文件里存着的计算结果，公式本身不看。脚本生成的表常常没写这个缓存值，转出来一整列 0。

七份文件一起转，产出差得挺远：

再补三条：输出是给机器读的，排版好不好看不保证；老式 .doc 不在名单里；它按进程权限读文件，接到别人的上传口之前得自己过滤输入。

一次转一个文件夹

一份一份转，说到底还是手动。真正省事的是把一个文件夹整个转成 Markdown，一次性塞进上下文，让它检索和对比。

转出来的文件名和原文件一一对应，回头要引用哪一句，还能顺着文件名找回原件。二十几份报告，一个循环就完事，下个月再跑一遍也不用改代码。