把 PDF 转成 Markdown 以节省 LLM token：MarkItDown 实战指南

你把一份 20 页的 PDF 拖进 Claude，问了一个问题，回答也顺利返回了。你没看到的，是账单。在你的问题还没被读到之前，这份文档就可能吞掉几万个 token。一个团队每天这样做上几次，你就在花真金白银，只为把原始 PDF 铲进一个本来用干净文本就同样满意的模型。

有一个免费的解决办法，而且它一直就摆在明面上：先把文件转成 Markdown。本指南会准确解释为什么 PDF 这么贵、你能省多少，以及如何用微软的开源转换器 MarkItDown 一条命令完成转换。

为什么一份 PDF 要耗这么多 token

这是没人告诉你的部分。当你把一份 PDF 交给 LLM 时，它读取的方式和你读的方式不一样。根据 Anthropic 自己的 PDF 文档，系统会对每一页做两件事：

1. 从页面中提取文本。
2. 把整页转成图片，然后把这张图片连同文本一起发送。

第二步就是那个无声的 token 黑洞。模型不只是在读文字，它还在看每一页的图片，好让自己能理解图表、表格和排版。这两份你都得付费。

Anthropic 的数据让成本变得具体。仅提取出的文本，按密度不同就要 每页 1,500 到 3,000 个 token。在此之上，每一页还要再加一张图片的成本。来自 Amazon Bedrock 集成的一个有说服力的数据点：完整的可视化 PDF 模式对一份 3 页 PDF 大约要用 7,000 个 token，而对同样这三页只做纯文本提取 大约只用 1,000 个 token。这是 7 倍的差距，而它完全来自逐页的图片。

把它放大到一份真实文档。一份内容密集的 20 页报告，一旦每一页都被栅格化成图片，token 数可能落在 40,000 到 70,000 之间。你还什么都没问，你只是打开了这个文件而已。

橙红色的色块是纯粹的额外开销：每一页一张图片，不管这一页里有没有任何值得一看的视觉内容。

解决办法：改喂干净的 Markdown

大多数文档并不需要被「看」。一份合同、一份规格说明、一篇研究论文、一套满是要点的幻灯片：这些全都是套着排版外衣的文本。如果你剥掉排版、保留结构，模型并不会损失任何它真正需要的东西。

这正是 Markdown 给你的。它几乎是一种格式能做到的、最接近纯文本的形态，但它仍然编码了那些要紧的结构：标题、列表、表格、链接、代码块、加粗与强调。主流 LLM 都是在海量 Markdown 上训练出来的，所以它们能原生、轻松地解析它。开发 MarkItDown 的微软说得很直白：Markdown「极其接近纯文本，标记或格式都极少，但仍提供了一种表示文档重要结构的方式」。

把你的 PDF 转成 Markdown，你就彻底丢掉了逐页图片。没有栅格化的页面，没有视觉开销，只剩下模型本来就要读的那份结构化文本。省下来的就是从这里来的。

认识 MarkItDown，微软的免费转换器

MarkItDown 是微软出品的一个轻量级 Python 工具，以宽松的 MIT 许可证发布，是 GitHub 上 star 数最高的开发者工具之一，超过 135,000 个 star。它唯一的任务，就是把现实世界里乱糟糟的文件变成 LLM 能低成本读取的干净 Markdown。

它不只是个 PDF 工具。它能转换一长串格式：

• PDF 文档
• Word（.docx）
• Excel（.xlsx、.xls）
• PowerPoint（.pptx）
• 图片，附带 EXIF 元数据，以及对图片内文字的 OCR
• 音频，附带元数据和语音转写
• HTML 页面
• CSV、JSON 和 XML 数据
• ZIP 压缩包（它会遍历其中的内容）
• YouTube 链接（它会抓取字幕）
• EPub 电子书
• Outlook 邮件（.msg）

一个工具，一种输出格式，几乎能搞定任何你原本会作为笨重二进制文件丢给模型的东西。

30 秒装好 MarkItDown

它就是个普通的 Python 包。想把所有功能都装齐，就安装 all extra：

pip install 'markitdown[all]'

如果你只关心少数几种格式、想要更精简的安装，就只要那几个 extra：

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

可选项包括 [all]、[pdf]、[docx]、[pptx]、[xlsx]、[xls]、[outlook]、[audio-transcription] 和 [youtube-transcription] 等等。

用命令行把 PDF 转成 Markdown

最快的路径是 CLI。把它指向一个文件，再把输出发到你想要的任何地方：

markitdown report.pdf -o report.md

或者用一个简单的重定向，效果一样：

markitdown report.pdf > report.md

你也可以直接把文件通过管道传进去：

cat report.pdf | markitdown

这就是全部流程了。现在你手上有一个 report.md，可以交给任何模型、放进代码仓库，或者粘进对话里，而它的成本只是原文件的一小部分。

笨重文件进，代理可直接读用的 Markdown 出，中间只隔着一条命令。

用 Python 转换（并批量处理整个文件夹）

如果你要把它接进流水线，Python API 同样简短：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("report.pdf")
print(result.text_content)

result.text_content 就是你的 Markdown 字符串，可以直接写入磁盘或喂给模型。想一次性转换整个文件夹的文档，循环遍历它即可：

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
for src in Path("docs").glob("*.pdf"):
    out = src.with_suffix(".md")
    out.write_text(md.convert(str(src)).text_content, encoding="utf-8")

跑一次，一个装满昂贵 PDF 的目录就变成一个装满廉价、结构化 Markdown 的目录，任何代理都能在每一轮读取它，而不必反复缴纳视觉税。

你到底能省多少？

诚实的回答是：取决于文档，但收益既大又稳定。对一份典型的、以文字为主的文件来说，大致是这个样子。

对一份价值在于其文字的文档来说，转成 Markdown 通常能把 token 成本砍掉一大半还不止，往往达到 80% 或更多。这些节省并不神奇：你只是不再为发送每一页的图片付费，而模型本来只需要文本。

当然，Markdown 并非字面意义上的免费。提取出的文本仍然要花 token。但那份文本成本本就是你无论如何都得付的底线。你去掉的，是叠在它上面那一摞逐页图片。

什么时候该保留 PDF（别过度优化）

转换是合理的默认选择，而不是放之四海皆准的规则。当视觉排版本身就是重点时，请保留原始 PDF：

• 你确实需要模型读懂的图表和曲线。 如果含义就活在一张柱状图里，那张图片是在做真正的工作。
• 扫描件，也就是文字的图片。MarkItDown 可以对它们做 OCR，但如果识别不太靠谱，模型自带的视觉有时反而能更可靠地读出这一页。
• 复杂的可视化表格或表单，其中位置与对齐承载着含义，而这些在 Markdown 里会被压平。
• 信息图和高度设计化的页面，排版「就是」内容本身。

至于其余的一切，也就是绝大多数文档，Markdown 都更胜一筹。

问题从来不是抽象的「PDF 还是 Markdown」。而是「模型是需要看这一页，还是只需要读它？」

不止 PDF：Word、Excel、PowerPoint，甚至 YouTube

同样一行命令对你那一堆其余文档也照样管用。一份 Word 文档、一个电子表格、一套幻灯片、一个网页，甚至一段 YouTube 视频的字幕，全都能以同样的方式塌缩成干净的 Markdown：

markitdown deck.pptx -o deck.md
markitdown budget.xlsx -o budget.md
markitdown https://www.youtube.com/watch?v=VIDEO_ID -o transcript.md

如果你的工作流就是经常从 Office 文件或网页里抽取上下文再交给模型，那么先把一切统一成 Markdown，是你能养成的最便宜、杠杆最高的习惯之一。

用 MarkItDown MCP 服务器接入你的编码代理

如果你和编码代理一起工作，那就更妙了。MarkItDown 提供了一个官方的 MCP（Model Context Protocol）服务器，于是你的代理可以在任务进行中自己转换文件，无需你手动跑任何东西。

安装它，并通过 stdio 运行：

pip install markitdown-mcp
markitdown-mcp

该服务器只暴露一个工具，convert_to_markdown(uri)，其中的 uri 可以是任何 http:、https:、file: 或 data: URI。给你的代理接上它一次，它就能按需抓取一份 PDF、一个电子表格或一个网页并转成 Markdown，全程付的是文本 token 的价钱，而不是视觉的价钱。

当你同时跑着不止一个代理时，这正是那种会产生复利效应的事情。在多代理驾驶舱 AgentsRoom 里，你只需配置一次 MCP 服务器，房间里的每个代理都会继承它。把你的参考文档转成 .md，提交进代码仓库，每个代理就能在每一轮读取廉价、结构化的文本，而不是把同一份 PDF 一次又一次地重新栅格化。让单个会话保持轻盈的那套纪律，也能让整支舰队保持可负担，而这在你并行运行编码代理、且每个代理都在读取你共享的上下文时，尤为重要。

它也自然契合优秀代理配置已经在用的上下文管理方式。如果你维护着一份 AGENTS.md 上下文文件，让它指向轻量的 .md 参考而非原始 PDF，就能让上下文窗口保持紧凑，而正如我们在用金丝雀技巧捕捉上下文漂移一文中讲过的，这在任何长会话里都已经是成功的一半。

要点回顾

把原始 PDF 喂给 LLM，是一笔你在不知不觉中一直在缴的税，因为每一页都被悄悄转成了图片。MarkItDown 免费替你去掉这笔税：一条命令就能把几乎任何文件变成干净的 Markdown，你甩掉最多 80% 的 token 成本，而模型回答得同样好，往往更好，因为它读的是结构，而不是眯着眼去辨认页面图片。

先转换，再提问。你的 token 账单和你的上下文窗口都会感谢你。

准备好把这套做法铺到一整支代理团队、而不只是一个终端上了吗？下载 AgentsRoom，在提供商兼容性矩阵里看看每个代理支持什么，并进一步了解多提供商支持。