ARTICLE · 1292710

手把手教你:一条命令,把 PDF 变成 AI 能读的文本

发布时间：2026-11-01 20:46:09 最近访问：2026-11-01 20:46:10

把一份 30 页的 PDF 丢给 AI 让它总结，多数人的动作是打开、全选、复制、粘贴。粘进去的文字没有标题层级，表格散成一行行数字，页眉页脚夹在正文中间，AI 读得懂，但读得不准。

MarkItDown 解决的就是这一步：一条命令，把 PDF、Word、PPT、Excel、图片、网页转成 Markdown，标题、表格、列表、链接都尽量保留。微软开源，仓库 github.com/microsoft/markitdown，193,326 Star，主要语言 Python，MIT 许可，最新版 v0.1.9（2026 年 10 月 21 日），用法都在仓库 README 里。你要是经常把合同、调研报告、需求文档喂给 AI，它省下的是你每次手动整理的那十几分钟。

为什么是 Markdown 而不是纯文本

纯文本只有字，没有结构。一句“预算 12 万，分三期”在纯文本里和别的行长得一样；到了 Markdown 里，表格还是表格，标题还是标题，AI 一眼能看出哪句是结论、哪列是金额。

几个主流模型本来就大量读 Markdown、写 Markdown，给它这个格式，比你塞一段排版错乱的文字更省 token，也更少答非所问。

装之前先确认一件事

Python 3.10 到 3.14，低于 3.10 装不上。建议单独开一个虚拟环境，避免和系统里的包打架：

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

Windows 换 .venv\Scripts\activate。用 uv 的话是 uv venv --python=3.12 .venv，之后装包记得用 uv pip install，别用 pip install。

装它

pip install 'markitdown[all]'

验证一下：

markitdown --version

回显形如 markitdown 0.1.9，版本对得上就能用了。

[all] 会把所有格式的依赖一次装齐。只处理 PDF、Word、PPT 的话可以只装这三样，装得快：

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

另外还有 [xlsx]、[xls]、[outlook]、[audio-transcription]（wav 和 mp3 语音转写）、[youtube-transcription]（拉 YouTube 字幕）几个单独的口子，用哪个装哪个。

第一条命令

markitdown 需求文档.pdf > 需求文档.md

或者直接指定输出文件：

markitdown 需求文档.pdf -o 需求文档.md

也能走管道，把别处的输出接进来：

cat 需求文档.pdf | markitdown

打开生成的 md，一级标题、二级标题都在，原来的表格变成 | 列名 | 列名 | 这种竖线表格，列表和链接保留。原文件要是扫描件，正文可能只有寥寥几行，那不是命令写错了，是 PDF 里本来就没有文字层，处理办法在下面。

一个目录一次转完

文件多的时候别一个个敲，用它自带的 Python 接口批量走一遍：

from pathlib import Path from markitdown import MarkItDown  md = MarkItDown() for p in Path("docs").rglob("*"):     if p.suffix.lower() in {".pdf", ".docx", ".pptx", ".xlsx"}:         text = md.convert(str(p)).markdown         p.with_suffix(".md").write_text(text, encoding="utf-8")         print("done:", p.name)

convert() 返回的对象里正文在 .markdown 上，直接写文件。跑完 docs 目录里每份源文件旁边会多一份同名 md。

转完怎么用

转出来的 md 可以整份贴给 AI，也可以丢到一个文件夹里让它自己找：

把 docs 目录里的 md 全读一遍，按项目把风险点列出来，每条后面标出处文件名。

一份五万字的需求文档转完大概两三行，一次读不完就分章节让它逐段过。关键是它现在能看见标题层级，你说“第七章的验收标准”，它找得到。

扫描件和图片里的字：加一个 OCR 插件

默认情况下，Excel 多张表会一张一张往下排，每张表带一个二级标题；文档里的图片只留基本信息，图里的文字它不认。后者要装官方那个 OCR 插件，借视觉模型把图里的字读出来：

pip install markitdown-ocr pip install openai

from markitdown import MarkItDown from openai import OpenAI  md = MarkItDown(     enable_plugins=True,     llm_client=OpenAI(),     llm_model="gpt-4o", ) print(md.convert("扫描件.pdf").markdown)

llm_client 传任何 OpenAI 兼容的客户端都行，llm_model 填模型名。这里有个坑：不传 llm_client，插件照样装、照样加载，但 OCR 会被静默跳过，你只会拿到普通转换的结果，不会报错。

把它接给自己的 AI 助手

MarkItDown 还有一个 MCP 版本，装完你的编码助手就能直接调它读文件：

pip install markitdown-mcp markitdown-mcp

默认走 STDIO，只暴露一个工具 convert_to_markdown(uri)，uri 支持 http:、https:、file:、data: 四种。想用 HTTP 方式：

markitdown-mcp --http --host 127.0.0.1 --port 3001

Claude Desktop 这类客户端加一条配置就能用，官方推荐走它的 Docker 镜像：

{   "mcpServers": {     "markitdown": {       "command": "docker",       "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]     }   } }

这条命令给助手的能力很大：它能读运行服务的这个用户能读的任何文件。所以官方一再强调只绑 127.0.0.1，别把端口开到外网，转换前也确认一下文件来源。

常见报错对照

MissingDependencyException：报错里写 dependencies needed to read .pdf files have not been installed，说明装的时候只装了主包，没装对应格式的额外依赖。补 pip install 'markitdown[pdf]'，或者直接 [all]。

UnsupportedFormatException：文件类型没认出来，常见于没有扩展名的文件。给它提示：markitdown data -x pdf，或者用 -m application/pdf 指定 MIME。

FileConversionException：格式认对了但转换失败，报错里会列出每一轮尝试的异常。扫描件最常见的表现就在这儿，先确认原文件有没有文字层。

中文乱码：加 -c utf-8 显式指定字符集，报错里也会提示字符集可能是自动猜错的。

装上却提示 command not found：多半是包装进了用户目录而 PATH 没带上。先用 python -m markitdown 文件.pdf 试，能跑就说明包在、只是没进 PATH，把 pip 的 bin 目录加进 PATH 即可。