MarkItDown：把办公文档转成供 LLM 使用的 Markdown

如果你正在把说明书、报告和表格接入 LLM，首先要解决的往往是怎样把文件内容变成可继续处理的文本。微软的 MarkItDown 是一个 Python 转换工具：把多种文件转换为 Markdown，重点保留标题、列表、表格和链接，官方明确将其定位于 LLM 与文本分析流水线。它适合作为数据准备环节；仓库提供的是可嵌入其他系统的库和命令行工具。官方定位

以一份包含章节标题、参数表和截图的产品说明书为教学情境：输入可以是 PDF 或 Word 文件，经转换器提取后，输出 Markdown；命令行可以写入 .md 文件，Python 调用则通过 result.markdown 取得内容。官方列出的输入还包括 PowerPoint、Excel、HTML、CSV、JSON、XML、图片、音频和 EPUB 等。格式与调用示例

这里保留结构的意义很具体：标题帮助后续处理识别章节，表格表达参数与数值的对应关系，链接保留继续访问资料的入口。对于需要统一接收多种文档的开发者，这是一个值得考虑的优势。不过，这只是基于输出形式的工作流判断，不代表转换后就能保证检索或回答准确；如果要建设知识库，还需另行安排分块、索引和模型调用。

同一份说明书里的截图要单独看待。README 介绍的 markitdown-ocr 插件可通过 LLM Vision 提取 PDF、DOCX、PPTX、XLSX 内嵌图片的文字，需要安装插件、启用插件，并提供 llm_client 与 llm_model。没有提供客户端时，插件仍会加载，但会静默跳过 OCR，退回内置转换器。 因此，“生成了 Markdown”不能作为截图文字已被提取的证明。OCR 插件条件

MarkItDown 的明确限制是转换目标：官方强调输出主要供文本分析工具消费，高保真、面向人阅读的文档转换未必适合它。对上述说明书，评估重点应是章节是否完整、参数表关系是否正确、必要截图文字是否进入输出，而不是页面外观是否还原。这也决定了它更适合文档预处理开发者；如果你的交付物必须保留原版排版，可以跳过这条路线。官方限制说明

部署选择会改变成本和数据流向。README 将内置文档转换描述为离线、按格式提取，成本为本地计算；Azure Document Intelligence 与 Azure Content Understanding 则使用计费云端 API。这个离线说明应限定在内置文档转换路径，不能延伸为所有输入、插件和外部模型都完全离线。官方能力与成本对照

如果任务从“把报告转成文本”升级为“从发票中提取指定字段”，Content Understanding 是另一条路径：分析器字段会进入 Markdown 前部的 YAML front matter，也可配置自定义分析器。官方将扫描 PDF、复杂表格和多页文档列为其云端布局分析与 OCR 的适用场景；“更高质量”属于官方描述，本文没有实测比较。每次路由到 CU 的 convert() 都会产生计费 API 调用，可用 cu_file_types 限定哪些格式走云端。选用前需同时接受相应内容进入云端处理及服务费用，本地 Python 入口并不意味着内容留在本地。CU 配置与计费边界

开始时，官方要求 Python 3.10–3.14，并建议使用虚拟环境。已有该环境后，可按 README 安装并转换一份已知内容的 PDF：

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

预期产物是 document.md。[all] 安装全部可选依赖；只处理少数格式时，可以按需选择 PDF、DOCX、PPTX 等依赖。首次检查应围绕真实任务：正文缺失先区分普通文本与图片文字，再确认相应格式依赖、插件启用状态和模型客户端配置，不要直接把所有缺失都归为 OCR 问题。安装与可选依赖

若把转换接入上传服务，还需承担输入约束工作：官方说明它按当前进程权限访问资源，通用 convert() 可接收本地文件、远程 URI 和字节流。只处理本地文件时优先使用 convert_local()，已控制输入流时可使用 convert_stream()，并限制不可信输入的路径与网络目标。安全边界

项目代码采用 MIT 许可，分发副本或重要部分时须保留版权与许可声明；这份代码许可不替代所选云端服务的条件。LICENSE

本文依据所提供的固定提交文档整理，未运行安装或转换；安装命令沿用官方示例，未锁定包版本。

---

资料核验：2026-10-22。本文依据官方公开资料研究整理，未进行安装或性能测试。