cat REAMDMe.md
markitdown
微软开源的文档转 Markdown 瑞士军刀 —— 一行命令把 PDF、Word、PPT、Excel、网页、音频、YouTube 全转成 LLM 友好的结构化 Markdown。135K Star，MIT 协议，零成本运行。
// 目录
// 概览
// 为什么需要它
先聊个真实的场景。我每天跑 GitHub AI 日报，素材来源千奇百怪：有的项目只有 README、有的是 PDF 论文、有的是 Word 技术报告、有的是网页博客、有的还带 YouTube 讲解视频。把这些东西全扒下来喂给 AI 做分析——光预处理就能耗掉一个上午。
做过 RAG 的人都知道这个痛点：要把非结构化文档塞进向量数据库，第一步永远是「转成纯文本」。这一步看起来简单，实际上鬼故事很多：PDF 转出来的文字顺序是乱的、Word 的表格被拆成了段落、Excel 公式全丢、PPT 的图片描述靠猜。
微软 AutoGen 团队搞的这个 markitdown，解决的就是这件事——而且解决的思路很聪明：不是生硬地把文档抽成 plain text，而是保留结构转成 Markdown。标题还是标题，表格还是表格，链接还是链接。LLM 天生就吃 Markdown 吃得很好，token 利用率也比 plain text 高得多。
项目自己在 README 里说得很直白："While the output is often reasonably readable, it is primarily intended for text analysis tools, not high-fidelity human-facing document conversion." ——不是给你做精美排版的，是给 AI 当饲料的。这个定位非常精准。
// 核心能力
markitdown 能处理的格式，按类别列一下：
| 类别 | 格式 | 原理 |
|---|---|---|
| 文档 | PDF、Word (.docx)、PowerPoint (.pptx)、EPub | 格式原生解析 + 可选 LLM 图片描述 |
| 电子表格 | Excel (.xlsx, .xls) | OpenXML 解析，保留表格结构 |
| 图片 | 图片文件（含 EXIF 元数据 + OCR） | 基础元数据提取，OCR 通过插件扩展 |
| 音频 | WAV / MP3 | EXIF 元数据 + 语音转录 |
| 网页 | HTML | DOM 解析转 Markdown |
| 数据 | CSV、JSON、XML | 结构化转表格化 Markdown |
| 压缩包 | ZIP | 递归遍历，逐个文件转换 |
| 在线 | YouTube URL | 字幕转录提取 |
可以看到覆盖范围相当广——从办公文档到多媒体，从本地文件到远程 URL，基本把「需要喂给 LLM 的东西」一网打尽了。
对了，还支持插件系统。默认提供了 markitdown-ocr 插件，能调 LLM Vision 从嵌入图片里扒文本。第三方插件在 GitHub 搜 #markitdown-plugin 标签就能找到。
// 快速上手
安装
一行搞定：
前置要求：Python 3.10+。建议用 venv 隔离环境。
命令行用法
Python API
// 架构设计
markitdown 的架构其实不复杂，核心思路是格式检测 → 路由到对应转换器 → 输出结构化 Markdown。
它是个 monorepo，核心包在 packages/markitdown，另外拆出了 markitdown-ocr 和 markitdown-sample-plugin 两个独立包。
几个设计点值得注意：
- 无 ML 依赖：基础转换全部走 XML/二进制解析，零 GPU，不需要模型。只在可选的 LLM 图片描述和 Azure 集成时才需要外部 AI 服务。这点在部署上非常友好——放服务器上跑不会吃显存。
- 插件默认禁用：第三方插件要手动
enable_plugins=True才会加载，安全面先拦一道。 - 四级 API 暴露面：
convert()（最宽松，支持本地文件/URL/字节流）、convert_local()（仅本地文件）、convert_response()（HTTP 响应对象）、convert_stream()（自行管理流）。这个分层设计对服务端部署很重要——你可以根据安全需求选最窄的 API。 - LLM 注入模式：通过
llm_client/llm_model参数注入任何 OpenAI 兼容客户端，不绑死某个模型。
// 处理流水线
// Azure 集成 — 把云端能力接进来
markitdown 虽然是本地优先，但也没把云端能力完全丢掉。它接了两个 Azure 服务：
| 服务 | 适用场景 | 关键能力 |
|---|---|---|
| Azure Document Intelligence | 扫描 PDF、复杂表格、多页文档 | 布局提取，结构保留更好 |
| Azure Content Understanding | 音频/视频处理、结构化字段提取 | 零配置自动路由（文档→documentSearch、视频→videoSearch、音频→audioSearch），自定义分析器提取发票/合同字段 |
Content Understanding 是这里面比较有意思的一个——视频文件只有走它才能转。而且它支持自定义分析器，比如你搞了个发票分析器，传入 cu_analyzer_id 就能直接输出 YAML front matter 里的结构化字段：VendorName、InvoiceDate 这些东西。这块对企业用户来说挺实用的。
不过要注意——这些都是按量计费的 Azure API 调用，不是免费的。基础转换还是纯本地计算。
// 竞品对比
文档转 Markdown 这个赛道说大不大说小不小，markitdown 的几个主要竞品各有各的侧重点：
| 工具 | Stars | 核心定位 | 优势 | 劣势 |
|---|---|---|---|---|
| microsoft/markitdown | 135K | 轻量 Office → Markdown | 零 ML 依赖 · 免费 · MIT · 极简 pip 安装 · LLM 友好输出 | 不支持扫描 PDF · 复杂版式弱 · 82% F1 · 251MB 安装包（含 ONNX） |
| DS4SD/docling (IBM) | 18K | GPU 加速文档理解 | 45 页/秒 · 88% F1 · MIT 开源 · DocLayNet 88.5% mAP | 1GB+ 安装包 · 需 GPU · 单文件可能 60+ 分钟 · 部署重 |
| Unstructured-IO/unstructured | 12K | 多格式管道 | 30+ 文件类型 · 内置分块/嵌入 · LangChain 原生兼容 · 88% 可靠性 | 表格提取 78% F1 · API $2K/月(10万页) · Apache 2.0 |
| run-llama/llama_parse | 24K | 多模态 LLM 解析 | 92% F1 最高准确度 · 表格 100% 正确 · 手写/旋转扫描件支持 | $0.10/页 · API only · $10K/月(10万页) · 需 12GB GPU 显存 |
| nhirschfeld/kreuzberg | 新 | 极致轻量快速 | 71MB 安装 · 35+ 文件/秒 · 边缘计算友好 · 异步 API | 生态新 · 社区小 · 75% 可靠性需微调配置 · 作者自建库 |
这里面有个关键点：markitdown 和 Docling/Unstructured 不是直接竞争关系，而是互补。markitdown 的优势在于「零门槛」——不需要 GPU，不需要 API Key，不需要模型下载，pip install 完就能跑。对于 80% 的场景（原生 Office 文档转 Markdown 喂 LLM），它是最快的选择。但对于那 20% 需要处理扫描件、手写笔记、复杂多栏布局的场景，Docling 或 LlamaParse 会更合适。
// 性能数据
基于 2025-2026 年多次独立 benchmark（94 文档 / 500 页混合文档），各工具的核心指标对比：
文本提取准确度 (F1 Score)
处理速度 (页/秒)
安装体积 (MB)
// 博主观点
+ 零门槛：pip install 一行搞定，不用 GPU、不用 API Key、不用折腾模型
+ 格式覆盖广：从 PDF 到 YouTube 一网打尽，日常 RAG 场景基本够用
+ 输出真正 LLM 友好：保留标题/表格/链接结构，不是生硬的 plain text dump
+ MIT 协议商用无忧 + Microsoft 出品长期维护有保障
+ 插件系统设计合理：默认禁用 + LLM 注入不绑模型 + 四级 API 暴露面分层清晰
+ Azure 集成是加分项：视频和结构化字段提取这两个场景确实实用
- 不支持扫描 PDF / 手写文档 —— 核心硬伤，原生数字文档以外的场景全无覆盖
- 82% F1 在同类里处于下游，复杂版式准确度明显不够
- 251MB 安装包偏大，主要是 ONNX Runtime 拖的
- 大文件（>10MB）处理困难，性能下降明显
- 389 个 Open Issues + 391 个 Open PRs 积压，社区维护速度跟不上热度
- 中文文档/中文 OCR 支持薄弱，国内用户体验有折扣
说实话，markitdown 是我见过最「省心」的文档预处理工具。不是说它最强——Docling 准确度更高，Unstructured 格式覆盖更广，LlamaParse 在复杂文档上是降维打击。
但 markitdown 强在你没得选的时候它就是唯一解：本地跑、免费、一行命令、不用 GPU。这三个条件凑一块的竞品几乎没有。你用 Docling 得搞 GPU，用 LlamaParse 得掏钱，用 Unstructured 部署也不轻——markitdown 的定位就是「把门槛降到最低」。
如果你是做 RAG 管道的，日常处理的文档以 Office 原生的为主（Word 写报告、PPT 做汇报、Excel 存数据），markitdown 基本能覆盖 80% 的需求。剩下 20% 需要用扫描 PDF 或者复杂排版的场景，再搭 Docling 或者 Azure Document Intelligence 就可以了。不是替代关系，是组合关系。
一个让我觉得可惜的点：389 个 Open Issues 积压不少。135K Star 的项目，issue 响应速度跟不上热度是个隐患。好在是微软官方维护，不用担心像个人项目那样突然弃坑。
// links
GitHub — microsoft/markitdown
PyPI — markitdown
Benchmark — 4 Python Text Extraction Libraries Compared
2026 AI Document Analysis Tools Comparison
MarkItDown Review — Honest Limits & Real Code
GitHub — DS4SD/docling (IBM)
GitHub — Unstructured-IO/unstructured
GitHub — nhirschfeld/kreuzberg