MarkItDown — 微软开源的文件转 Markdown 利器
做 LLM 应用的人大概都遇到过同一个头疼问题：用户丢过来一个 PDF、一个 Word、一张截图、一段录音，然后问你"能不能帮我总结一下？"
每种格式都要找对应的解析库，PDF 用 PyMuPDF、Word 用 python-docx、Excel 用 openpyxl、图片还得上 Tesseract OCR……写完一堆胶水代码，发现提取出来的文本结构全丢了——标题变普通段落、表格变乱码、链接直接蒸发。
微软开源的 MarkItDown 就是来解决这个问题的。
一句话概括
MarkItDown 是一个 Python 工具，把各种文件格式统一转成结构化的 Markdown 文本。
PDF → Markdown，Word → Markdown，Excel → Markdown（表格保留），图片 → Markdown（OCR + EXIF），音频 → Markdown（语音转文字），甚至 YouTube 链接 → Markdown（字幕）。
一行命令搞定：
markitdown report.pdf -o report.md
支持哪些格式？
| 格式 | 说明 |
|---|---|
| 提取文本，保留结构 | |
| Word (.docx) | 标题、列表、表格都保留 |
| Excel (.xlsx / .xls) | 表格转 Markdown 表格 |
| PowerPoint (.pptx) | 每页内容提取 |
| 图片 | OCR 提取文字 + EXIF 元数据 |
| 音频 (.wav / .mp3) | 语音转文字 |
| HTML | 转 Markdown |
| CSV / JSON / XML | 结构化转义 |
| ZIP | 解压后递归处理内部文件 |
| YouTube URL | 提取字幕 |
| EPUB | 电子书文本 |
为什么是 Markdown？
官方 README 里有一段解释得很好：
Markdown 极度接近纯文本，但保留了重要的文档结构（标题、列表、表格、链接等）。主流 LLM 原生"说"Markdown，而且 Markdown 的 token 效率很高。
简单说：LLM 吃 Markdown 最香。 纯文本丢了结构，HTML 太臃肿，Markdown 刚刚好。
快速上手
安装
pip install 'markitdown[all]'
[all] 会装所有可选依赖。如果你只需要处理部分格式，可以按需安装：
pip install 'markitdown[pdf, docx, xlsx]'
命令行用法
# 基本用法
markitdown report.pdf > report.md
# 指定输出文件
markitdown report.pdf -o report.md
# 管道输入
cat report.pdf | markitdown
Python API
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.docx")
print(result.text_content)
处理 Excel 文件，表格会自动转成 Markdown 格式：
result = md.convert("data.xlsx")
# 输出：
# | 姓名 | 部门 | 薪资 |
# |------|------|------|
# | 张三 | 技术 | 20k |
用 LLM 描述图片
给图片加 llm_client，可以用 GPT-4o 等模型生成图片描述：
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o")
result = md.convert("screenshot.jpg")
print(result.text_content)
# 输出：[Image: A screenshot showing a dashboard with charts...]
进阶玩法
OCR 插件
官方提供了 markitdown-ocr 插件，用 LLM Vision 从 PDF/Word/PPT/Excel 的嵌入图片中提取文字：
pip install markitdown-ocr
pip install openai
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o")
result = md.convert("scanned.pdf") # 扫描件 PDF 也能处理
Azure Document Intelligence
如果文档质量差（扫描件、复杂排版），可以用 Azure 的文档智能服务：
markitdown report.pdf -o report.md -d -e "<document_intelligence_endpoint>"
云端分析，质量更高，但需要 Azure 账号和 API 调用费用。
Azure Content Understanding
更强大的云端方案，支持音视频、结构化字段提取（发票金额、合同条款等），输出带 YAML front matter：
md = MarkItDown(cu_endpoint="<endpoint>", cu_analyzer_id="my-invoice-analyzer")
result = md.convert("invoice.pdf")
# 输出包含：
# ---
# fields:
# VendorName: CONTOSO LTD.
# InvoiceDate: '2019-11-15'
# ---
Docker 运行
不想装 Python 依赖？用 Docker：
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < report.pdf > output.md
在 LLM 工作流中的位置
MarkItDown 的定位很清晰——格式转换层。
用户文件 (PDF/Word/Excel/图片/音频)
↓
MarkItDown ← 统一转成 Markdown
↓
LLM / RAG / 知识库
典型场景：
- RAG 管道预处理：用户上传各种文件，MarkItDown 统一转 Markdown 后存入向量数据库
- 知识库构建：把公司文档库批量转 Markdown，给 LLM 做检索增强
- 批量文档分析：100 份合同 PDF → 100 份 Markdown → LLM 批量审查
- Hermes Agent 集成：让 Hermes 具备处理 Office/PDF 文件的能力
跟 textract 对比
官方说 MarkItDown 最接近 textract，但核心区别在于：
- textract：目标是提取纯文本，结构基本丢失
- MarkItDown：目标是保留文档结构（标题层级、列表、表格、链接），输出 Markdown
如果你的下游是 LLM，MarkItDown 的结构化输出明显更有价值。
注意事项
- 设计给 LLM 消费，不是给人看的：输出质量足够 readable，但别指望完美排版
- 安全提示：MarkItDown 以当前进程权限执行 I/O，处理不可信文件要注意
- Python 3.10+：需要较新的 Python 版本
- 推荐虚拟环境：避免依赖冲突
总结
MarkItDown 是那种"用了就回不去"的工具。以前要写一堆格式解析胶水代码，现在 pip install + 一行命令搞定。
如果你在做 LLM 应用、RAG 系统、或者只是经常需要把各种文件丢给 AI 处理，MarkItDown 值得加到工具链里。
项目地址：https://github.com/microsoft/markitdown
安装：pip install 'markitdown[all]'
一句话：把任何文件变成 LLM 能吃的 Markdown。