一天一个开源项目（第50篇）：MarkItDown - Microsoft 开源的文件转 Markdown 工具，支持 PDF、Office、图片、音频等 15

引言

"Convert various files to Markdown for use with LLMs and related text analysis pipelines."

这是「一天一个开源项目」系列的第 50 篇文章。今天介绍的项目是 MarkItDown（GitHub）。

需要将 PDF、Word、PPT、Excel 等文件转换为 Markdown 供 LLM 使用？手动转换效率低，格式丢失严重？MarkItDown 是 Microsoft 开源的轻量级 Python 工具，用于将各种文件和 Office 文档转换为 Markdown：支持 PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV/JSON/XML、ZIP、YouTube URLs、EPUB 等 15+ 种格式，专为 LLM 和文本分析管道设计，保留重要文档结构（标题、列表、表格、链接等），支持插件系统、Azure Document Intelligence、LLM 图像描述。

为什么值得看？

• 🚀 轻量级工具：Python 3.10+，简单易用
• 📚 15+ 格式支持：PDF、Office、图片、音频、HTML、ZIP、YouTube、EPUB 等
• 🎯 专为 LLM 设计：保留文档结构，Markdown 格式，token 高效
• 🔌 插件系统：支持第三方插件扩展功能
• ☁️ Azure 集成：支持 Azure Document Intelligence
• 🧠 LLM 增强：支持 LLM 图像描述（OpenAI GPT-4o 等）
• 🐳 Docker 支持：容器化部署

你将学到什么

• MarkItDown 的定位与「专为 LLM 设计」的理念
• 支持的输入格式和转换能力
• 插件系统：如何开发和使用第三方插件
• Azure Document Intelligence 集成
• LLM 图像描述功能
• 与同类工具（textract、pandoc 等）的对比

前置知识

• 了解 Python 3.10+ 的基本使用
• 对 Markdown 格式有基本了解
• 对 LLM 和文本分析有基本认识（可选）

---

项目背景

项目简介

MarkItDown 是 Microsoft 开源的轻量级 Python 工具，用于将各种文件转换为 Markdown，专为 LLM 和文本分析管道设计。它最接近 textract，但专注于保留重要文档结构和内容为 Markdown（包括：标题、列表、表格、链接等）。

核心特点：

• 轻量级：Python 3.10+，简单易用
• 多格式支持：支持 15+ 种输入格式
• 结构保留：保留文档结构（标题、列表、表格、链接等）
• 专为 LLM：Markdown 格式，token 高效，主流 LLM 原生支持
• 插件系统：支持第三方插件扩展功能
• Azure 集成：支持 Azure Document Intelligence
• LLM 增强：支持 LLM 图像描述

解决的核心问题：

• 文件格式转换需要手动操作，效率低
• 转换后格式丢失，结构不清晰
• LLM 需要结构化的 Markdown 格式
• 不同格式需要不同工具，学习成本高

面向的用户：

• 需要将文件转换为 Markdown 供 LLM 使用的开发者
• 构建文本分析管道的团队
• 需要批量处理文档的用户
• 需要 OCR 和图像识别的用户

作者/团队介绍

• 团队：Microsoft（GitHub）
• 背景：Microsoft AutoGen Team 开发维护
• 理念：专为 LLM 和文本分析管道设计
• 官网：PyPI 包，GitHub 开源

项目数据

• ⭐ GitHub Stars: 约 90.7k
• 🍴 Forks: 约 5.4k
• 📦 版本: v0.1.5（持续更新中，303+ commits）
• 📄 License: MIT
• 🌐 PyPI: markitdown
• 💬 社区: GitHub Issues、GitHub Discussions
• 📚 文档: GitHub README

技术栈：

• 语言: Python（99.7%）、Dockerfile（0.3%）
• Python 版本: 3.10+
• 核心特性: 插件系统、Azure Document Intelligence、LLM 图像描述

---

主要功能

核心作用

MarkItDown 的核心作用是：将各种文件转换为 Markdown，专为 LLM 和文本分析管道设计，让用户能够：

1. 文件格式转换：PDF、Office、图片、音频等 → Markdown
2. 结构保留：保留文档结构（标题、列表、表格、链接等）
3. LLM 友好：Markdown 格式，token 高效，主流 LLM 原生支持
4. 批量处理：支持 ZIP 文件批量转换
5. OCR 支持：图片 OCR、PDF 扫描件 OCR
6. 音频转录：音频文件自动转录为文本

使用场景

1. LLM 文档处理

   • 将 PDF、Word、PPT 转换为 Markdown 供 LLM 分析
   • 保留文档结构，提高 LLM 理解准确性

2. 文本分析管道

   • 构建文本分析管道，统一输入格式
   • 批量处理多种格式文档

3. 文档数字化

   • 扫描 PDF OCR 转换为 Markdown
   • 图片 OCR 提取文字

4. 内容提取

   • YouTube 视频字幕提取
   • 音频文件转录

5. 批量转换

   • ZIP 文件批量转换
   • 多格式文档统一处理

快速开始

安装：

# 安装所有可选依赖
pip install 'markitdown[all]'

# 或只安装特定格式的依赖
pip install 'markitdown[pdf, docx, pptx]'

命令行使用：

# 基本用法
markitdown path-to-file.pdf > document.md

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

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

Python API：

from markitdown import MarkItDown

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

Docker 使用：

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

核心特性

1. 支持的输入格式（15+ 种）

   • 📄 PDF：支持扫描件 OCR（需 Azure Document Intelligence 或插件）
   • 📊 PowerPoint：.pptx 文件转换
   • 📝 Word：.docx 文件转换
   • 📈 Excel：.xlsx、.xls 文件转换
   • 🖼️ 图片：JPEG/PNG/GIF，支持 EXIF 元数据和 OCR
   • 🎵 音频：WAV/MP3，支持 EXIF 元数据和语音转录
   • 🌐 HTML：网页内容转换
   • 📊 结构化数据：CSV、JSON、XML
   • 📦 ZIP：批量处理压缩包内容
   • 📺 YouTube URLs：视频字幕提取
   • 📚 EPUB：电子书转换
   • 📧 Outlook：邮件消息转换（需 [outlook] 依赖）

2. 可选依赖

   • [all]：安装所有可选依赖
   • [pptx]：PowerPoint 文件支持
   • [docx]：Word 文件支持
   • [xlsx]：Excel 文件支持
   • [xls]：旧版 Excel 文件支持
   • [pdf]：PDF 文件支持
   • [outlook]：Outlook 消息支持
   • [az-doc-intel]：Azure Document Intelligence 支持
   • [audio-transcription]：音频转录支持
   • [youtube-transcription]：YouTube 视频字幕提取支持

3. 插件系统

   • 支持第三方插件扩展功能
   • 插件默认禁用，需显式启用
   • 使用 #markitdown-plugin 标签搜索插件
   • 示例插件：markitdown-ocr（OCR 支持）

4. Azure Document Intelligence

   • 使用 Microsoft Document Intelligence 进行转换
   • 命令行：markitdown path-to-file.pdf -o document.md -d -e "<endpoint>"
   • Python API：MarkItDown(docintel_endpoint="<endpoint>")

5. LLM 图像描述

   • 使用 LLM（如 OpenAI GPT-4o）生成图像描述
   • 支持 pptx 和图片文件
   • 提供 llm_client 和 llm_model 参数

6. MCP 服务器

   • 提供 MCP（Model Context Protocol）服务器
   • 可与 Claude Desktop 等 LLM 应用集成
   • 详见 markitdown-mcp

项目优势

对比项	MarkItDown	textract	pandoc
定位	✅ 专为 LLM 设计	⚠️ 通用文本提取	⚠️ 文档转换
结构保留	✅ 保留 Markdown 结构	⚠️ 纯文本	✅ 保留格式
LLM 友好	✅ Markdown，token 高效	⚠️ 纯文本	⚠️ 其他格式
插件系统	✅ 支持	❌ 无	⚠️ 有限
Azure 集成	✅ 支持	❌ 无	❌ 无
LLM 增强	✅ 图像描述	❌ 无	❌ 无
批量处理	✅ ZIP 支持	⚠️ 有限	⚠️ 有限
学习曲线	✅ 简单易用	⚠️ 中等	⚠️ 复杂

为什么选择 MarkItDown？

• 专为 LLM 设计：Markdown 格式，token 高效，主流 LLM 原生支持
• 结构保留：保留文档结构（标题、列表、表格、链接等）
• 多格式支持：支持 15+ 种输入格式
• 插件系统：支持第三方插件扩展功能
• Microsoft 维护：90.7k stars，持续更新

---

项目详细剖析

架构设计

MarkItDown 采用模块化 + 插件化架构设计：

核心组件：

MarkItDown
├── DocumentConverter（文档转换器）
│   ├── PDFConverter
│   ├── PPTXConverter
│   ├── DOCXConverter
│   ├── XLSXConverter
│   ├── ImageConverter
│   ├── AudioConverter
│   ├── HTMLConverter
│   └── ...（其他转换器）
├── Plugin System（插件系统）
│   ├── markitdown-ocr（OCR 插件）
│   └── ...（第三方插件）
├── Azure Integration（Azure 集成）
│   └── Document Intelligence
└── LLM Integration（LLM 集成）
    └── Image Description

设计原则：

• 模块化：每个格式有独立的转换器
• 插件化：支持第三方插件扩展功能
• 可选依赖：按需安装，减少依赖冲突
• 流式处理：支持文件流输入，不创建临时文件

为什么选择 Markdown？

Markdown 的优势：

1. 接近纯文本：最小化标记，易于阅读
2. 保留结构：标题、列表、表格、链接等结构信息
3. LLM 原生支持：主流 LLM（如 GPT-4o）原生支持 Markdown
4. Token 高效：Markdown 约定高度 token 高效
5. 广泛使用：LLM 训练数据中包含大量 Markdown 格式文本

插件系统

插件开发：

参考 packages/markitdown-sample-plugin 开发插件。

插件使用：

# 列出已安装插件
markitdown --list-plugins

# 启用插件
markitdown --use-plugins path-to-file.pdf

markitdown-ocr 插件：

from markitdown import MarkItDown
from openai import OpenAI

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

插件为 PDF、DOCX、PPTX、XLSX 转换器添加 OCR 支持，使用 LLM Vision 从嵌入图像中提取文本，无需新的 ML 库或二进制依赖。

Azure Document Intelligence

设置 Azure Document Intelligence：

1. 创建 Azure Document Intelligence 资源
2. 获取端点 URL 和密钥
3. 使用 -d -e "<endpoint>" 参数

命令行使用：

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Python API：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

LLM 图像描述

使用 LLM 生成图像描述：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="optional custom prompt"
)
result = md.convert("example.jpg")
print(result.text_content)

支持的文件类型：

• PPTX：提取幻灯片中的图像并生成描述
• 图片文件：直接生成图像描述

流式处理

v0.1.0 重大变更：

• convert_stream() 现在需要二进制文件流对象（如以二进制模式打开的文件，或 io.BytesIO 对象）
• DocumentConverter 类接口改为从文件流读取，而不是文件路径
• 不再创建临时文件

优势：

• 内存效率更高
• 支持管道输入
• 适合批量处理

MCP 服务器

MarkItDown 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop 等 LLM 应用集成。

详见 markitdown-mcp 项目。

---

项目地址与资源

官方资源

• 🌟 GitHub: github.com/microsoft/m…
• 📦 PyPI: markitdown
• 📚 文档: GitHub README
• 💬 社区: GitHub Issues、GitHub Discussions
• 🔌 MCP 服务器: markitdown-mcp

相关资源

• Azure Document Intelligence: Azure 文档
• OpenAI: openai.com
• textract: textract.readthedocs.io
• pandoc: pandoc.org

适用人群

• LLM 开发者：需要将文件转换为 Markdown 供 LLM 使用
• 文本分析工程师：构建文本分析管道
• 文档处理用户：需要批量处理多种格式文档
• OCR 用户：需要图片和扫描 PDF OCR
• 内容提取用户：需要从 YouTube、音频等提取内容

学习价值：

• ✅ 文件格式转换的最佳实践
• ✅ Markdown 格式在 LLM 中的应用
• ✅ 插件系统的设计和实现
• ✅ Azure Document Intelligence 集成
• ✅ LLM 图像描述的应用
• ✅ 流式处理和批量处理

---

欢迎来我中的个人主页找到更多有用的知识和有趣的产品