MarkItDown：把各种文件转成 Markdown

先认清它做什么、不做什么

MarkItDown 是给 LLM 和文本分析流水线准备输入的工具，不是文档转换器。

README 写得很直白：输出「虽然通常还算可读、适合人看，但它是为了被文本分析工具消费的，高保真转换不是它的目标」。

想做版式级保留（比如排版、字体、精确分页），它不合适。

为什么是 Markdown

官方给的三条理由都值得记：

• Markdown 极接近纯文本，标记极少，但仍能表达文档结构（标题、列表、表格、链接都保得住）
• 主流 LLM 原生就说 Markdown，训练数据里大量是 Markdown，理解得好
• Markdown 约定在 token 上很省

安装

全装：

bashpip install 'markitdown[all]'

只装你要的格式（更推荐，依赖少很多）：

bashpip install 'markitdown[pdf, docx, pptx]'

从源码装：

bashgit clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

装在虚拟环境里

要求 Python 3.10 到 3.14。官方建议用虚拟环境避免依赖冲突。

标准方式：

bashpython -m venv .venv
source .venv/bin/activate

用 uv（注意最后那行是 uv pip install，不是 pip install）：

bashuv venv --python=3.12 .venv
source .venv/bin/activate

用 conda：

bashconda create -n markitdown python=3.12
conda activate markitdown

三种用法

bash# 1. 重定向到文件
markitdown path-to-file.pdf > document.md

# 2. 用 -o 指定输出文件
markitdown path-to-file.pdf -o document.md

# 3. 管道输入
cat path-to-file.pdf | markitdown

支持哪些格式

PDF、PowerPoint、Word、Excel、图片（EXIF 与 OCR）、音频（EXIF 与语音转录）、HTML、文本类（CSV/JSON/XML）、ZIP（遍历内容）、YouTube URL、EPUB。

十种可选依赖

[all] 全装，或者挑着装：

插件（默认关闭）

插件默认是关的。先看装了什么：

bashmarkitdown --list-plugins

启用：

bashmarkitdown --use-plugins path-to-file.pdf

找现成插件：在 GitHub 搜 #markitdown-plugin hashtag。官方仓库里有 packages/markitdown-sample-plugin 可以当开发模板。

OCR：有个会静默失败的坑

markitdown-ocr 插件给 PDF、DOCX、PPTX、XLSX 加 OCR，用 LLM Vision 提取图片里的文字，不需要新的 ML 库或二进制依赖（复用 MarkItDown 已有的 llm_client / llm_model 模式）。

bashpip install markitdown-ocr
pip install openai  # 或任何 OpenAI 兼容客户端

pythonfrom markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.markdown)

坑在这里：没传 llm_client 时插件仍然会加载，但 OCR 会被静默跳过，直接回退到内置转换器。 命令不报错、文件也有输出，只是图片里的文字全丢了。所以 OCR 没生效时先检查这个参数传了没。

什么时候需要 Azure Content Understanding

三个内置的层级，能力递增、代价也递增：

需要这些才上 CU： 视频（CU 是唯一支持视频的选项）、结构化字段提取（发票金额、收据日期、合同条款）、扫描 PDF 和复杂表格的更高质量提取。

bashmarkitdown path-to-file.pdf --use-cu --cu-endpoint "<endpoint>"

也可以设一次环境变量，之后只写 --use-cu：

bashexport MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu

安全：接进服务前必读

README 开头就警告了：MarkItDown 的 I/O 权限就是当前进程的权限，和 open()、requests.get() 一样，会访问进程本身能访问的任何资源。

两条实践：

• 在不受信任的环境里清洗输入
• 只调你用例需要的那个最窄的函数——convert_stream() 或 convert_local()，而不是宽接口

这是所有文件解析器的通用风险（zip 炸弹、路径遍历、超大文件），但 MarkItDown 明确写出来了，值得在设计时就想清楚。

上手顺序

1. 虚拟环境装好，按需要选依赖项
2. markitdown 文件.pdf > out.md 跑通一次
3. 扫一遍输出，看结构（标题、表格、列表）保住了没
4. 图片里的文字没出来 → 装 markitdown-ocr 并检查 llm_client 有没有传
5. 质量不够再考虑 Azure Document Intelligence，字段提取或视频再上 Content Understanding
6. 要接进服务 → 按安全那节改成最窄的函数调用