MarkItDown 快速指南：批量把 PDF、Word、PPT 转成带结构的 Markdown
项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown MarkItDown 是微软开源的轻量级 Python 工具，批量把 PDF、Word、PPT、Excel、音频、HTML 等办公文档转换成 Markdown，面向需要把异构文档喂给 LLM 或做文本分析流水线的开发者。输出保留标题层级、列表、表格、超链接等结构，依赖可按格式按需安装。
🧭 什么时候需要它
- 手头一堆 PDF 论文、Word 报告、Excel 表混在一起要喂给 LLM：每个文件跑一条命令，得到能直接切片、索引的统一 Markdown 格式。
- 在做文本分析流水线，多种文件类型要归一成一种文本：它按扩展名自动路由到对应转换器，不用为每种格式写解析。
- 文档里有表格、多级标题、链接，不想压扁成纯文本：输出是带结构的 Markdown，而不是一坨文字。
- 只想处理一两种格式：只装对应 extras 分组，环境不臃肿。
🚀 从零到第一次输出
最快安装方式：一条命令装全依赖
- 环境要求：Python 3.10 到 3.14，建议用虚拟环境避免依赖冲突。
- 安装。不想挑就
[all]一次带全所有可选依赖：
pip install 'markitdown[all]'
你会得到 markitdown 命令行工具；只要某几种格式时，改成 pip install 'markitdown[pdf,docx]' 即可。
- 转一个手边的 PDF：
markitdown report.pdf -o report.md
你会看到同目录出现 report.md，原文标题变成 # 层级，表格输出为 Markdown 表格，超链接保留 URL。也可以 > 重定向到 stdout，或 cat report.pdf | markitdown 管道输入。
📦 核心能力地图
每种格式一个独立转换器
| 能力 | 输入 | 输出 | 备注 |
|---|---|---|---|
| 文档转换 | PDF、DOCX、PPTX、XLSX/XLS | 带标题、表格、链接的 Markdown | 各格式 extras 独立 |
| 图片转换 | 图片文件 | EXIF 元数据文本 | 配 LLM 可生成图像描述 |
| 音频转换 | wav、mp3 | 语音转写 + 元数据 | 需装 audio-transcription |
| 网页与结构化数据 | HTML、CSV、JSON、XML、EPUB | Markdown | ZIP 会逐成员处理 |
| YouTube 转换 | 视频链接 | 字幕转写 | 需装 youtube-transcription |
设计思路是不写"万能解析器"：每种格式一个独立转换器，源码都在 converters/，按扩展名自动路由，依赖按需安装。
🔍 进阶用法
用 LLM 生成图片描述
怎么开启：给构造函数传 llm_client 和 llm_model。前置：一个 OpenAI 兼容客户端。生效情况：README 说明目前仅对 PPTX 和图片文件生效，仓库里就有现成测试图可当输入样本：
模型调用失败并耗尽重试后，会自动尝试其他可用转换器，全部失败才抛 FileConversionException。
OCR 插件做批量文档转换（扫描件处理）
怎么开启：先装插件和客户端，再在 Python 侧传三个参数：
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o")
print(md.convert("scan.pdf").text_content)
前置：pip install markitdown-ocr openai。生效情况：PDF、DOCX、PPTX、XLSX 中内嵌图片会被 OCR；无可提取文本的扫描件按 300 DPI 渲染成整页图片送模型，文字包在 *[Image OCR]...[End OCR]* 标记里插回原位。不生效情况：不传 llm_client 时插件仍会加载，但 OCR 被静默跳过，回退到内置转换器。
⚙️ 实战走查
一行命令批量转换整个目录
输入：papers/ 里混着 PDF 论文、Word 报告、Excel 表。处理：按扩展名自动路由，一个文件进，一个 md 出。
for f in papers/*; do
markitdown "$f" -o "papers_md/$(basename "${f%.*}").md"
done
输出：papers_md/ 里每个原文件对应一个 .md，下游切片、建索引、喂 LLM 只面对一种格式；目录里若有扫描件，再叠加前面的 OCR 插件即可。
⚠️ 避坑与 FAQ
- 现象：照 markitdown-ocr 的 README 敲
--llm-client openai --llm-model gpt-4o，终端里模型不生效。原因：当前 CLI 源码（main.py）的 argparse 没注册这两个参数。正确做法：走 Python API 传参，用markitdown --list-plugins确认插件已装。 - 现象：复杂排版文档转换后结构松散。原因：README 明确输出面向文本分析工具，不是高保真排版。正确做法：多栏、公式密集文档人工抽查后再用。
- 现象：某格式报错或无法转换。原因：该格式可选依赖没装。正确做法：先补装对应 extras，如
pip install 'markitdown[pdf,docx]'再重试。 - 现象：服务端用
convert()处理不可信输入被安全审查拦下。原因：它接受远程 URI 和字节流。正确做法：只读本地文件时换用convert_local()。
总评：MarkItDown 朴素直接——装好、一条命令、拿带结构的 Markdown，OCR 插件与 LLM 描述补上扫描件和图片的最后一公里。手边有文档的话，直接 pip install 'markitdown[all]'，再 markitdown any.pdf -o any.md 试一把。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
