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 倍速度。

常见问题 FAQ

Q1: 这个 Skill 跟 markitdown 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: markitdown 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 markitdown 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 markitdown,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/microsoft/markitdown
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• markitdown 官方仓库:https://github.com/microsoft/markitdown
• 官方文档:https://microsoft.github.io/markitdown/
• PyPI 包:https://pypi.org/project/markitdown/
• markitdown MCP:https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md
• LLM CLI(Simon Willison):https://llm.datasette.io/

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。