MarkItDown：把办公文档统一转成 Markdown，但别指望它做高保真转换
使用 Python 将文件和 Office 文档转换为 Markdown。
秒懂
- 它是什么？
- 微软开源的 MarkItDown 是一个 Python 工具，能把 PDF、Office 文档、图片、音频等转成 Markdown，目标读者是 LLM 和文本分析管道。它的输出适合机器消费，不适合追求排版还原的人类读者。
- 适合谁用？
- MarkItDown 适合那些需要把大量异构文档快速转成 Markdown 文本，再喂给 LLM 做检索、摘要或分类的工程师。它不适合需要保留原始排版、字体、页眉页脚的高保真转换场景。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题，谁该用它
MarkItDown 解决的是把各种格式的文件统一成 Markdown 文本的问题。PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV、JSON、XML、ZIP、YouTube 链接、EPub，这些格式在 README 里都被列为支持对象。它的目标不是给人看，而是给 LLM 和文本分析管道用。README 明确说输出“often reasonably presentable and human-friendly”，但“meant to be consumed by text analysis tools”。所以如果你要把一堆文档变成可检索的文本库，或者作为 RAG 管道的输入，它是合适的。如果你要生成一份排版精美的文档，它不适合。
转换机制：结构保留比视觉还原更重要
MarkItDown 的核心思路是保留文档的结构信息，而不是视觉细节。它把标题、列表、表格、链接这些元素转成 Markdown 对应的语法。比如 PDF 转换会尝试识别段落和标题，Word 和 PowerPoint 会提取文本和结构。对于图片和音频，它提取 EXIF 元数据，音频还能做语音转写。ZIP 文件会遍历内部内容。这种设计来自一个判断：LLM 训练时大量接触 Markdown，对 Markdown 的理解比纯文本好，而且 Markdown 的标记密度低，token 效率高。README 里说“Markdown conventions are also highly token-efficient”，这是它选择 Markdown 而非 HTML 或 PDF 的直接理由。但要注意，这种转换是尽力而为，复杂布局可能丢失，比如多栏排版或嵌套表格。
安装与命令行使用：一条命令上手
安装很简单，pip install 'markitdown[all]' 会装齐所有可选依赖。如果你想控制依赖，可以只装部分，比如 pip install 'markitdown[pdf, docx, pptx]'。命令行用法直接：markitdown path-to-file.pdf > document.md，或者用 -o 指定输出文件：markitdown path-to-file.pdf -o document.md。也支持管道输入：cat path-to-file.pdf | markitdown。Python API 也简单，从 README 的插件示例能看到 MarkItDown 类的用法，convert 方法返回结果对象，text_content 属性给出 Markdown 文本。安装前建议用虚拟环境，README 给了 venv、uv、conda 三种方式。注意，如果只用 uv 创建虚拟环境，安装包时要用 uv pip install，而不是 pip install。
插件机制：OCR 是重点，但默认关闭
MarkItDown 支持第三方插件，但默认不启用。命令行里用 markitdown --list-plugins 查看已安装插件，用 --use-plugins 启用。README 提到了 markitdown-ocr 插件，它给 PDF、DOCX、PPTX、XLSX 的转换器增加 OCR 能力，从嵌入图片中提取文字，用的是 LLM Vision，也就是和图片描述相同的 llm_client 和 llm_model 参数。安装方式是 pip install markitdown-ocr，再配一个 OpenAI 兼容客户端。使用时传入 llm_client 和 llm_model，比如 OpenAI() 和 gpt-4o。关键限制：如果不提供 llm_client，插件会加载但 OCR 会被静默跳过，退回内置转换器。这个设计有好处，不会因为缺依赖报错，但也会让你误以为 OCR 生效了。如果你依赖 OCR，必须在代码里显式传入客户端。
Azure Content Understanding：云端的更高保真选项
MarkItDown 内置转换器对扫描版 PDF、复杂表格和多媒体支持有限。README 指出 Azure Content Understanding 是更高保真的选项，安装方式为 pip install 'markitdown[az-content-understanding]'。它提供结构化字段提取，能输出 YAML front matter，比如发票金额、收据日期、合同条款。它还支持音频和视频，内置转换器没有视频支持，音频转写也较基础。Content Understanding 的定位是当内置能力不够时使用，尤其是需要领域特定字段提取的场景。这意味着 MarkItDown 的架构是可插拔的，后端可以换成云服务，但代价是你得依赖 Azure 的 API，可能产生费用和网络延迟。如果你的数据不能出内网，这个选项就不合适。
安全警告：权限模型与 untrusted 输入
README 开头有个 IMPORTANT 警告，说 MarkItDown 以当前进程的权限执行 I/O，就像 open() 或 requests.get() 一样。这意味着如果你让它处理一个恶意文件，它可能读取进程能访问的任何资源。文档建议在不可信环境中消毒输入，并且调用最窄的 convert 函数，比如 convert_stream() 或 convert_local()。这个警告不是空话，因为工具会解析各种格式，解析器可能有漏洞，而它又能访问文件系统。如果你在服务器上跑这个工具处理用户上传的文件，必须放在沙箱里，或者至少限制进程权限。这个设计是便利性和安全性的权衡，MarkItDown 选择不隔离，把责任交给调用者。
维护与升级成本，以及许可证
项目最近一次提交是 2026 年 7 月，版本号到了 v0.1.7，说明还在活跃开发，但版本号 0.x 意味着 API 可能不稳定。升级成本取决于你依赖的转换器，比如从 v0.1.5 升到 v0.1.7，如果内置转换器行为有变，你的输出可能变化，需要重新验证。可选依赖的粒度细，你可以只装需要的，减少依赖冲突。许可证是 MIT，这意味着你可以自由使用和修改，包括商用，只要保留版权声明。没有看到贡献指南或文档链接，但 README 提到有 documentation 的 Security Considerations 部分，具体路径没给出。如果你要长期依赖，建议锁定版本，并关注 release notes，因为 0.x 版本可能会有 breaking changes。
编辑结论
MarkItDown 适合那些需要把大量异构文档快速转成 Markdown 文本，再喂给 LLM 做检索、摘要或分类的工程师。它不适合需要保留原始排版、字体、页眉页脚的高保真转换场景。如果你要处理扫描版 PDF 或复杂表格，内置转换器可能不够，得考虑 Azure Content Understanding 或 markitdown-ocr 插件。在采用之前，先确认你的输入文件类型在支持列表里，并且用真实样本跑一遍 markitdown 命令，检查输出的 Markdown 结构是否满足下游需求。另外，注意安全警告：它像 open() 一样以当前进程权限读写资源，处理不可信输入时要先消毒。
社区笔记