microsoft/markitdown

Microsoft AutoGen 团队出品的轻量级 Python 工具，将各类文件和 Office 文档转换为 Markdown，专为 LLM 管道设计。142k stars，Python 实现，MIT 许可证。

定位与 textract 相似，但专注于保留文档结构（标题、列表、表格、链接）以供 LLM 消费，而非高保真人工阅读输出。

支持的输入格式

类别	格式
Office 文档	PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx/.xls）、Outlook（.msg）
图片	EXIF 元数据 + OCR（需 LLM client）
音频	EXIF 元数据 + 语音转写（wav/mp3）
视频	通过 Azure Content Understanding
Web 内容	HTML、YouTube URL（自动获取字幕）
文本格式	CSV、JSON、XML
其他	EPub、ZIP（递归处理内容）

安装

# 安装全部可选依赖
pip install 'markitdown[all]'
 
# 按需安装
pip install 'markitdown[pdf,docx,pptx]'

可选依赖分组：pptx docx xlsx xls pdf outlook az-doc-intel az-content-understanding audio-transcription youtube-transcription

使用方式

CLI

# 基本转换
markitdown path-to-file.pdf > document.md
 
# 指定输出文件
markitdown path-to-file.pdf -o document.md
 
# 管道输入
cat path-to-file.pdf | markitdown
 
# 启用插件
markitdown --use-plugins path-to-file.pdf
markitdown --list-plugins

Python API

from markitdown import MarkItDown
 
# 基本用法
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)
 
# 带 LLM 图片描述（pptx / 图片）
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
 
# Azure Document Intelligence（扫描 PDF / 复杂表格）
md = MarkItDown(docintel_endpoint="<endpoint>")
result = md.convert("scanned.pdf")
 
# Azure Content Understanding（文档/图片/音频/视频统一入口）
md = MarkItDown(cu_endpoint="<cu_endpoint>")
result = md.convert("meeting.mp4")   # 视频 → prebuilt-videoSearch
result = md.convert("call.wav")      # 音频 → prebuilt-audioSearch

Docker

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

云服务对比

能力	内置转换器	Azure Document Intelligence	Azure Content Understanding
文档转换	本地离线	云端布局提取	云端多模态
结构化字段	不支持	不暴露	YAML front matter
音视频	基础音频，无视频	不支持	✅ 音频+视频
费用	本地计算	计费 Azure API	计费 Azure API

插件生态

插件默认关闭，用 --use-plugins 或 enable_plugins=True 启用
第三方插件通过 GitHub hashtag #markitdown-plugin 发现
markitdown-ocr：为 PDF/DOCX/PPTX/XLSX 内嵌图片添加 OCR，复用同一个 llm_client/llm_model
自定义插件参考 packages/markitdown-sample-plugin

安全注意

以当前进程权限执行 I/O。不可信环境中需净化输入，并调用最窄范围的 convert 函数（如 convert_stream()、convert_local() 而非全能的 convert()）。

为何 Markdown

极接近纯文本，token 效率高
主流 LLM（GPT-4o 等）天然”说” Markdown，训练语料大量含 Markdown
保留文档结构（标题/列表/表格/链接），优于纯文本

关联页面

CLI-Anything — 将任意软件转化为 Agent 原生 CLI，与 markitdown 的”文件→文本”思路互补
deepwiki-open — 代码仓库 Wiki 自动生成，同样面向 LLM 消费的文档工具
understand-anything — 将代码库转为知识图谱，markitdown 可用于其文档预处理

zhaoweiguo 的知识库

目录