MarkItDown：3 个命令把 PDF、Word、Excel 转成 Markdown，让大模型读得懂任何文件-平芜编程栈

MarkItDown：3 个命令把 PDF、Word、Excel 转成 Markdown，让大模型读得懂任何文件

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

MarkItDown 是微软 AutoGen 团队开源的一个轻量级 Python 文档转换工具，核心能力是把 PDF、Word、Excel、PowerPoint 等常见办公文件转换成保留结构的 Markdown 文本。如果你的工作里需要把大量文件喂给 LLM 做分析或检索增强生成（RAG），它值得放进工具链里。

📄 先把问题说清楚：文件喂给模型之前卡在哪

设想一个常见场景：你有一份几十页的 PDF 报告和几个 Excel 表格，想让大模型总结其中的数据。直接把这些文件丢给模型是不行的——模型只吃文本，而每种文件格式的解析方式都不同。更麻烦的是，用纯文本提取工具把内容抠出来之后，标题层级、表格行列、列表结构基本都丢了，模型拿到的只是一堆没有组织的文字，回答质量会大打折扣。

MarkItDown 要解决的就是这一步：在文件进入模型之前，把它变成结构化的 Markdown。

📄 MarkItDown 是什么，边界在哪

项目定位很明确：一个面向 LLM 和文本分析管线的文件格式转换器。它支持 PDF、PowerPoint、Word、Excel、EPub、HTML、CSV/JSON/XML 等文本格式、音频、图像（EXIF 元数据）、ZIP（遍历内部文件）、YouTube 链接等，共 15 类以上输入，运行环境要求 Python 3.10 到 3.14。

需要说清的一点是：它的输出"通常对人也可以读"，但主要设计目标是给文本分析工具消费，而不是追求排版级的高保真还原。如果你要的是像素级还原的文档转换，它不是对的工具；如果是为模型准备干净的输入文本，它正是为此设计的。

📄 安装与第一次转换

安装只需一条命令，[all]表示装齐所有可选格式依赖：

pip install 'markitdown[all]'

装完之后，命令行转换一个 PDF 到 Markdown，最短路径就是这样：

markitdown path-to-file.pdf -o document.md

也可以不落地中间文件，用管道把文件内容直接转出来：cat path-to-file.pdf | markitdown。不想装 Python 环境的读者可以用仓库根目录提供的 Dockerfile 构建镜像，以docker run --rm -i markitdown:latest < file.pdf > output.md的方式运行。

从源码安装的话，先git clone https://gitcode.com/GitHub_Trending/ma/markitdown，进入目录后执行pip install -e 'packages/markitdown[all]'即可。

📄 四个值得留意的能力

1. 结构是被保留的，不是只剩文字

转换结果中，标题会对应#、##等标记，表格变成 Markdown 表格，列表和超链接也都会保留。之所以选 Markdown 作为目标格式，是因为主流大模型在海量 Markdown 文本上训练过，对这种格式理解得最好，而且它的标记开销小、token 效率高。对你来说意味着：省掉了自己写后处理来重建文档结构的活。

2. 格式依赖可以按需安装

不想要全量依赖时，可以只装需要的部分，例如：

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

完整清单在 packages/markitdown/pyproject.toml 里，包括[xls]、[outlook]、[audio-transcription]、[youtube-transcription]等，装少了不影响其他格式的正常工作。

3. Python API 按用途选入口

在代码里集成只有几行：

from markitdown import MarkItDown md = MarkItDown() result = md.convert("test.xlsx") print(result.markdown)

convert()是最通用的入口，可以同时处理本地文件、远程 URI 和字节流。README 特别提示：如果你的应用只读本地文件，应该调用更窄的convert_local()；需要更细控制时还有convert_stream()和convert_response()。在服务器端处理用户上传的文件时，这个区分能明显降低风险。

4. 插件机制和 LLM 增强：处理图片里的文字

内置转换只处理文档里的文本层，文档里嵌入的图片文字是拿不到的。社区的markitdown-ocr插件（源码见 packages/markitdown-ocr/）用 LLM Vision 把 PDF、DOCX、PPTX、XLSX 中嵌入图片的文字识别出来，扫描件整页渲染后识别，对 MarkItDown 本体零侵入。启用方式就是命令行加两个参数：

markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o

同样的llm_client/llm_model参数不接插件时也能用：MarkItDown 本身支持让大模型给 PPTX 和图像文件生成描述，把OpenAI客户端和模型名传给MarkItDown()即可，仓库测试目录里就有这类测试素材：

插件默认不启用，markitdown --list-plugins可以列出已安装的插件。仓库还提供了一个可直接参照的插件模板：packages/markitdown-sample-plugin/，想支持 RTF 之类的新格式，照着写一个DocumentConverter就能发布独立包。

📄 不同输入类型的处理方式一览

输入类型	转换行为	适合什么时候用
PDF / Word / PPT / Excel	本地离线提取，保留标题、表格、列表结构	批量准备 RAG 语料、文档问答
图像、音频	提取 EXIF 元数据；可接 LLM 描述或语音转写	截图归档、会议录音整理
CSV / JSON / XML	按文本格式直接转 Markdown	数据文件入模型
ZIP	遍历包内文件逐个转换	一次处理整包文档
HTML / YouTube 链接	抓取页面正文或视频字幕	网页文章、线上讲座转文本

各格式的具体实现分散在 packages/markitdown/src/markitdown/converters/ 下，一个文件一个转换器，想确认某种格式实际怎么处理时看这里最直接。

📄 三个典型落地场景

企业知识库接入 RAG：把历史上散落在 PDF、Word、PPT 里的技术文档批量转成 Markdown，保留章节层级后再做分块和向量化。对搭建团队来说，省掉的是"每种格式各写一个解析器"的部分。

扫描件和图文混排文档：纯文本层的提取对扫描件无效，用markitdown-ocr插件配合任意 OpenAI 兼容的视觉模型，扫描页会被渲染成整页图片送识别，文字再插回文档流中。

给智能体装一个"读文件"工具：仓库里的 packages/markitdown-mcp/ 是一个 MCP 服务器，只暴露一个convert_to_markdown(uri)工具，支持 STDIO 和本地 HTTP/SSE 传输。配到支持 MCP 的客户端后，智能体就能自己把文件转成文本再回答，而不需要你在中间人肉搬运。