MarkItDown 是 GitHub 上最火的文档转 Markdown 工具，没有之一。截至 2026 年 7 月底，169,538 颗星、12,256 个 fork、MIT 协议、纯 Python，2024 年 11 月 13 日首提交，最新版 v0.1.6。微软 AutoGen 团队出品，定位轻量级「文件->Markdown」转换器，专门喂给 LLM 和文本分析流水线。它干的事一句话：把 PDF、Word、PPT、Excel、图片、音频、HTML、YouTube 链接等十来种格式，统一转成结构保留的 Markdown。它不追求人类阅读保真，死磕「机器可读 + token 高效」，输出给 LLM 吃不是给人排版。
解决什么痛点
搞 RAG 和知识库的人都踩过这些：企业文档库 PDF、Word、PPT 混着堆，每种格式一套解析器，PDF 表格抽出来乱序，Word 公式丢光，PPT 图形变占位符；自己拼 Apache Tika + pdfplumber + python-docx + python-pptx，四五个库缝缝补补，代码比业务逻辑还长，每加格式再接一个轮子；文档里有图片和扫描件，纯文本抽取一片空白，又得挂 OCR 后处理；想把音频、视频喂进 LLM，又得自己接 Whisper、拉 YouTube 字幕。MarkItDown 把这些打包进 convert()：一个调用吃任意格式，吐结构化 Markdown。核心是从「每格式造轮子」换成「一个入口 + 可选依赖按需装」，标题、列表、表格、链接都尽量保留，让 LLM 直接读懂文档骨架而非纯文本坨。
支持什么格式：11 类输入 + 可选依赖精装
输入覆盖是这个项目最厚的地方。开箱转换源有：PDF、PowerPoint、Word、Excel、图片（EXIF + OCR）、音频（EXIF + 语音转录）、HTML、文本格式（CSV、JSON、XML）、ZIP（遍历内部文件逐个转）、YouTube URL（拉字幕）、EPub，以及更多。一套代码处理十一种来源，不用为「这批材料有 PPT 又有 PDF 还有 Excel」写分发逻辑。关键是这些能力按需装。pip install 'markitdown[all]' 一把全装适合本地开发；生产想瘦身按格式挑：[pdf]、[docx]、[pptx]、[xlsx] 新版 Excel、[xls] 老版 Excel、[outlook] 吃 Outlook 邮件、[audio-transcription] 给 wav/mp3 上转录、[youtube-transcription] 拉 YouTube 字幕。刀切得很细--只转 PDF 的服务不用拖进整个音频转录栈，镜像和攻击面都小。两条 Azure 路线 [az-doc-intel] 和 [az-content-understanding] 是云上高保真转换，后面说。命令行直白：markitdown path-to-file.pdf > document.md 重定向，或 -o document.md 指定输出，或 cat path-to-file.pdf | markitdown 走管道。
插件与 LLM 视觉：让 OCR 和图片描述走 GPT-4o
内置转换器吃不下「文档里嵌的图片」时，LLM 视觉路线顶上。MarkItDown 支持第三方插件，默认关，markitdown --use-plugins path-to-file.pdf 打开，--list-plugins 看装了哪些，社区插件 GitHub 搜 #markitdown-plugin，自己写照着 packages/markitdown-sample-plugin 抄。最实用的官方插件是 markitdown-ocr：给 PDF、DOCX、PPTX、XLSX 挂上 OCR，把内嵌图片里的字抽出来，走 LLM Vision--和图片描述共用同一套 llm_client / llm_model 机制，不引入新 ML 库或二进制依赖。装法 pip install markitdown-ocr 再 pip install openai（或任何 OpenAI 兼容客户端）。Python 侧传进去就行：MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o")，转 document_with_images.pdf 时图片被 LLM 看一遍描述出来。这套视觉原生也对 pptx 和图片文件生效，还能传 llm_prompt 自定义提示词。没传 llm_client 不报错，OCR 静默跳过、回退内置转换器--优雅降级而不是崩。
Azure 云转换：结构化字段抽取与多模态
本地转换器搞不定的，留两条 Azure 后路。一条是 Azure Document Intelligence，markitdown path-to-file.pdf -d -e "<endpoint>" 或 Python MarkItDown(docintel_endpoint=...)，走云上版式分析 + OCR，适合扫描 PDF、复杂表格、多页文档这种硬骨头。更强的是 Azure Content Understanding（CU），pip install 'markitdown[az-content-understanding]' 装上后能力跳一档：一是多模态全覆盖，文档、图片、音频、视频一个 cu_endpoint 全包，视频是内置转换器唯一完全没法处理的，CU 是唯一出路，音频也比内置初级转录质量高。二是结构化字段抽取，用预置或自定义 analyzer 抽领域字段（发票金额、收据日期、合同条款），序列化成 YAML front matter 挂在 Markdown 前--内置和 Doc Intel 集成都不暴露字段，这是 CU 独家。三是自定义 analyzer，传 cu_analyzer_id，CU 自动按模态圈定兼容文件类型，不兼容的回退预置。CLI 是 markitdown path-to-file.pdf --use-cu --cu-endpoint "<endpoint>"，Python 零配置 MarkItDown(cu_endpoint=...) 按文件类型自动选 analyzer。代价是每次 CU 路由的 convert() 都是计费 Azure API 调用，省钱用 cu_file_types=[ContentUnderstandingFileType.PDF] 只让 PDF 走 CU。
三分钟上手
# 1. 装（Python >= 3.10，建议虚拟环境）
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'
# 2. 命令行一把跑
markitdown path-to-file.pdf > document.md
# 或指定输出：markitdown path-to-file.pdf -o document.md
# 3. Python API 验证
python -c "
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，文件喂进容器、Markdown 流出来。生产里喂 LLM 就拿 result.text_content 拼进 prompt，结构化标题列表表格被 LLM 原生理解，token 也省。
适合谁 + 五个踩坑
适合：搭 RAG 要批量把企业文档转 Markdown 喂向量库的；做内容站统一多格式素材的；写 AI agent 要先读懂文档再决策的；做音频/视频/YouTube 多模态知识库的。
踩坑记五条。一是安全模型，MarkItDown 以当前进程权限做 I/O，行为和 open()、requests.get() 一样--进程能访问什么它就能访问什么。不可信环境（托管服务、服务端应用）务必清洗输入：限制文件路径、收紧 URI scheme 和网络目标、封掉私网/loopback/链路本地/云元数据地址（169.254.169.254 这种），别让用户构造 file:///etc/passwd 或 http://169.254.169.254/ 把你打穿。二是用最窄的 convert_*，别图省事全走 convert()--它故意很宽松，本地文件、远程 URI、字节流全收。只读本地就 convert_local()，要控 URI 拉取就自己 requests.get() 传 convert_response()，要最大控制就开流喂 convert_stream()。三是别装 [all] 就上生产，按格式挑 [pdf,docx,pptx]，镜像小攻击面小，缺格式的文件优雅降级不崩。四是 LLM 视觉要花钱，挂 llm_client 转带图文档每张图一次 GPT-4o 调用，大批量先估 token；没传 client 时 OCR 静默跳过回退内置转换器，别以为图片被处理了其实没有。五是 Azure 计费，CU 每次路由的 convert() 都是计费调用，用 cu_file_types 限定只让指定格式走云，其余走本地免费转换器，否则账单吓人。
和竞品比
和 textract 比，同档但 MarkItDown 更现代：textract 纯文本抽取结构丢光；MarkItDown 死磕结构保留，输出直接是 LLM 友好 Markdown，还有插件 + LLM 视觉 + Azure 云后路，textract 生态早停滞。和 LlamaParse、Unstructured 比，LlamaParse 云优先质量高但闭源 SaaS、按页计费、数据出域；Unstructured 开源多格式但偏重 chunking 和 pipeline 编排，单文件保真不如 MarkItDown；MarkItDown 走「本地优先 + MIT 开源 + 可选云增强」，核心转换不出域，要更高保真再挂 Azure。和 Docling（IBM）比，都开源做结构化转换，Docling 重版式理解和表格解析深度，MarkItDown 胜在格式覆盖广（音频、视频、YouTube、ZIP 这些 Docling 不碰）和插件生态。一句话：要纯本地轻量、十一种格式一把梭、还要 LLM 视觉和 Azure 云兜底选 MarkItDown；要极致表格/版式深度解析看 Docling；要开箱即用云 SaaS 看 LlamaParse。
参考来源
- MarkItDown GitHub 仓库（169,538 star，MIT，Python）：https://github.com/microsoft/markitdown
- 官方 README（格式列表 / 安装 / 可选依赖 / 插件 / Azure / 安全）：https://github.com/microsoft/markitdown
- markitdown-ocr 插件（PDF/DOCX/PPTX/XLSX 的 LLM Vision OCR）：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr
- Azure Content Understanding 文档（多模态 + 结构化字段抽取）：https://learn.microsoft.com/azure/ai-services/content-understanding/
- Azure Document Intelligence 文档（云版式分析 + OCR）：https://learn.microsoft.com/azure/ai-services/document-intelligence/
- PyPI 包页面（版本与可选依赖 extras）：https://pypi.org/project/markitdown/