Microsoft MarkItDown 使用笔记

1. 它是什么

MarkItDown 是一个轻量级 Python 包和命令行工具，主要解决“各种文件怎么转成 LLM 友好的 Markdown”这个问题。

它和传统文档转换工具的取向不太一样。很多工具追求版式还原，比如 Word 转 PDF、PPT 转图片、PDF 转 HTML；MarkItDown 更关心文本分析管线需要什么：标题、列表、表格、链接、正文层次、元数据，以及尽可能干净的 Markdown。官方 README 也明确说，它的输出通常可读，但不一定适合做人类消费的高保真文档转换。

我理解它最适合放在这几类工作流里：

• 把客户 PDF/PPT/Word/Excel 材料转成 Markdown，再交给大模型分析。
• 给 Obsidian、知识库、RAG 系统做资料入库前的格式清洗。
• 在 Agent 工作流里，把本地文件或 URL 转成模型容易读的文本。
• 通过 MCP server 给 Claude Desktop、Codex、OpenClaw 这类 Agent 暴露“文件转 Markdown”工具。

2. 基本信息

检查日期：2026-08-06。版本、Star、Release、依赖版本都可能变化，正式使用前建议再看 PyPI 或 GitHub Release。

3. 适合用来做什么

4. 不适合用来做什么

1. 不适合做高保真格式转换。比如要求 Word 样式、页眉页脚、分页、字体、版面完全保留，应该找专门的文档排版/转换工具。
2. 不适合无筛选地处理不可信输入。官方安全说明强调，MarkItDown 会以当前进程权限执行 I/O，能访问当前进程能访问的本地文件和网络资源。
3. 不适合直接暴露成公网服务。特别是 markitdown-mcp 的 HTTP/SSE 模式，官方明确建议默认只绑定 localhost，不要随便绑到外网地址。
4. 不适合指望一次转换就得到完美知识库笔记。它负责抽取和转换，后续标题重组、摘要、术语解释、图片筛选、人工校对仍然需要做。
5. 不适合把所有格式都装成最大依赖后扔进生产环境。生产里更建议按格式安装可选依赖，减少攻击面和依赖冲突。

5. 支持的输入格式

官方 README 提到当前支持：

• PDF
• PowerPoint
• Word
• Excel
• 图片：EXIF 元数据和 OCR/图像描述相关能力
• 音频：EXIF 元数据和语音转录
• HTML
• 文本格式：CSV、JSON、XML
• ZIP 文件：会遍历其中内容
• YouTube URLs
• EPubs
• 其他格式

从 PyPI 和 pyproject.toml 看，核心依赖包括 beautifulsoup4、requests、markdownify、magika、charset-normalizer、defusedxml。不同格式通过 optional dependencies 解锁。

6. 安装与依赖

基础要求

MarkItDown 要求 Python 3.10 或更高。官方建议使用虚拟环境，避免和系统 Python 或其他项目依赖冲突。

普通 venv：

python -m venv .venv
source .venv/bin/activate

用 uv：

uv venv --python=3.12 .venv
source .venv/bin/activate
uv pip install 'markitdown[all]'

用 conda：

conda create -n markitdown python=3.12
conda activate markitdown

从 PyPI 安装

最省事的安装方式：

pip install 'markitdown[all]'

只装部分格式依赖：

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

从源码安装：

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

7. 可选依赖怎么选

我的建议：个人电脑上试用可以直接 [all]；放到项目或服务器里，最好按实际文件类型安装。比如只处理 Office + PDF，就装 [pdf,docx,pptx,xlsx]，没必要把音频、YouTube、Azure 相关依赖都带上。

8. CLI 快速开始

最常用命令：

markitdown path-to-file.pdf > document.md

指定输出文件：

markitdown path-to-file.pdf -o document.md

管道输入：

cat path-to-file.pdf | markitdown

配合批处理时，我更喜欢显式写输出路径，方便后续检查：

markitdown 客户方案.pdf -o 客户方案.md
markitdown 需求说明.docx -o 需求说明.md
markitdown 产品介绍.pptx -o 产品介绍.md
markitdown 数据表.xlsx -o 数据表.md

9. Python API 用法

基础用法：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

如果只需要转换本地文件，安全上更建议使用更窄的 API。官方安全说明里提到，convert() 比较宽松，可以处理本地文件、远程 URI 和字节流；如果只处理本地文件，优先用 convert_local()；如果需要自己控制网络请求，可以先用 requests.get()，再把响应交给 convert_response()；如果要最大控制，打开 stream 后用 convert_stream()。

用 Azure Document Intelligence：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="")
result = md.convert("test.pdf")
print(result.text_content)

给图片或 PPTX 中的图片生成描述：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="optional custom prompt",
)
result = md.convert("example.jpg")
print(result.text_content)

10. 插件机制

MarkItDown 支持第三方插件，但默认关闭。

列出已安装插件：

markitdown --list-plugins

启用插件转换：

markitdown --use-plugins path-to-file.pdf

Python 里启用：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("path-to-file.rtf")
print(result.text_content)

官方仓库里有 packages/markitdown-sample-plugin，示例了怎么实现自定义 DocumentConverter、注册 register_converters()，并通过 pyproject.toml 的 markitdown.plugin entry point 暴露插件。

11. OCR 插件

仓库里有 markitdown-ocr 插件，目标是给 PDF、DOCX、PPTX、XLSX 中嵌入的图片提取文字。它复用 MarkItDown 现有的 llm_client / llm_model 模式，不额外引入本地 OCR 大模型或二进制依赖。

安装：

pip install markitdown-ocr
pip install openai

命令行使用：

markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o

Python 使用：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)

result = md.convert("document_with_images.pdf")
print(result.text_content)

几个关键点：

• PDF：可提取嵌入图片；扫描 PDF 会按页渲染成图片后交给 LLM Vision。
• DOCX：会在文档流中插入 OCR 文本块，尽量保留上下文。
• PPTX：处理图片 shape、placeholder 图片、group 里的图片。
• XLSX：图片会列在工作表数据后的 Images in this sheet 区域。
• 输出 OCR 块会包在 [Image OCR] ... [End OCR] 里。
• 如果没有传 llm_client 或 llm_model，插件会加载，但 OCR 会跳过，回退到内置转换器。

这点很实用：很多客户资料里的关键内容其实是截图、扫描页或 PPT 图片。普通文本抽取会漏，OCR 插件能补一块。不过它会调用 LLM Vision，意味着有 API 成本、数据出境和隐私合规问题。

12. Azure Content Understanding

README 专门介绍了 Azure Content Understanding。它适合需要更高质量解析、结构化字段抽取、多模态处理的场景。

安装：

pip install 'markitdown[az-content-understanding]'

CLI：

markitdown path-to-file.pdf --use-cu --cu-endpoint ""

Python：

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="")
result = md.convert("report.pdf")
print(result.markdown)

指定自定义 analyzer：

md = MarkItDown(
    cu_endpoint="",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)

适合用 Azure Content Understanding 的情况：

• 扫描 PDF、复杂表格、多页文档，内置转换效果不够。
• 需要从发票、收据、合同里抽结构化字段。
• 要处理音频、视频等多模态文件。
• 已经在 Azure 环境里，能接受 API 调用成本和数据合规路径。

成本提醒：每次走 CU 的 convert() 都是 Azure API 调用。可以用 cu_file_types 限制哪些格式走 CU，避免所有文件都误走云端。

13. Azure Document Intelligence

如果只想用 Azure Document Intelligence 做文档转换：

markitdown path-to-file.pdf -o document.md -d -e ""

Python：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="")
result = md.convert("test.pdf")
print(result.text_content)

和 Azure Content Understanding 相比，Document Intelligence 更偏文档布局解析；Content Understanding 则覆盖更多模态，并能通过 analyzer 做结构化字段抽取。

14. MCP Server

markitdown-mcp 是 MarkItDown 的 MCP server 包，适合给本地可信 Agent 使用。它暴露一个工具：

convert_to_markdown(uri)

uri 可以是 http:、https:、file: 或 data: URI。

安装：

pip install markitdown-mcp

默认 STDIO 启动：

markitdown-mcp

HTTP/SSE 模式：

markitdown-mcp --http --host 127.0.0.1 --port 3001

Docker：

docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest

如果要访问本地文件，需要挂载目录：

docker run -it --rm -v /home/user/data:/workdir markitdown-mcp:latest

安全提醒很重要：MCP server 没有认证，会以启动它的用户权限运行。HTTP/SSE 默认绑定 localhost 是有原因的。不要把它绑定到 0.0.0.0 暴露到局域网或公网，除非你清楚文件读取和网络访问风险，并做了沙箱隔离。

15. Docker 用法

主仓库也支持 Docker：

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Docker 的好处是依赖隔离，尤其适合在服务器或 CI 里批量转换文件。缺点是本地文件访问要挂载目录，且一些需要云 API、音频处理或插件的场景要额外配置环境变量和依赖。

16. 和 Obsidian 的搭配

MarkItDown 很适合做 Obsidian 资料导入的第一步。

推荐流程：

1. 把原始 PDF/PPT/Word/Excel 放进资料目录。
2. 用 MarkItDown 转出 Markdown。
3. 人工或用 Agent 做二次整理：补标题、摘要、标签、来源、图片说明、关键结论。
4. 放入 Obsidian 的 07-学习资料 或具体项目目录。

示例：

markitdown 客户材料.pdf -o 客户材料.raw.md

然后让 Agent 整理成：

• 客户材料 摘要.md
• 客户问题清单.md
• 技术方案要点.md
• 待确认事项.md

不要直接把所有转换结果都当最终笔记。转换结果更像原料，Obsidian 里真正有价值的是整理后的结构化笔记。

17. 和 RAG / 知识库的搭配

做 RAG 入库时，MarkItDown 可以承担“格式归一化”这一步。

一个常见流程：

原始文件 -> MarkItDown 转 Markdown -> 清洗/分块 -> 向量化 -> 入库 -> 检索问答

它比直接把 PDF 二进制丢给模型更可控，因为 Markdown 里保留了标题、列表、表格、链接，后续分块时更容易按章节和段落切。

不过要注意：

• 表格转换质量要抽样检查。
• PDF 页眉页脚可能产生噪声。
• 扫描件需要 OCR，不要指望普通 PDF 抽取拿到文字。
• 转换后的 Markdown 还要做去重、分块、元数据补充。
• 敏感材料不应直接走云端 OCR 或外部 LLM Vision。

18. 典型使用场景

19. 常见问题与排坑

20. 安全注意事项

官方 README 的安全提醒值得单独记下来：MarkItDown 会以当前进程权限进行 I/O，类似 open() 或 requests.get()，能访问当前进程本来就能访问的资源。

如果在本地个人电脑转换自己的资料，问题通常不大。可一旦放到 Web 服务、企业后台、Agent 自动化平台里，就要认真控制输入：

• 限制可访问的本地目录，不允许用户随便传 file:///。
• 限制 URL scheme，只允许 https 或白名单域名。
• 阻止访问内网地址、loopback、link-local、metadata service。
• 对上传文件做类型、大小和压缩包层级限制。
• 使用 convert_local()、convert_stream()、convert_response() 这类更窄 API。
• 对 MCP server 做本机绑定、容器隔离和最小权限运行。

这不是小题大做。文档转换工具一旦能读文件、访问 URL、解压 ZIP，就天然有文件读取、SSRF、压缩包炸弹、敏感信息泄露这些风险。

21. 维护状态和生态

MarkItDown 的维护信号很强：

• GitHub Star 很高，关注度大。
• 最新 Release 是 2026-07-29 的 v0.1.7。
• 最近代码推送也在 2026-07-29。
• PyPI 包同步到 0.1.7。
• 仓库包含主包、MCP server、OCR 插件、示例插件。
• 采用 MIT License，适合商业和内部项目中使用，但仍要遵守许可证文本和 Microsoft 商标声明。

但也要看到它仍标注为 Beta。生产项目里不要只因为是 Microsoft 仓库就跳过测试。至少要准备一组自己的样本文档：PDF、扫描件、PPT、表格、合同、图片混排材料，逐类看输出效果。

22. 对售前工作的价值

MarkItDown 对售前最直接的价值不是“给客户卖一个转换工具”，而是让资料处理更顺。

售前经常会收到客户发来的 PDF、PPT、Word、Excel、截图包。手工看很慢，直接丢给大模型又容易超上下文、丢结构、文件格式不兼容。MarkItDown 可以先把材料变成 Markdown，再让模型做：

• 需求点抽取
• 业务流程梳理
• 技术架构摘要
• 风险和待确认事项列表
• PPT 大纲生成
• RAG 知识库预处理
• 项目交付文档初稿

在客户沟通里可以这样讲：我们不是只把文件“上传给模型”，而是先把多格式材料统一成可检索、可分块、可追踪来源的文本，再进入知识库或 Agent 流程。MarkItDown 可以作为其中一个轻量转换组件。

23. 我的使用建议

个人学习和 Obsidian 资料整理：直接装 [all]，先用 CLI 跑起来。

项目 PoC：按文件类型装依赖，保留原始文件和转换后的 Markdown，抽样检查表格、页码、标题层级、图片文字。

企业生产：把 MarkItDown 放在沙箱或容器里，限制输入路径和网络访问。扫描件、票据、复杂表格不要只靠默认转换，提前评估 OCR 或 Azure Content Understanding。

和 Agent 搭配：优先用 MCP server 给本地可信 Agent 使用，公网场景要非常谨慎。最稳妥的方式是让服务端自己控制文件下载和权限，再把流交给 MarkItDown，而不是让用户输入任意 URI。

24. 参考资料

• GitHub 仓库：microsoft/markitdown
• PyPI：markitdown
• 主包配置：packages/markitdown/pyproject.toml
• MCP server：packages/markitdown-mcp
• OCR 插件：packages/markitdown-ocr
• 示例插件：packages/markitdown-sample-plugin
• 最新 Release：v0.1.7
• Azure Content Understanding：Microsoft Learn
• Azure Document Intelligence：Microsoft Learn
• 安全报告：MSRC