MarkItDown 是什么？微软开源的"万物转 Markdown"神器，让 AI 真正读懂你的文档

把 PDF、PPT、Word、Excel、图片、音频、视频……通通转成 Markdown——这是微软开源的工具 MarkItDown 做的事。

它是一个为 AI 时代设计的文档解析工具——把人类用的文件格式，转成 AI 最爱吃的 Markdown。

先说结论：

MarkItDown 是当下最强的"文档预处理"工具：

• 📦 微软开源（MIT 协议），Python 工具
• 🔄 支持 13+ 种格式：PDF / PPT / Word / Excel / 图片 / 音频 / HTML / YouTube / EPUB …
• 🍬 输出干净的 Markdown，保留结构（标题、列表、表格、链接）
• 🤖 专为 LLM / RAG 设计，节省 token
• 🪄 可选 GPT-4o 做图像描述、Azure Content Understanding 做高精度提取

下面一个个讲。

---

一、MarkItDown 是什么？3 句话讲清

1.1 一句话定位

MarkItDown = 把任意文件转成 Markdown，给 AI "读"。

类比：

• 人类的"通用语言" → 中文
• AI 的"通用语言" → Markdown（+YAML front matter）

MarkItDown 把所有"非 Markdown 文件"转成 AI 最爱吃的格式。

1.2 它跟其他工具的区别

工具	适合	不适合
textract	转文本	不保留结构，写 AI 用乱七八糟
PyMuPDF / pdfplumber	单格式（PDF）	跨格式能力差
Apache Tika	元数据提取	输出 XML，AI 不爱
MarkItDown ✨	多格式 + 保留结构 + AI 友好	—

一句话：「别人是提取文本，MarkItDown 是给 AI 做菜」。

1.3 谁开发的？

• 微软（Microsoft）
• 主要作者：Adam Fourney
• 许可证：MIT（随便用、商用、改造都可以）
• GitHub 星标：27.5k+
• 最新版本：v0.1.6（2026 年 5 月）

---

二、为什么要把文档转 Markdown？

你可能想问："文档本来就是 Markdown 直接给 AI 不行吗？"

现实是：现实文档80% 不是 Markdown。

文档类型	比例（估算）
PDF（合同、论文、报表）	30%
Word / Docx（方案、说明书）	25%
PPT / Pptx（汇报、培训）	10%
Excel（表格、数据）	12%
图片 / 截图	15%
音频 / 视频字幕	5%
Markdown / HTML	3%

也就是说，97% 的"人类文档"AI 直接看不懂。MarkItDown 是这个"翻译官"——把 PDF、PPT、Word 翻成 AI 听得懂的话。

核心原理（1 段话讲清）

1. 解析文件结构
2. 提取关键元素（标题、段落、列表、表格、链接）
3. 把结构化元素按 Markdown 语法输出
4. 对图片、图表用 LLM 生成描述
5. 输出 = LLM 最爱吃的「文本」

为什么是 Markdown？

文件	在 LLM 眼里
PDF 二进制	一坨乱码
Word XML	标签迷宫
HTML	嵌套地狱
Markdown ✨	「说话」一样的格式

OpenAI / Anthropic / Google 的 LLM 在训练时看了海量 Markdown，所以它们：

• ✅ 原生理解 Markdown
• ✅ Markdown 输出的 token 更少（不浪费钱）
• ✅ 在回复中自然带 Markdown（表格、代码块、列表）

所以"转 Markdown" = "节省 token + 让 AI 更懂你"。

---

三、能转什么？13+ 种格式全覆盖

格式	输出	适合
PDF ✅	Markdown（保留标题、表格、链接）	论文 / 合同 / 报表
PowerPoint (.pptx) ✅	每张幻灯片 → Markdown 章节	汇报 / 培训材料
Word (.docx) ✅	完整 Markdown（含标题、表格）	方案 / 说明书
Excel (.xlsx, .xls) ✅	每个 sheet → Markdown 表格	数据 / 财务报表
图片 (JPG, PNG) ✅	EXIF 元信息 + 可选 OCR	截图 / 表格拍照
音频 (WAV, MP3) ✅	EXIF + 语音转写	会议录音 / 播客
HTML ✅	干净的 Markdown	网页抓取
CSV / JSON / XML ✅	结构化 Markdown	数据导入
ZIP 文件 ✅	递归逐个文件转	压缩包整处理
YouTube URL ✅	URL → 视频字幕转 Markdown	学教程
EPUB ✅	电子书 → Markdown	知识库
Outlook 邮件（可选）✅	邮件转 Markdown	企业知识库
Az Doc Intel / Az CU（可选）✅	云端高精度 OCR / 结构化字段	扫描件 / 合同

13+ 种格式——基本上你日常能碰到的文档，它都能转。

---

四、5 分钟上手教程

4.1 安装

需要 Python 3.10+（建议 3.12）。

# 建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate  # Windows 用 .venv\Scripts\activate

# 装全套
pip install 'markitdown[all]'

💡 新手提示：第一次 pip install 'markitdown[all]' 会下载很多依赖（PDF 解析、OCR、音频转写…），需要 2-5 分钟，属正常。

4.2 入门 1：命令行转一个 PDF

# 把 PDF 转到 stdout
markitdown path-to-file.pdf > document.md

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

# 用管道输入（Linux/Mac）
cat path-to-file.pdf | markitdown

输出示例（一份 PDF 转成 Markdown 后的样子）：

# 2025 年年度报告

## 第一节 重要提示

本公司董事会、监事会及董事、监事...

## 第二节 公司基本情况

### 一、公司信息

| 股票简称 | 股票代码 |
|---------|---------|
| 演示公司 | 600000  |
| 股票上市交易所 | 上海证券交易所 |

### 二、联系人
...

看到没？标题层级、表格完全保留——不是"机器一行行抓"。

4.3 入门 2：Python API

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

4.4 入门 3：让 LLM 帮你描述图片

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")

result = md.convert("example.jpg")
print(result.text_content)

效果：图片不只是"提取 EXIF"，而是 GPT-4o 看了图之后写一段描述塞进 Markdown。

---

五、4 个实战场景（让你立刻会用）

5.1 场景 1：把一堆 PDF 喂给 RAG 系统

需求：做一个 "公司内部知识问答" 系统，用 RAG + GPT-4。

难点：RAG 系统只吃 Markdown/文本，PDF 不行。

MarkItDown 解决方案：

import os
from markitdown import MarkItDown

md = MarkItDown()

# 整个文件夹的 PDF → Markdown
for pdf in os.listdir("./docs/"):
    if pdf.endswith(".pdf"):
        result = md.convert(f"./docs/{pdf}")
        
        # 保存
        with open(f"./md/{pdf[:-4]}.md", "w") as f:
            f.write(result.text_content)

print("✅ 所有 PDF 已转 Markdown")

之后把这些 Markdown 灌进 LangChain / LlamaIndex，向量库 + GPT-4 就是个企业知识问答机器人。

5.2 场景 2：把 PDF 论文转 Markdown 喂给 GPT-4 解读

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")

# PDF 论文 + GPT-4o 看图
result = md.convert("paper.pdf")

# 喂给 GPT-4 解读
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": f"请用通俗中文总结这篇论文：\n{result.text_content}"}
    ]
)
print(response.choices[0].message.content)

5.3 场景 3：把 PPT 转 Markdown 用于自动化讲解

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("汇报.pptx")
markdown = result.text_content

# 喂给 LLM，让他把 PPT 转成讲稿
from openai import OpenAI
client = OpenAI()
script = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": f"把这份 PPT 转成 5 分钟口语化演讲稿：\n{markdown}"}
    ]
)
print(script.choices[0].message.content)

5.4 场景 4：从批量图片提取文字（OCR）

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    enable_plugins=True,
    llm_client=client,
    llm_model="gpt-4o"
)

# 一张包含表格的截图
result = md.convert("invoice.jpg")
print(result.text_content)
# 输出：表格内容 + OCR 文字 + GPT-4o 对图表的描述

配合 markitdown-ocr 插件（见下），图里的表格都能识别。

---

六、3 个高级玩法

6.1 OCR 插件（识别 PDF 中的扫描文字）

GitHub 上有官方插件 markitdown-ocr：

pip install markitdown-ocr
pip install openai  # 或任何 OpenAI 兼容 SDK

启用：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o"
)
result = md.convert("扫描件.pdf")
print(result.text_content)

注意：插件 OCR 用 LLM Vision，没有新依赖。

6.2 Azure Content Understanding（云端高精度）

如果你买得起 Azure，用 cu_endpoint 接入：

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")

# 文档用云端多模态
result = md.convert("report.pdf")
print(result.markdown)

支持的格式更多（视频、音频、扫描件），输出还带 YAML front matter：

---
contentType: document
fields:
  VendorName: CONTOSO LTD.
  InvoiceDate: '2024-11-15'
---

# 发票内容...

还能用 custom analyzer（prebuilt 或自定义）提取特定字段：

md = MarkItDown(
    cu_endpoint="...",
    cu_analyzer_id="my-invoice-analyzer"
)
result = md.convert("invoice.pdf")

⚠️ Azure Content Understanding 是 Azure 计费 API。个人小规模玩玩用本地即可。

6.3 Docker 部署

不想装 Python？

docker build -t markitdown:latest .

# 容器化运行
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

服务器端批量转文件特别方便。

---

七、4 类典型用法 + 不适合的场景

7.1 适合 MarkItDown 的

场景	为什么合适
RAG 知识库搭建	把企业 PDF/Word 转 Markdown 入向量库
AI 解读论文 / 法规	喂给 GPT-4 / Claude 让它读
批量处理图片文字	OCR + 描述生成
自动化内容处理	一键把 100 个文件转 Markdown

7.2 不适合 MarkItDown 的

场景	原因	替代方案
要保留原版排版	Markdown 是简化格式	Adobe/Pandoc
要像素级还原	表格只能转 Markdown 表格	pdf2htmlEX
极度复杂的版式（杂志）	Markdown 表达力有限	专业的 PDF 工具
实时 OCR	启动慢、要 LLM 调用	Tesseract

简单说：MarkItDown 是 AI 时代的"预处理工具"，不是"给人看的排版工具"。

---

八、安全与最佳实践

⚠️ MarkItDown 是 Python 进程权限运行的——和 open()、requests.get() 一样。

8.1 3 条安全规则

规则	操作
别传不受信任的输入	处理用户上传的 PDF 时先验证路径
用最窄的 API	只读本地用 convert_local()，别用 convert()
限制网络目标	服务端部署前要先打防火墙规则

8.2 闭坑指南

坑	解决方案
pip install 'markitdown[all]' 一直失败	用国内镜像：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple markitdown[all]
PDF 转出来是空白	PDF 是扫描件 → 装 OCR 插件
转换太慢	关掉 OCR，用默认即可
Markdown 表格乱了	升级到最新版本（pip install --upgrade markitdown）

---

九、和"PDF 转 Word""在线 OCR" 工具的对比

维度	MarkItDown	PDF → Word 在线工具	在线 OCR
目标	AI 友好	给人看	给人看
格式	Markdown	Word	文本
批量	✅ Python	❌ 一份份来	❌
可编程	✅ SDK	❌	❌
token 友好	✅	❌ 浪费	❌
保留结构	✅ 表格/标题	✅ 但 XML	❌
OCR	✅ 可选	❌	✅
价格	免费	免费/付费	付费

一句话总结：

MarkItDown = 给 AI 用的"PDF 转换器 + OCR + LLM 描述生成器" 三合一。

---

十、写在最后

3 年后回看，
"让 AI 读懂人类文档" 可能是 RAG 时代最被低估的技术环节。

MarkItDown 这个工具做的事看起来"不起眼"——把文件转个格式。但实际价值：

• 让企业能用 RAG 整理内部知识
• 让学习者让 AI 解读论文
• 让数据团队批量 OCR 历史扫描件
• 让开发者少写 80% 的文件解析代码

它不"性感"，但它是基础设施——就像高速公路一样，你可能不知道它在哪，但你每天上班都靠它。

---

👇 立刻试试

👉 打开终端跑一句：

pip install 'markitdown[all]'
markitdown ~/Desktop/你的文件.pdf > ~/output.md

5 分钟后，你就有了一份"AI 能读的"文档。

---

有问题评论区告诉我，我帮你看。

我是晚枫，祝你玩得开心。

---

附录 · 关键链接

• 📦 MarkItDown GitHub
• 📖 MarkItDown 官方文档
• 🧩 MarkItDown OCR 插件
• ☁️ Azure Content Understanding
• 🧠 同类工具 textract