微软 MarkItDown 使用教程：文档转 Markdown，做 AI 知识库更方便

Sun, 21 Jun 2026 16:45:50 +0800

微软的 microsoft/markitdown 是一个把多种文件转换成 Markdown 的 Python 工具。它的目标不是做高保真排版还原，而是把文档、表格、网页、图片、音频等资料变成更适合 LLM、RAG、搜索索引和文本处理流程使用的 Markdown。

项目地址：

https://github.com/microsoft/markitdown

如果你经常需要把 PDF、Word、Excel、PowerPoint、网页、图片或压缩包里的资料交给大模型分析，MarkItDown 很适合放在预处理环节。它输出的是纯文本 Markdown，比直接把二进制文件塞进流程里更容易调试、切分、检索和存档。

MarkItDown 支持什么

根据官方 README，MarkItDown 支持的输入类型包括：

PDF
PowerPoint
Word
Excel
图片，包括 EXIF 元数据和 OCR
音频，包括 EXIF 元数据和语音转写
HTML
CSV、JSON、XML
ZIP 文件，会遍历其中内容
YouTube URL
EPUB

它的定位很明确：把文件转换成 Markdown，方便下游的 LLM 和文本工作流使用。不要把它当成一个严格保留版式的文档转换器。对于简历、合同、扫描件、产品资料、会议录音、网页快照这类素材，重点通常不是还原每个像素，而是提取出能被模型稳定理解的文本结构。

安装命令

最简单的安装方式是直接用 pip：

`1`	`pip install markitdown`

如果需要使用全部可选功能，可以安装 all 额外依赖：

`1`	`pip install 'markitdown[all]'`

如果只想安装特定格式支持，也可以按需安装 extra。例如 PDF、DOCX、PPTX：

`1`	`pip install 'markitdown[pdf,docx,pptx]'`

如果想从源码安装：

1
2
3

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

命令行用法

安装后可以直接使用 markitdown 命令。最基础的用法是把文件转换到标准输出：

`1`	`markitdown path-to-file.pdf`

保存为 Markdown 文件：

`1`	`markitdown path-to-file.pdf -o output.md`

转换 Office 文档：

1
2
3

markitdown report.docx -o report.md
markitdown slides.pptx -o slides.md
markitdown data.xlsx -o data.md

转换网页：

`1`	`markitdown https://example.com -o page.md`

转换 YouTube URL：

`1`	`markitdown https://www.youtube.com/watch?v=VIDEO_ID -o video.md`

处理 ZIP 文件：

`1`	`markitdown archive.zip -o archive.md`

这些命令适合先手动验证效果。确认输出结构符合预期后，再把它放进自动化脚本、知识库导入流程或 RAG pipeline。

Python API 用法

MarkItDown 也可以作为 Python 库使用。官方 README 给出的基本方式是创建 MarkItDown 实例，然后调用 convert：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

如果要接入 OpenAI 客户端做图片描述，可以把客户端传给 MarkItDown：

from openai import OpenAI
from markitdown import MarkItDown

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

这个能力适合处理图片型资料，例如截图、扫描图片、包含图表的页面。实际使用时要注意成本、隐私和网络请求，尤其是处理内部文档时。

Docker 用法

如果不想污染本机 Python 环境，可以用 Docker 运行。官方 README 提供了镜像构建方式：

`1`	`docker build -t markitdown:latest .`

然后把当前目录挂载到容器里执行转换：

`1`	`docker run --rm -v .:/workdir markitdown:latest path-to-file.pdf -o output.md`

这种方式适合服务器、CI 或临时批处理环境。缺点是调试依赖会比本机 Python 环境稍慢一点。

插件机制

MarkItDown 支持插件，但默认不会启用第三方插件。查看插件：

`1`	`markitdown --list-plugins`

启用插件：

`1`	`markitdown --use-plugins path-to-file.foo -o output.md`

在 Python 中启用插件：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("example.foo")
print(result.text_content)

插件适合扩展私有格式、内部文档格式或特定业务系统导出的文件。需要注意的是，插件本质上是执行额外代码，来源不可信时不要随便启用。

适合放在哪些流程里

我更推荐把 MarkItDown 放在这些场景：

把 PDF、DOCX、PPTX、XLSX 统一转成 Markdown，再进入知识库。
把网页、YouTube、EPUB 等资料转成可检索文本。
做 RAG 前的文档预处理，先得到更容易切分的 Markdown。
把资料转换结果提交给 Codex、Claude Code、Cursor 这类工具阅读。
批量整理历史文档，生成统一的 .md 中间格式。

一个简单流程可以是：

1
2

mkdir -p markdown
markitdown input.pdf -o markdown/input.md

如果要批量处理目录，可以先用脚本枚举文件，再逐个调用 markitdown。转换后建议人工抽查几份输出，尤其是表格、扫描件、复杂版式 PDF 和多栏文档。

使用边界

MarkItDown 很实用，但要注意几个边界：

复杂 PDF 的阅读顺序不一定完美，特别是多栏、脚注、页眉页脚很多的文件。
OCR 和图片描述依赖额外组件或 LLM，效果和成本都要单独评估。
Markdown 适合表达文本结构，但不适合保留精确排版。
插件和 LLM 处理内部文件时，要注意数据安全。
转换结果最好作为中间产物，不要默认等同于原文。

如果目标是“让大模型读懂资料”，MarkItDown 的方向是对的：先把各种文件变成统一的 Markdown，再做清洗、切分、索引和问答。它不是万能转换器，但作为 LLM 文档入口工具，已经足够清晰、轻量，也方便接进现有 Python 工作流。

MarkItDown on KnightLi的博客