MarkItDown | 微软开源文件转 Markdown 工具 – CLI/Python API

MarkItDown 是 Microsoft 开源的 Python 文件转 Markdown 工具，采用 MIT 许可，可处理 PDF、Office、HTML、图片、音频等输入。它更适合文档入库、RAG 预处理和智能体阅读：尽量留下标题、列表、表格与正文结构，让后面的检索和分析有内容可用。

把文件变成 .md 只是其中一步。资料库能不能找回答案，还取决于原文是否抽取正确、来源是否可追溯，以及后续如何分块和检索。这篇按文档进入处理流程的顺序，说明本地转换、额外识别与智能体接入各自负责什么。

先拿到可读文本，再判断哪些信息丢了

有文本层的 PDF 与扫描图片看起来都像“文档”，转换条件却不同。MarkItDown 不以复刻字体、分页和图形位置为目标，输出也不能替代原文件保存。转换复杂材料时，标题和表格出现了，并不表示阅读顺序、合并单元格或图中内容已经完整。

检查标题层级和正文顺序，尤其是多栏 PDF、页眉页脚和浮动文本框。
检查表格中的字段、单位与数值关系；需要计算时，不把 Markdown 表格当成原 Excel 公式和格式的完整副本。
检查重要内容是否在图片里。文本抽取为空或很少时，先判断是否需要 OCR，再选择对应转换路径。

批量处理前，可以先用一组代表性样本文档做这些检查。后续批处理保留原文件、文件标识和转换结果的对应关系，某条答案出现问题时，才找得到应该回看的那份原文。

Microsoft MarkItDown GitHub 项目卡片 — GitHub 为 microsoft/markitdown 自动生成的项目卡片。贡献者、Star 和 Fork 数为 2026 年 8 月 9 日抓取时的页面快照。

依赖安装跟着输入走

只处理 PDF、Word 和 PowerPoint，可以在独立 Python 环境里安装对应分组，再把单份结果写入文件。当前主分支元数据要求 Python >=3.10,<3.15，实际安装仍以选定版本为准。

pip install "markitdown[pdf,docx,pptx]"
markitdown report.pdf -o report.md

新旧 Excel 对应 xlsx、xls 分组，MSG 邮件对应 outlook。markitdown[all] 可以安装全部格式依赖，但不会自动启用第三方插件，也不会替你创建 OCR 或 Azure 服务账户。服务端依赖越多，镜像与升级时需要维护的部分也越多。

转换结果交给应用，来源信息由应用保留

在 Python 中读取一个本地文件，可以用更明确的 convert_local()：

from markitdown import MarkItDown

converter = MarkItDown(enable_plugins=False)
result = converter.convert_local("report.pdf")
print(result.markdown)

应用再保存来源标识、原文件位置和转换版本，随后按自己的检索设计切分内容。MarkItDown 提供转换结果，不负责替资料库建立索引、管理原文权限或保证问答正确。

输入来自上传服务时，应用仍需限制可读目录、文件大小和处理时间；来自网络时，先用受控请求取回内容，再交给 convert_response()。字节流可用 convert_stream()。这些方法帮助收窄输入方式，本身不构成权限隔离，也不会自动阻止访问内网或敏感文件。

普通抽取不够时，按缺失内容增加能力

嵌入图片里的文字：OCR 插件

markitdown-ocr 可为 PDF、DOCX、PPTX 和 XLSX 中的嵌入图片增加 LLM Vision 识别。需要安装插件、显式启用插件，并提供 llm_client 和 llm_model。没有客户端时，即使插件被加载，OCR 也会跳过而使用标准转换器。

插件默认关闭。命令行的 --list-plugins 用于查看，--use-plugins 才启用已安装插件。接入远程视觉模型时，文档图像会进入该服务的处理范围；保密材料应在选择路径时就确定允许发送的内容。

复杂文档与结构化字段：Azure 路径

Azure Document Intelligence 是可选文档解析服务；Content Understanding 还支持文档、图片、音频、视频和字段提取，可以把分析结果放进 YAML front matter。两者都需要对应云服务配置，不是基础本地转换默认拥有的能力。

Content Understanding 路由的调用会产生 Azure API 费用，可用 cu_file_types 限定哪些格式走云端。发票金额、日期等字段即便被提取出来，也应按业务规则检查，不能把结构化输出直接当作已核实事实。

接给智能体时，MCP 服务能读到什么

独立的 markitdown-mcp 包提供 convert_to_markdown(uri) 工具，支持 STDIO、Streamable HTTP 和 SSE。URI 可以指向 http:、https:、file: 或 data:，因此它获得的不只是某个上传文件，还可能包括进程有权读取的文件和网络资源。

官方 MCP 服务没有身份验证，定位是可信本地智能体使用。HTTP/SSE 默认绑定 localhost，不应直接把监听地址改成公网入口。即使只在本机运行，其他本机进程也可能访问；需要限制资料范围时，用低权限用户或隔离环境，只提供允许处理的目录。

二次开发转换器可从 packages/markitdown 和 packages/markitdown-sample-plugin 入手，智能体接入则看 packages/markitdown-mcp。固定所用版本和代表性样本，更新后检查转换结果，更容易发现只看命令返回状态时会漏掉的内容变化。

项目仓库与格式说明：https://github.com/microsoft/markitdown
MCP 使用与权限说明：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
OCR 插件：https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr

1.本站所发布资源部分收集于网络，仅限用于学习和研究测试使用。2.本站资源售价仅为赞助网站，赞助收费仅用于网站维护运营更新，感谢您的支持。3.本站仅保证资源的正常下载和测试使用，售后不包含相关技术咨询服务，请知悉谅解。4.本站所发布资源为非实物商品，不接受退款，请考虑好再进行支付赞助获取下载。
赞助获取下载注意：
1.支付赞助成功后请勿关闭窗口或其他操作，等待系统自动确认，按钮变为获取下载按钮。2.游客操作请使用 Chrome、Edge 或 FireFox 浏览器，以免支付刷新失败(浏览器缓存7天有效)。3.如支付赞助成功后刷新无法显示下载按钮、链接失效等问题请到 【公告留言】 处理或参考下载说明文档。

THE END