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

MarkItDown 是 Microsoft 开源的一款 Python 文件转换工具，用于把 PDF、Word、PowerPoint、Excel、图片、音频、HTML、CSV、JSON、XML、ZIP、EPUB 和部分网络内容整理成 Markdown。它的目标不是复刻原文件的视觉排版，而是尽量保留标题、列表、表格、链接等结构，让文档更适合交给 LLM、检索系统和文本分析流程继续处理。

截至 2026 年 8 月 9 日核对时，MarkItDown 最新正式版本为 v0.1.7，要求 Python 3.10 或更高版本，采用 MIT 许可证。项目可作为命令行工具或 Python 库使用，还提供独立的 MCP Server 包与第三方插件机制；Azure Document Intelligence、Azure Content Understanding、LLM 图片描述和 OCR 插件属于可选扩展，不是离线基础转换的必要条件。

MarkItDown 保留的是文档结构，不是原始版式

MarkItDown 的输出重点是语义结构：标题层级转成 Markdown 标题，项目符号和编号继续保留为列表，表格尽量转换为 Markdown 表格，链接和正文按可分析的顺序输出。这种结果通常比直接提取纯文本更利于分块、检索、总结和问答，也比保存复杂 HTML 更节省上下文。

它并不承诺高保真视觉还原。复杂页眉页脚、浮动文本框、精确分页、字体、配色、图形位置和桌面排版可能丢失或发生重排。需要把 Office、PDF 原样转换为可供人阅读的精美网页或印刷文档时，应选择面向版式保真的转换器；MarkItDown 更适合把内容送入 LLM 或文本分析管线。

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

支持格式由可选依赖分组控制

最省事的安装方式是使用 markitdown[all]，一次启用项目声明的全部格式依赖；对生产环境更稳妥的做法是只安装实际需要的分组，减少依赖数量、镜像体积和潜在攻击面。

安装分组	主要用途	典型依赖或边界
`pdf`	PDF 文本与表格抽取	pdfminer.six、pdfplumber
`docx`	Word 文档	mammoth、lxml
`pptx`	PowerPoint 演示文稿	python-pptx
`xlsx` / `xls`	新旧 Excel 工作簿	pandas、openpyxl、xlrd
`outlook`	Outlook MSG 邮件	olefile
`audio-transcription`	WAV、MP3 语音转写	pydub、SpeechRecognition，识别后端另行评估
`youtube-transcription`	YouTube 字幕获取	受字幕可用性与平台访问条件影响
`az-doc-intel`	Azure Document Intelligence	需要 Azure 资源，调用会产生云端数据与费用边界
`az-content-understanding`	Azure Content Understanding	支持多模态与结构化字段，属于计费 API

README 同时列出图片 EXIF/OCR、HTML、文本格式、ZIP 遍历、EPUB、YouTube URL 等输入。具体效果与文件内容、解析依赖和上游服务有关，不能仅凭扩展名推断所有扫描件、复杂表格或受保护文档都能完整转换。

CLI 与 Python API 如何接入现有流程

命令行适合批处理脚本、CI 或临时转换。安装全部依赖后，可把结果写到标准输出，也可以通过 -o 指定文件。

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

如果项目只处理 PDF、Word 和 PowerPoint，可以安装更窄的依赖组合：

pip install 'markitdown[pdf,docx,pptx]'

Python API 适合在索引、上传处理或智能体工具中继续使用转换结果。基础调用返回的 text_content 可以交给后续分块、嵌入或总结模块。

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert_local("report.pdf")
print(result.text_content)

这里使用 convert_local() 是有意收窄输入范围。通用 convert() 可以处理本地文件、远程 URI 和字节流，服务器端若只需要本地文件，就不应无条件开放远程地址能力。

插件默认关闭，OCR 与自定义格式需要显式启用

MarkItDown 支持第三方插件，但默认不加载。命令行可先执行 markitdown --list-plugins 查看已安装插件，再通过 --use-plugins 显式启用。仓库中的 packages/markitdown-sample-plugin 展示了插件包结构和转换器注册方式。

markitdown-ocr 插件可为 PDF、DOCX、PPTX 和 XLSX 中的嵌入图片补充基于 LLM Vision 的文字识别。它复用 MarkItDown 的 llm_client 与 llm_model 配置；没有提供客户端时，OCR 会跳过并回退到标准转换器。由于文档图像可能包含隐私或商业信息，接入云端视觉模型前要确认上传对象、日志和服务条款。

Azure Content Understanding 适合复杂文档，但不是免费本地模式

Azure Content Understanding 可以处理文档、图像、音频和视频，并把预构建或自定义分析器提取的字段写入 YAML front matter。对于发票金额、合同条款、收据日期等结构化字段，它比基础格式转换更接近文档理解服务。

每次走 Content Understanding 的 convert() 都属于可计费 Azure API 调用，输入会进入相应云服务边界。可以用 cu_file_types 只让指定格式走云端，避免所有文件自动路由。单纯需要本地文本抽取时，没有必要为了“效果可能更好”默认启用云服务。

MarkItDown MCP 只应面向可信本地智能体

仓库中的 markitdown-mcp 包提供 STDIO、Streamable HTTP 与 SSE 三种方式，并暴露 convert_to_markdown(uri) 工具。这个 URI 可以是 http:、https:、file: 或 data:，因此能力边界不仅是“转换文档”，还包括读取当前进程能够访问的本地文件和网络资源。

官方文档明确说明该 MCP Server 没有身份验证，HTTP/SSE 默认绑定 127.0.0.1，用途是可信本地智能体。不要把它直接监听在公网或不受信任的局域网接口；需要跨主机调用时，应先通过容器、虚拟机、系统用户权限、网络访问控制和输入白名单限制文件与 URI 范围。