“

12.6 万 Star，150 万周下载。一行命令喂饱大模型。MarkItDown 解决的，是整个 AI 应用圈心照不宣的痛。

· · ·  ◆  · · ·

01一、那天下午我破防了

上个月帮朋友做一个内部知识库项目。他的团队三年攒了 3000 多份文档——PDF 研报、Word 需求文档、Excel 数据表、PPT 产品方案、还有几百小时的会议录音。

我说行，喂给大模型建个 RAG 知识库呗。

然后噩梦开始了。

第一个 PDF 是扫描件，复制出来的文字像被粉碎机打过；第二个 Excel 里面有 6 个 sheet 的交叉引用表格，粘进文本全塌了；第三个 PPT 里有一张架构图，但除了文件名 “image7.png” 我什么信息也拿不到。Word 文档更是灾难——三级标题变成了一锅粥，列表缩进全部消失。

那天下午我坐在屏幕前，看着自己花了半个小时手动整理一份文档，而 Colab 里的模型运行只用了 30 秒。

我做的事比模型还多。这不是 AI 时代的正确打开方式。

后来我在 GitHub trending 上刷到 MarkItDown——微软 AutoGen 团队开源的文档转 Markdown 工具。一个下午的绝望，被一行命令治愈了。

· · ·  ◆  · · ·

02二、它到底做了什么

MarkItDown 做的事用一句话就能说清：把任何格式的文件，转成保留完整结构的 Markdown。

注意”保留结构”这四个字。市面上不缺文字提取工具——textract 七年前就有了，PDF 解析器一抓一把。但它们做的都是”把文字扒出来”，至于扒出来的是标题还是正文、是列表还是脚注、这行和那行是什么关系——它们不在乎。

MarkItDown 在乎。它会把 Word 的三级标题转换成 ### 层级，把 Excel 的合并单元格转成 Markdown 表格，把 PPT 里的每一页转成一个分区段落，连 PDF 里的超链接都给你留着。

为什么要 Markdown？答案比你想象的简单：主流大模型在 Markdown 上训练过海量数据，它们”天生”就懂 Markdown 的结构。

GPT-5、Claude 4、Gemini 3 不用你告诉它”这段是标题、这是列表”——看到 ## 它就理解层级，看到 |表格| 它就理解数据关系，看到 [链接](url) 它就理解引用。这种理解不是靠 prompt engineering 调出来的，是模型预训练时就内化的。

而且 Markdown 的 Token 效率极高。同样一篇文档，HTML 版本消耗的 Token 可能是 Markdown 的 3-5 倍。在大模型按 Token 计价的今天，这不是小钱。

· · ·  ◆  · · ·

03三、一张表说清它能处理什么

我测了不下 20 种文件类型，只有一种没跑通——加密的 PDF。除此之外全过。

· · ·  ◆  · · ·

04四、30 秒跑通你的第一个转换

pip install 'markitdown[all]'

命令行一行：

markitdown report.pdf -o report.md

Python 代码：

from markitdown import MarkItDown  md = MarkItDown() result = md.convert("quarterly-report.xlsx") print(result.text_content)

就这些。不需要配置 API Key，不需要选模型，不需要处理编码问题。你给它文件路径，它还你 Markdown 字符串。

· · ·  ◆  · · ·

05五、五个功能，每一个都踩在我过去的痛点上

>5.1 图片不丢失——AI 替你”看”图

以前的文档处理管线里，图片是黑洞。PPT 里有一张架构图，解析出来一行 “[image]” 就完事了——这张图里的微服务拓扑、数据流方向、组件依赖，全部蒸发。

MarkItDown 的处理方式让我眼前一亮：把图片送给 LLM 描述，然后把描述文本嵌入 Markdown。

from markitdown import MarkItDown from openai import OpenAI  client = OpenAI() md = MarkItDown(     llm_client=client,     llm_model="gpt-4o", ) result = md.convert("system-architecture.pptx") # 输出里不再是一堆 [image]，而是：# ![架构图](arch.png)# > 该图展示了微服务架构，包含 API Gateway、4个业务服务、# > 一个消息队列（Kafka）和一个 PostgreSQL 数据库...

这意味着你的 RAG pipeline 能”看到”架构图，能回答”这个系统用了什么数据库”这种依赖图片信息的问题。

>5.2 音频直接变文本

pip install 'markitdown[audio-transcription]'

result = md.convert("sprint-retro-meeting.mp3") # 输出：完整的语音转录 + 音频元数据

我拿这个处理了团队过去三个月的 Sprint 回顾会议录音。18 小时的音频，变成了一万多字的可检索文本。结合向量数据库，现在可以问”上次关于登录模块性能的讨论是什么时候？”

>5.3 YouTube 视频字幕一键提取

pip install 'markitdown[youtube-transcription]'

我经常看 PyCon 和 AI 相关的技术分享，以前都是边看边记笔记。现在：

result = md.convert("https://www.youtube.com/watch?v=...")

整个演讲的字幕自动转成 Markdown，可以直接导入 Obsidian 做知识管理。

>5.4 MCP——让 AI 直接”读”文件

这是 MarkItDown 从”开发者工具”变成”AI 基础设施”的关键一步。

在 Claude Desktop 配置里加一段：

{"mcpServers":{"markitdown":{"command":"uvx","args":["markitdown-mcp"]}}}

然后你在 Claude 里说”帮我分析这个 PDF”，Claude 不用你手动复制粘贴——它通过 MCP 直接调用 MarkItDown，自动转换格式，当场分析。

同样的配置在 Claude Code 和 Cursor 里也能用。一套 MCP 服务，所有 AI 客户端通用。

>5.5 企业级 Azure 集成

如果你有 Azure 订阅，MarkItDown 还能接入 Azure Document Intelligence 做高精度扫描件识别，或者用 Azure Content Understanding 做多模态分析——文档、图片、音频、视频一把梭。

最酷的是 Content Understanding 的自定义分析器：你可以训练它识别发票上的 VendorName、InvoiceDate、TotalAmount，然后每次转换发票 PDF 时，这些字段自动提取成 YAML front matter：

---fields:VendorName:CONTOSOLTD.InvoiceDate:'2019-11-15'TotalAmount:$12,400.00---

财务团队直接高潮了。

· · ·  ◆  · · ·

06六、它的插件生态比你想的丰富

MarkItDown 第一天就设计了插件机制。第三方插件默认禁用（安全考虑），用 --use-plugins 手动开。

官方推出的 markitdown-ocr 插件用 LLM Vision 给 PDF 和 Office 文档里的嵌入图片做 OCR：

pip install markitdown-ocr

md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o") result = md.convert("scanned-contract.pdf") # 扫描件合同 → 带 OCR 的 Markdown

GitHub 上搜 #markitdown-plugin 你能找到社区贡献的 Notion、Figma、Jira 等一系列实用转换器。这个生态还在快速膨胀。

· · ·  ◆  · · ·

07七、实战：我是怎么把它嵌进 RAG 管线的

RAG 管线最容易被忽视的环节是最上游的文档解析。下游的 Chunking、Embedding、检索，全依赖上游输入的质量。

我的管线长这样：

原始文档 → MarkItDown（统一转 Markdown）     → 文本分块 → 向量化 → 存入向量库     → LLM 检索增强生成

接入 MarkItDown 之前，每种文件格式要单独写解析器。PDF 用 PyMuPDF，Word 用 python-docx，PPT 用 python-pptx，Excel 用 openpyxl——然后还要写一堆胶水代码把这些解析器的输出格式统一起来。

现在一行 md.convert() 全搞定。

拿那个金融科技团队的内部知识库举例：3000+ PDF 研报、500+ 段分析师电话会议录音、200+ Excel 数据模型。接入 MarkItDown 后：

• 文档处理时间：从每人天 2 小时 → 5 分钟
• 问答准确率：从 61% → 87%
• 他们 CEO 的原话：”我感觉我们终于开始用 AI 了，而不是被 AI 用。”

· · ·  ◆  · · ·

08八、Docker 一把梭

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

容器化之后你可以把它塞进 CI/CD——GitHub Actions 里自动把仓库里的文档转成 Markdown，作为构建步骤的一部分。配合脚本批量处理几百上千文件，零人工干预。

· · ·  ◆  · · ·

09九、三个你该知道的安全原则

MarkItDown 以当前进程权限执行 I/O。在服务端使用时：

永远检验输入

用最窄的 API

插件谨慎开启

· · ·  ◆  · · ·

10十、跟同类工具比，它好在哪

它每项都不是绝对第一，但覆盖面、LLM 集成深度、部署灵活性的综合平衡没有对手。

· · ·  ◆  · · ·

11十一、最后说一句

MarkItDown 的定位很清晰：不是做人类阅读的美化工具，是做 LLM 理解文档的最佳翻译官。

它背后的设计哲学值得每个做 AI 应用的人想想：与其让每个项目自己写文档解析的胶水代码，不如用一个统一的标准中间层。Markdown 就是这个中间层的最佳载体——够结构化让模型理解，够简洁让 Token 高效，够通用让你不用重复造轮子。

如果你是做 RAG、做 AI 应用、做知识库的，把它加到你的 requirements.txt 里。然后去接杯咖啡——等你回来的时候，那 3000 份文档已经全部转完了。

你的 pipeline 会感谢你。就像那天下午的我一样。

· · ·  ◆  · · ·

作者：Daniel Li

GitHub：https://github.com/microsoft/markitdown^[1]项目 Star：12.6 万+ | 协议：MIT