如何用 MarkItDown 3步把办公文档转成 Markdown：LLM 文档处理完整指南
【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown
MarkItDown 是一个轻量 Python 工具，能把 PDF、Word、PPT、Excel、图片和音频一键转成 Markdown，并保留标题、列表、表格等结构。它是新手把文档喂给大模型做摘要、问答的首选工具。
想把一堆 PDF 喂给大模型时
你手里有一批扫描件、合同和产品手册，想让模型帮你总结。传统做法很折腾：用 PDF 库提文字，表格全糊成一团；手动复制进 Word，二十个文件就累趴。MarkItDown 把这套流程压缩成一条命令：自动识别文件格式，转成 Markdown，同时保留文档结构。输出可以直接喂给 GPT 等模型，转换质量足够稳定，可以放心用在生产流程里。
快速跑通：2步完成安装和第一次转换 🚀
一条命令安装完事，[all]附加项会装齐所有格式依赖，不用逐个配置：
pip install 'markitdown[all]'Python 里最简用法只有 5 行：
from markitdown import MarkItDown md = MarkItDown() result = md.convert("test.pdf") print(result.text_content)命令行也一样：markitdown工具随 MarkItDown 一起安装，markitdown test.pdf -o test.md效果相同。全新环境里直接就能跑，不需要任何云服务配置。
场景实战：3个最常用的文档转换场景 📄
扫描件发票和报告：用 OCR 救回来
扫描版 PDF 本身没有文字层，常规提取出来是空的。装上 MarkItDown OCR 插件，再在转换时传一个视觉模型客户端，页面上图片里的文字就会被识别并插回原文位置：
pip install markitdown-ocr效果就是：扫描发票、合同、报告变成可搜索、可归档的 Markdown，归档检索不再靠人眼。
让大模型"看懂"文档里的图片
PPT 和图片文件里有大量提不出来的文字信息。给 MarkItDown 传llm_client和llm_model两个参数，它就会让模型为图片生成文字描述；搭配 OCR 插件，图里的文字也会被一并提取。下图就是仓库测试用例里用来验证图片描述能力的样例图：
网页和音频也走同一条流水线
HTML 页面、RSS、YouTube 链接、WAV 和 MP3 录音，都走同一个convert()入口。网页转成干净的 Markdown，音频转成文字（装[audio-transcription]依赖即可）。多种来源的文档处理，一个接口就够，后面直接拼接成一份长文喂给模型就行。
参数速查
| 参数 | 作用 | 建议值 |
|---|---|---|
[all]（可选依赖） | 装齐所有格式的转换依赖 | 新手直接全选 |
llm_client | OpenAI 兼容客户端，用于图片描述和 OCR | 需要视觉功能时必传 |
llm_model | LLM 调用的模型名 | gpt-4o |
llm_prompt | 自定义图片描述 / OCR 提取提示词 | 特殊文档才需要 |
enable_plugins | 启用 markitdown-ocr 等第三方插件 | 需要 OCR 时设为True |
避坑清单：4个最常见的报错 ⚠️
- 转换时提示找不到转换器：对应格式的可选依赖没装。按需要装，如
pip install 'markitdown[pdf, docx]'。 - 扫描版 PDF 转出来是空的：文件没有文字层，内置转换器只读文字。加装 markitdown-ocr 插件并传
llm_client。 - OCR 静默不生效：没传
llm_client时插件仍会加载，但 OCR 被跳过。llm_client和llm_model必须一起传。 - 把不可信文件直接丢给
convert()：该接口也接受网络地址。只处理本地文件时，改用convert_local()更安全。
写在最后：从手头那批文档开始
MarkItDown 把"读办公文档 → 转 Markdown → 喂给大模型"压缩成一次调用，是搭 RAG 流水线、做文档归档的实用基础工具。建议先跑通上面 5 行示例，再把你手头那批 PDF 转一遍，效果立刻可见。
延伸阅读：markitdown-ocr 插件文档 packages/markitdown-ocr/README.md，源码入口 _markitdown.py
【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
