markitdown

markitdown 快速入门

一行命令把 PDF、Word、Excel、PPT、图片、音频全转 Markdown,直接喂给 AI 分析。

这是什么?解决什么问题?

markitdown 是 Microsoft 官方开源的格式转换工具,GitHub 上 84k+ Stars。它的核心能力极其简单:把各种”非 Markdown”格式的文件批量转成结构化 Markdown,直接喂给 LLM 做分析。 传统流程中,你想让 AI 帮你分析一份 PDF 合同、一份 Excel 报表、一份 Word 文档,通常要先手动复制粘贴,或者写复杂的解析脚本。markitdown 把这件事做成”一行命令”:

markitdown 合同.pdf > 合同.md

它支持 20+ 种格式:

• 文档:PDF、Word(docx)、PowerPoint(pptx)、Excel(xlsx)、RTF、OpenDocument。
• 图像:JPG、PNG、GIF(用 GPT-4V 提取文字和描述,可选)。
• 音频:MP3、WAV(用 Whisper 转录,可选)。
• 网页:HTML(保留结构)。
• 数据:CSV、JSON、XML。
• 电子书:EPUB。
• 压缩包:ZIP(自动展开里面的文件)。 它解决的问题,和”AI 时代的文档工作流”直接相关:当你想让 AI 读 PDF 报告、对比 Excel 表格、转录会议录音时,markitdown 是最方便的”格式归一化”工具。 它适合的场景:把公司历史 PDF 文档喂给 RAG 系统、会议录音转写后让 AI 做总结、批量把 Excel 报表转 Markdown 入库、网页内容转 Markdown 永久存档。

准备工作

1. Python 3.10+(markitdown 对 Python 版本有要求)。
2. pip 安装:

pip install markitdown[all]

all 会装上所有可选依赖(PDF、Word、Excel、音频等)。 3. 验证安装:

markitdown --version

3 步快速上手

第 1 步:基本转换

把一份 PDF 转 Markdown:

markitdown 季度报告.pdf > 季度报告.md

或者直接管道喂给 LLM:

markitdown 季度报告.pdf | llm "请帮我总结这份报告的 3 个核心结论"

(假设你装了 LLM CLI 工具,比如 llm by Simon Willison。)

第 2 步:验证安装

markitdown README.md  # Markdown 转 Markdown,应该是 noop

正常返回 README 内容说明工具可用。

第 3 步:用 markitdown 跑第一个真实任务

任务 1:把整批 PDF 入库 RAG

# 批量转 docs/ 目录下所有 PDF 为 Markdown
for f in docs/*.pdf; do
markitdown "$f" > "markdown/${f%.pdf}.md"
done

任务 2:音频文件转录 + AI 总结

# 转录音频,需要先设置 OpenAI API Key
export OPENAI_API_KEY=sk-xxx
markitdown 会议录音.mp3 > 会议纪要.md

转出来的 Markdown 是带时间戳的对话文本,可以直接喂给 AI 做总结。 任务 3:Excel 转 Markdown 表格

markitdown 财务报表.xlsx > 财务报表.md

转出来是 Markdown 表格,结构保留得很好,直接喂 AI 就能让它做财务分析。 任务 4:批量压缩包处理

markitdown 项目文档.zip > 全部文档.md

ZIP 里的所有文件会被合并到一个 Markdown 里,每个文件用二级标题分隔。

常见踩坑

1. PDF 扫描件识别失败。纯图片型 PDF 不会自动 OCR,需要 markitdown[pdf] 装上 PDF 文本提取依赖,或者先用其他工具 OCR。
2. Excel 多 sheet 合并混乱。markitdown 默认把多 sheet 拼到一个表里,可能字段对不齐。Skill 建议用 --sheet 参数指定 sheet。
3. 音频转录需要 API Key。markitdown[audio] 默认用 OpenAI Whisper,需要 OPENAI_API_KEY 环境变量。
4. 图像理解贵。用 GPT-4V 提取图片内容很贵,大量图片场景下成本高,Skill 建议设置预算限制。
5. 中文 PDF 编码乱码。部分老旧 PDF 字体嵌入不规范,转出来是乱码,这种情况下用 pymupdf 替代 PDF 后端。
6. 大文件内存爆掉。500MB 的 PDF 可能 OOM,Skill 建议分章节转换,或者先用流式处理。

初级用法

用法 1:RAG 文档入库。把公司所有 Word/PDF/PPT 批量转 Markdown,然后灌进向量数据库,做企业知识库问答。 用法 2:会议录音转写。把周会、月会、客户访谈的录音批量转录,再让 AI 自动生成会议纪要。 用法 3:网页存档。把博客、新闻、文档站批量下载转 Markdown,做长期存档,避免链接失效后内容丢失。

高级玩法

玩法 1:接 LLM Pipeline。把 markitdown 接进 LangChain / LlamaIndex 文档加载器,作为 RAG 的预处理步骤。 玩法 2:接 MCP Server。markitdown 有官方的 MCP server,让 AI 编程助手直接在对话里调 markitdown 转换文件。 玩法 3:命令行批处理。写一个 convert.sh,把整个目录的文档批量转 Markdown,扔给 cron 定时跑,自动维护文档库。

小技巧

1. 用 --keep-data-uris 保留图片的 base64 编码,适合需要图片一起进 LLM 上下文的场景。
2. 用 --disable-tables 关闭表格识别,在某些 Excel 转换时表格识别反而破坏数据,关掉更稳。
3. 音频转录用 -l zh 指定中文,Whisper 默认会”听”成英文,中文场景必须显式指定。
4. PDF 转出来结构乱了,试试加 --pdf-backend=pymupdf,markitdown 内部支持切换 PDF 解析后端。
5. 大批量转换用 GNU parallel。ls *.pdf | parallel -j 4 'markitdown {} > {.}.md',4 核并行,4 倍速度。

参考链接

• markitdown 官方仓库
• 官方文档
• PyPI 包
• markitdown MCP
• LLM CLI(Simon Willison)