MarkItDown 文档转换实战指南：把 PDF、Word、Excel 变成大模型能读的 Markdown

MarkItDown 文档转换实战指南：把 PDF、Word、Excel 变成大模型能读的 Markdown

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

有一份会议记录的 PDF 要喂给大模型，表格乱成了一团字；想分析一份 Excel 报价单，还得先手工把格式清一遍——你可能花了一下午在清理数据，而不是写代码。MarkItDown 文档转换就是为这种麻烦准备的：一个轻量级 Python 工具，一条命令把 PDF、Word、Excel 等办公文档变成 Markdown，标题、列表、表格结构都保留，大模型直接就能读。

项目速览：它到底能干什么

一句话定位：MarkItDown 是微软 AutoGen 团队出的工具，只干一件事——把各种文件转成 Markdown，给 LLM 和文本分析流水线消费。

为什么选 Markdown 而不是纯文本？因为主流大模型天生"会说"Markdown：GPT-4o 等模型不提示就会在回复里用 Markdown，说明它们见过足够多的这类文本，理解得很熟；而且 Markdown 的 token 开销也小。一句提醒：它的输出是优先给机器读的，人看"过得去"，但不以排版见长。

三步上手：一条命令完成 PDF转Markdown

前提是 Python 3.10 以上，建议用虚拟环境装。安装和转换一共两行：

pip install 'markitdown[all]' markitdown path-to-file.pdf -o document.md

第一步，装。[all]装全量格式依赖；只转几种格式就按需装，比如pip install 'markitdown[pdf, docx]'只引入 PDF 和 Word 的支持。

第二步，转。零配置：没有 key、没有配置文件，装上就能跑。-o指定输出文件，或者直接markitdown file.pdf > out.md重定向；也可以管道输入：cat file.pdf | markitdown。

第三步，看结果。用任何编辑器打开document.md，标题和表格已经分好层；在 Python 里调用时，result.markdown就是转换后的完整 Markdown。

判断标准很简单：转完扫一眼，标题层级对不对、表格断没断行。拿你手头任意一个 PDF 跑一遍上面两行，第一轮体验就完整了。

一个机制讲透：像"打印机驱动"一样的转换器

MarkItDown 凭什么认识这么多格式？答案：主程序只管分发，每种格式有各自的转换器。

类比打印机驱动：系统不关心驱动内部怎么出墨，只问两件事——"你能不能接这个文件"（accepts）和"把它打出来"（convert）。主程序按顺序问每个转换器，谁说自己能处理，谁就接手。文件类型由 magika 库识别，所以没有扩展名的文件通常也能认出来。

想给新格式写转换器，骨架长这样：

from markitdown import DocumentConverter, DocumentConverterResult class MyFormatConverter(DocumentConverter): def accepts(self, file_stream, stream_info, **kwargs): return stream_info.file_extension == ".myfmt" def convert(self, file_stream, stream_info, **kwargs): return DocumentConverterResult(markdown="...")

第三方插件走的是同一套注册机制。比如 markitdown-ocr 插件用 LLM 视觉能力识别 PDF 和 Office 文档里嵌的图片文字，不引入额外 ML 库，但需要传入 LLM 客户端。插件默认关闭：命令行加--use-plugins启用，markitdown --list-plugins查看已装插件。

其余机制一笔带过：Azure Document Intelligence 和 Content Understanding 也以内置转换器的形式接进来，给构造器传 endpoint 就能用；代价是每次转换都是一次计费的云端调用，用之前想清楚要不要上云。

三个高频实战场景

文档转Markdown喂给大模型

问题：转出来的内容还要交给 LLM 做总结、问答或入 RAG。链路就两步：先转换，再丢给模型。

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown() client = OpenAI() content = md.convert("paper.pdf").markdown resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": f"总结这篇论文的核心观点：\n{content}"}], ) print(resp.choices[0].message.content)

避坑提示：判断转换质量的标准是"大模型读得顺不顺"，不是"排版漂不漂亮"；投喂前先看一眼表格有没有串行，串了就该换 Azure 服务。

批量转换一个文件夹

问题：目录里几十个文件，不想一条条敲命令。写个 for 循环，两个要点：MarkItDown()实例放在循环外创建、循环内复用；每个文件包一层 try/except，坏掉一个文件不中断整批，把失败名单记下来回头查。

避坑提示：遇到没有扩展名或扩展名奇怪的"文件"，先确认 magika 识别出的是什么类型，再决定要不要转，别盲目全量跑。

用 Docker 部署到生产

问题：服务器环境和本地对不上。仓库根目录自带 Dockerfile，两条命令：

docker build -t markitdown:latest .

docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

容器从标准输入读、向标准输出写，可以直接嵌进现有流水线。

避坑提示：生产里如果启用了 Azure 服务，注意每次转换都是一次计费调用，用cu_file_types圈定哪些格式走云端，其余留本地。

避坑与常见疑问

问：Word、PowerPoint 文件为什么报缺依赖？答：格式支持是可选依赖，用括号装：pip install 'markitdown[pdf, docx, pptx]'；图省事就装[all]。

问：转出来的 Markdown 能直接排版发文章吗？答：不能。官方定位就是给文本分析工具消费的，布局"过得去"但不高保真；要给人看的正式出版物，请选专门的排版工具。

问：扫描版 PDF 怎么办？答：本地内置转换不带 OCR。两条路：启用 markitdown-ocr 插件（用 LLM Vision 识别图片文字，传入llm_client即可）；或走 Azure Document Intelligence / Content Understanding（云端做版面分析和 OCR，能处理复杂表格，按次计费）。

问：图片文件转出来是什么？答：默认是 EXIF 元数据。传入llm_client和llm_model后，pptx 和图片文件可以让 LLM 生成图像描述。

问：服务器上能直接转用户上传的文件吗？答：要谨慎。convert()同时接受本地文件、远程链接和字节流，权限和你进程能访问的范围一致；服务端调用请用最窄的convert_local()或convert_stream()，输入先做校验。

MarkItDown 文档转换的价值就一句话：把你手里的杂格式文档变成大模型能读的 Markdown。现在装一次pip install 'markitdown[all]'，然后对那个最头疼的文件跑一下 markitdown。

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown