项目地址：github.com/microsoft/m…
Star 数：108K+ | 当日增长：+1672 | 协议：MIT
最新版本：0.1.0（Breaking Change，升级需注意）
前言
做 RAG 的同学一定深有体会：文档预处理环节往往会吃掉整个项目 60% 以上的精力，PDF 表格错位、Word 嵌套结构丢失、扫描件直接变空白，喂给大模型一团乱文本，检索以及生成的质量会直线崩盘。有没有一个工具可以一劳永逸地把这些异构文档统一转成结构清晰的 Markdown？微软的 MarkItDown 就是冲着这个问题来开展工作的。
一、存在的痛点
异构文档格式五花八门，PDF 以及 Word、PPT、Excel 都各自为政，手动开展预处理工作耗时耗力，还会让格式结构尽失；而大模型偏偏只认可结构清晰的 Markdown，要是输入一团乱文本，推理质量就会骤降。如何把任意格式文档高效、保留结构地转换为 LLM 友好的 Markdown，就是 MarkItDown 要解决的核心问题。
二、MarkItDown 是什么
MarkItDown 是微软 AutoGen 团队所开源的轻量级 Python 工具，可以把 PDF、Word、PowerPoint、Excel、图片、音频、HTML、EPub、ZIP 等 15 种以上的文件格式一键转换为 Markdown，并且在转换过程当中智能保留标题、列表、表格、链接等文档结构，输出的结果既契合人类阅读习惯，同时也特别适宜作为 LLM 的输入来使用。
它的定位十分精准：一个面向 LLM 时代的文档预处理工具，会把各种格式的文件统一转换为结构化的 Markdown。它不是一个简单的格式转换器，同时还是 AI 应用链路当中"数据入口"的基础设施。
三、所支持的文件格式一览
| 类别 | 支持格式 | 说明 |
|---|---|---|
| 办公文档 | Word 也就是 (.docx)、PowerPoint 也就是 (.pptx)、Excel 也就是 (.xlsx) | 核心场景当中，保留标题、列表以及表格等结构 |
| 支持开展文本提取以及表格对齐提取工作，扫描版可以支持 OCR | ||
| 图片 | .jpg、.png 等 | 提取 EXIF 元数据，集成 LLM 来生成图片描述 |
| 音频 | .mp3、.wav 等 | 提取 EXIF 元数据，并且支持进行语音转录 |
| 网页 | HTML | 智能开展正文提取工作，去除导航栏等多余噪音信息 |
| 数据格式 | CSV 以及 JSON 以及 XML | 结构化数据自动映射为 Markdown 表格 |
| 其他 | EPub 以及 ZIP 以及 YouTube URL | 对 ZIP 自动开展内部文件的遍历工作，逐个进行转换 |
特别说一下 ZIP 的处理工作：MarkItDown 会自动遍历压缩包当中的所有文件并且逐一转换，这在进行批量文档处理时极大程度上方便。你把一个包含各种格式文档的 ZIP 放进去，出来就是一个完整的 Markdown 文本。
四、快速上手：从安装到核心 API
4.1 进行安装
要求运用 Python 3.10+ 版本，安装过程非常简洁：
# 基础安装
pip install markitdown
# 按需开展特定格式依赖的安装工作
pip install 'markitdown[pdf, docx, pptx]'
# 一步到位来安装所有依赖
pip install 'markitdown[all]'
0.1.0 版本的一个重要变化是依赖组织方式调整，也就是之前所有格式的依赖都打包在一起，现在拆分成了可选依赖，按需进行安装就可以，不会互相污染。这是一个合理的 Breaking Change，同时让核心包更加轻量。
4.2 命令行的使用
最简单的用法，只需要一条命令就能搞定：
# 进行转换并且输出到终端
markitdown path-to-file.pdf
# 进行转换并把结果保存到文件当中
markitdown path-to-file.pdf -o output.md
# 管道重定向
markitdown path-to-file.pdf > document.md
# 从标准输入当中开展读取工作
cat path-to-file.pdf | markitdown
# 批量开展目录下所有 PDF 的转换工作
find ./documents -name "*.pdf" | xargs markitdown
命令行工具适宜用来快速验证以及开展批量脚本处理工作，日常开发当中用起来非常顺手。
4.3 Python API 的运用
对于需要在代码当中进行集成的场景，MarkItDown 提供了简洁的 Python API：
from markitdown import MarkItDown
md = MarkItDown()
# 转换 PDF
pdf_result = md.convert("annual_report.pdf")
print(pdf_result.text_content)
# 开展 Word 的转换工作
docx_result = md.convert("meeting_notes.docx")
print(docx_result.text_content)
# 对 Excel 进行转换——自动输出为 Markdown 表格
xlsx_result = md.convert("sales_data.xlsx")
print(xlsx_result.text_content)
# 对 URL 直接开展转换工作
url_result = md.convert("https://example.com/document.pdf")
print(url_result.text_content)
API 设计在极大程度上非常直观——convert() 方法会根据文件类型自动选用适宜的转换器，不需要手动进行指定。返回的 result 对象拥有 text_content、title、metadata 以及其他属性，可以直接获取 Markdown 文本。
注意 0.1.0 的一个 Breaking Change：之前的 convert_url() 已经更名为 convert_uri()，并且它现在还支持 data: 以及 file: URI scheme：
# 新的 URI 方式
markitdown = MarkItDown()
result = markitdown.convert_uri("file:///path/to/file.txt")
print(result.markdown)
# 支持 data URI 方面
result = markitdown.convert_uri("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==")
print(result.markdown)
另外，convert() 方法现在不再接受文本文件类对象，比如 io.StringIO，只接受二进制流，升级时务必检查代码。
4.4 对大文件开展流式处理工作
针对超大文件，建议运用流式处理来开展处理工作，避免出现内存溢出的问题：
with open("large_document.pdf", "rb") as f:
result = md.convert_stream(f, file_extension=".pdf")
print(result.text_content)
五、进阶玩法：三大核心增强特性
5.1 接入 LLM，来让图片"开口说话"
这是 MarkItDown 最令人惊艳的特性。借助接入 OpenAI 以及其他多模态大模型，MarkItDown 可以对图片内容开展智能描述工作，还可以对音频进行语音转录：
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI() # 需要配置 OPENAI_API_KEY
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
# 对图片生成开展描述工作
result = md.convert("architecture_diagram.jpg")
print(result.text_content)
# 对音频开展转录工作
audio_result = md.convert("meeting_recording.mp3")
print(audio_result.text_content)
实测下来，针对架构图以及流程图这类技术图片，GPT-4o 的描述质量相当不错，基本能识别出模块名称、箭头方向以及数据流向，不过对于纯文字截图，OCR 的效果会比 LLM 描述更加直接，这个方面后面会进行讲解。
5.2 插件系统：实现无限扩展的可能
0.1.0 版本引入了全新的插件架构，允许第三方开发者扩展 MarkItDown 的功能，这是这个项目从一个工具走向平台的关键一步：
# 命令行开展插件启用工作
markitdown path-to-file.pdf --use-plugins
# 查看可用的插件
markitdown --list-plugins
# Python API 启用插件
md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")
项目内置了一个示例插件 markitdown-ocr，为 PDF、DOCX、PPTX、XLSX 转换器添加了 OCR 支持，运用 LLM Vision 从嵌入图像当中提取文本，不需要新的 ML 库或者二进制依赖。这意味着你不需要安装 Tesseract 或 EasyOCR 这些重量级依赖，只需要一个 LLM API Key 就能来获得 OCR 能力。
安装 OCR 插件的工作：
pip install markitdown-ocr
插件系统的开放性意味着，如果遇到 MarkItDown 原生不支持的格式，完全可以自己编写插件来实现扩展，同时不需要 fork 整个项目。
5.3 MCP 协议：接入 AI Agent 工作流当中
MarkItDown 还拥有 MCP 也就是 Model Context Protocol 服务器包的功能，可以借助它把文档转换能力直接集成到 Claude Desktop 以及 Cursor 等 AI 应用当中：
# 进行 MCP 包的安装
pip install markitdown-mcp
# 启动 MCP 服务器，也就是 stdio 模式，适配 Claude Desktop
markitdown-mcp
# HTTP 模式
markitdown-mcp --http --host 127.0.0.1 --port 3001
同时也支持运用 Docker 来进行部署：
docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest
实测体验：在 Claude Desktop 当中进行 MarkItDown MCP 配置后，直接丢一个 PDF 文件让 AI 分析，AI 会自动调用 MarkItDown 先转成 Markdown 再去处理工作，整个过程完全无感。这对 AI Agent 工作流来说，是"干净输入"的关键基础设施。
安全提醒：有安全研究人员发现 MarkItDown MCP 服务器在早期版本当中存在 URI 验证缺失的问题，攻击者可以借助 SSRF 读取 AWS 凭证这类敏感信息。建议选用最新版本，并且在生产环境中做好网络隔离以及权限控制工作。
六、最新的重磅更新：PDF 表格开展对齐提取以及 OCR 层服务工作
这两个功能是最近几个版本的重磅更新，同时也是社区呼声最高的需求，值得单独拿出来进行说明。
6.1 PDF 表格对齐提取也就是 Aligned Markdown
之前的版本在提取 PDF 表格时，经常会出现列对不齐、数据错位的问题。新版本借助改进 pdfminer.six 的依赖以及表格提取逻辑，得以实现对齐的 Markdown 表格输出：
md = MarkItDown()
result = md.convert("financial_report.pdf")
# 表格的输出现在已经是对齐的 Markdown 格式
print(result.text_content)
对齐后的表格在 LLM 当中的解析准确率得到了显著提升，尤其是财务报表以及数据统计这类对表格精度要求极高的场景。
6.2 OCR 层服务
新版本增加了针对嵌入图片以及 PDF 扫描件的 OCR 层服务。当 PDF 当中包含扫描件图片时，MarkItDown 会自动检测并且调用 OCR 来进行文字识别：
# 运用 Azure Document Intelligence 来进行 OCR
markitdown document.pdf -d -e "<your_azure_endpoint>" -o output.md
# 或是运用 OCR 插件，也就是基于 LLM Vision 的插件
md = MarkItDown(enable_plugins=True)
result = md.convert("scanned_document.pdf")
OCR 层服务的引入，让 MarkItDown 终于能够完整去处理扫描件 PDF 的工作，而不只是跳过图片区域。这是它从文本提取工具迈向文档理解工具的关键一步。
七、以及和同类工具的对比
| 维度 | MarkItDown | Pandoc | textract | Unstructured |
|---|---|---|---|---|
| 定位 | LLM 文档预处理 | 通用格式转换 | 文本提取 | 文档解析平台 |
| 格式覆盖 | 15+ 种 | 范围极广（50+） | 约 10 种 | 广 |
| 输出格式 | Markdown | 多种 | 纯文本 | JSON/CSV |
| LLM 优化 | 专门设计 | 无 | 无 | 部分支持 |
| LLM 集成 | 原生支持 GPT-4o | 无 | 无 | 需要进行额外配置 |
| OCR 支持 | 内置（插件以及 Azure） | 需要借助外部工具 | 需要借助外部工具 | 内置 |
| 插件系统 | 拥有该特性，也就是 0.1.0 版本新增 | Filter 机制 | 无 | 无 |
| MCP 支持 | 有 | 无 | 无 | 无 |
| 学习成本 | 极低 | 较高 | 低 | 中等 |
| 安装复杂度 | pip 一键安装 | 需要借助 Haskell | 体量轻量 | 依赖较重 |
| 维护方 | 微软官方 | 社区 | 社区 | 社区 |
可以看到，MarkItDown 的核心差异化特性在于：输出格式天然对 LLM 友好，以及 LLM 增强，以及 MCP 集成。它并不是要去替代 Pandoc 这样的通用格式转换工具，而是在文档到 Markdown 再到 LLM 这条链路当中做到了极致。
八、总结
MarkItDown 的出现，本质上开展解决的是 AI 时代的"数据入口"问题。LLM 再强大，如果输入的是一团没有结构的文本，它的推理能力也会在极大程度上打折扣。MarkItDown 借助把各种格式的文档统一转换为结构化的 Markdown，为 LLM 提供了高质量的"食物"。
从 0.0.1 到 0.1.0，MarkItDown 的进化路径是非常清晰的：从单一工具到可扩展平台——插件系统让第三方开发者可以去扩展格式支持工作，MCP 协议让 AI Agent 可以进行无缝调用，OCR 层服务让扫描件不再成为盲区。108K 的 Star 数以及活跃的社区迭代，同时也证明了它在开发者心中的地位。
适宜以下人群马上上手：
- RAG 开发者：统一文档格式，提升检索质量，减少预处理的工作量
- AI Agent 开发者：借助 MCP 进行集成，让 Agent 直接对文档内容开展理解工作
- 技术博主以及文档工程师：可以快速把 Word、PDF 转为 Markdown，告别手动搬运工作
- 企业开展知识管理工作：批量转换内部文档，构建统一的知识库
pip install markitdown[all]
只需要一行命令，就可以开启高效文档转换之旅。
项目地址：github.com/microsoft/m…
MCP 服务器：github.com/microsoft/m…
OCR 插件：github.com/microsoft/m…
协议：MIT License（可以商用）
本文基于 MarkItDown 0.1.0 版本来开展撰写，项目仍在进行快速的迭代，建议关注 GitHub 仓库来获取最新动态。如果这篇文章对你有帮助，可以点赞收藏，同时也欢迎在评论区分享你的使用场景，会挑选一些高价值场景后续整理成进阶实战指南。
