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 报告、Word 纪要、Excel 表格堆在桌上，你只想把它们变成一份能喂给大模型的 Markdown。MarkItDown 正是干这个的：微软开源的 Python 工具，一条命令把文档转成 Markdown。第一次听说它的人，看三分钟就够。

30 秒认识它

MarkItDown 是微软（AutoGen 团队）开源的 Python 包加命令行工具，核心任务就一件事：把各种文件转成干净的 Markdown。它最不可替代的地方在于"统一出口"——PDF、Word、Excel、PPT、图片、音频、HTML、CSV、ZIP、YouTube 链接等几十种格式，全部收敛成同一种文本，标题层级、表格、链接这些结构还能保留下来，输出可以直接进 RAG 索引或者丢给大模型做分析。想象一下：早上九点收到供应商发来的六种格式附件，中午前你就有一份结构完整的 Markdown 汇总。

环境搭建与首次运行

要求 Python 3.10 及以上，然后两步走完：

pip install "markitdown[all]" # [all] 会装齐各格式依赖 markitdown report.pdf -o report.md

跑通之后你会得到一个.md文件，内容就是原文档的文字和结构，没有多余噪音。

功能实战

日常高频场景就三类：办公三件套、PDF 长文档、带图的素材。

📄 ### 把 Word、Excel、PPT 变成 Markdown

三条命令覆盖最常见的办公格式：

markitdown report.docx -o report.md # Word 保留标题层级 markitdown data.xlsx -o data.md # Excel 变 Markdown 表格 markitdown 季度汇报.pptx -o slides.md # PPT 逐页输出

标题、列表、表格都会按原结构映射到 Markdown，喂给 LLM 时上下文顺序不乱。

📄 ### 处理 PDF 长文档

PDF 走的是本地解析，纯文本文档转换极快；超大文件可以走流式输入，避免整文件读进内存：

markitdown paper.pdf > paper.md # 直接重定向输出 cat 超长文档.pdf | markitdown > out.md # 流式输入，省内存

下面是测试集里一份学术论文 PDF 的首页，它的标题、作者、图表说明都能被完整抽出来：

🖼️ ### 让图片里的字"开口说话"

图片转换分两层：装了exiftool就先提取拍摄元数据，再挂一个多模态 LLM（比如 gpt-4o）自动生成画面描述，插进 Markdown 里：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o") result = md.convert("chart.jpg") # 图片转成带描述的 Markdown print(result.markdown)

左边这张红圆加蓝方块的测试图就是给这个功能用的，转出来的 Markdown 会包含对画面内容和文字的直接描述。

音频（mp3/wav）、HTML、CSV、RSS 这些格式同理，一条markitdown 文件就能出结果，这里就不展开了。

进阶与定制

👀 ### 给扫描件装上一双 OCR 眼睛

内置 PDF 解析只读文字层，纯图片扫描件得靠 LLM Vision。官方的 OCR 插件会先把文档里的图片抠出来发给多模态模型，再把文字按原位置插回去，扫描件整页 300 DPI 渲染后走同样的流程：

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)

接上 Azure 云端服务

对复杂表格或高要求场景，可以把提取环节交给 Azure 文档智能或内容理解服务，命令行加两个参数即可：markitdown 复杂表格.xlsx -d -e "<endpoint>"，或--use-cu --cu-endpoint "<endpoint>"走内容理解，还能指定 analyzer 做字段级结构化抽取。

📦 ### 写个批量转换脚本

CLI 面向单文件，批量就套个循环：

for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done

避坑与边界

几个我自己踩过、提前说能帮你省时间的点：

离线转换只读文字层。纯扫描的 PDF 转出来是空的或只有零星字，别怪工具，换 OCR 插件或 docintel 再说。
输出是给 AI 看的，不是给排版看的。跨页合并表格、多层嵌套布局会退化，别拿它替代 PDF 阅读器。
它用当前进程的权限做 I/O，和open()一个待遇。处理不受信任的输入时先做校验，Python 侧尽量用convert_local()这种最窄的接口，别直接convert()一个来路不明的 URL。
几百页塞满高清图的大 PDF 比较吃内存，建议先拆页再跑。