MarkItDown：微软开源文档转Markdown工具，91K星，专为RAG管道打造

发表于

MarkItDown 是微软研究院开源的轻量级 Python 工具，专门用于将各类文档格式批量转换为干净的 Markdown 格式，专为 LLM 和 RAG 管道设计。该项目诞生于 AutoGen 框架的开发过程中，最初用于支撑 GAIA 基准评测的 AI Agent 数据处理需求。2024 年底开源后迅速获得社区关注，目前已在 GitHub 累计超过 91,000 颗星，是微软最受欢迎的 Python 开源项目之一。

在 AI 应用开发中，数据格式是个绕不开的问题。你的知识库可能分散在 Word 文档、PPT 演示、Excel 表格和 PDF 报告中——这些格式对人类友好，但对 LLM 来说充满了无意义的 XML 标签和排版元数据。你需要一种既能保留文档结构、又能被 AI 高效处理的中间格式。这就是 MarkItDown 存在的意义。

支持哪些格式？

MarkItDown 目前支持转换以下格式：

格式类型 扩展名 说明
📄 Office 三件套 DOCX / PPTX / XLSX / XLS Word、PowerPoint、Excel
📰 PDF .pdf 含文本提取
🖼️ 图片 .jpg / .png 等 EXIF 元数据 + OCR
🔊 音频 .mp3 / .wav 语音转录（需安装 audio-transcription）
🌐 网页 .html HTML 转 Markdown
📦 其他文本 .csv / .json / .xml 结构化文本
📚 电子书 .epub 电子书格式
🎬 YouTube 视频 URL 自动抓字幕转 Markdown
📁 ZIP .zip 自动解压并批量转换

快速上手

安装

1
2
3
4
5
# 安装全部格式支持
pip install 'markitdown[all]'

# 或者按需安装（减少依赖体积）
pip install 'markitdown[pdf,docx,pptx]'

💡 提示：MarkItDown 要求 Python 3.10 及以上版本，推荐使用虚拟环境隔离依赖。

命令行转换

1
2
3
4
5
6
7
8
# 输出到标准输出
markitdown path-to-file.pdf

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

# 管道输入
cat path-to-file.pdf | markitdown

Python 代码使用

1
2
3
4
5
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.docx")
print(result.text_content)

LLM 图像描述（PowerPoint / 图片）

1
2
3
4
5
6
7
8
9
10
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)
result = md.convert("slides.pptx")
print(result.text_content)

OCR 插件（图片文字识别）

1
pip install markitdown-ocr openai
1
2
3
4
5
6
7
8
9
10
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")
print(result.text_content)

Docker 使用

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

为什么选择 MarkItDown？

Token 效率远超 HTML / XML

LLM 原生”说”Markdown。GPT-4o 和 Claude 都接受过大量 Markdown 格式的文本训练（主要来源：GitHub 技术文档、Stack Overflow 问答、README 文件），因此对 Markdown 语法有着极深的理解。在 RAG 管道中，使用 Markdown 的文档比使用原始 HTML 或 XML 的文档，token 消耗更低、信息密度更高。

以一篇 5,000 词的技术文档为例：原始 HTML 格式约消耗 18,000 tokens，同一文档转为 Markdown 后仅消耗约 7,000 tokens，节省超过 60% 的上下文空间。这意味着你可以将更多文档塞入同样的上下文窗口，或者让相同预算处理更长的文档。

一个具体对比：<h1 class="title"> 标签占 23 个 token，而 Markdown 的 # 只需 3 个 token——单条标题就节省了 87% 的 token 开销。

保留文档结构，适合 RAG 分块

Markdown 通过 # 标题、## 二级标题、表格、列表等语法提供自然的语义层级。RAG 系统（如 LangChain、LlamaIndex）在处理 Markdown 文档时，可以按逻辑章节分块，而不是按固定 token 数强行切割，从而生成更精确的向量嵌入，减少检索和生成阶段的幻觉。

社区活跃，插件生态丰富

MarkItDown 支持第三方插件扩展。通过 GitHub 搜索 #markitdown-plugin 可以找到社区贡献的插件。官方还提供了 markitdown-sample-plugin 示例包，方便开发者自行扩展。

关键要点

📌 使用 MarkItDown 之前，你需要知道的三件事：

  1. 专注 Markdown 输出：与 textract 等通用文本提取工具不同，MarkItDown 输出保留完整文档结构（标题、表格、列表、链接），最适合 AI 场景
  2. 可选依赖分组安装：不要一次性安装全部格式依赖，按需安装 [pdf,docx,pptx] 即可，减少 Docker 镜像体积
  3. 安全注意：MarkItDown 以当前进程权限执行 I/O，不要将不可信来源的文件直接传入，优先使用 convert_local() 而非 convert()

总结

MarkItDown 是一个专为 AI 时代设计的文档转换工具，用一行命令或几行 Python 代码，就能把分散的 Word、PDF、PPT、Excel 整理成 AI-ready 的 Markdown。如果你正在搭建 RAG 管道、构建知识库，或只是想让 LLM 更好地理解你的文档，MarkItDown 值得一试。

👉 GitHub 地址：https://github.com/microsoft/markitdown