MarkItDown 项目说明

一、项目作用

MarkItDown 是微软 AutoGen 团队开源的一个轻量级 Python 工具，主要功能是把各种格式的文件转换为 Markdown 文本。

它的设计目标不是为了"人类阅读"的高保真排版，而是为 LLM（大语言模型）和文本分析流水线生产输入。Markdown 接近纯文本但能保留标题、列表、表格、链接等结构信息，而且主流 LLM（如 GPT-4o）“原生说 Markdown”，token 效率也高，所以非常适合作为 RAG、文档解析、AI Agent 的预处理层。它在用途上类似 textract，但更注重结构保留。

---

二、典型使用场景

场景	说明
RAG 知识库构建	把企业内 PDF/Word/PPT 统一转为 Markdown 后切块入向量库
LLM 上下文喂料	把异构文档变成 LLM 能高效消费的统一格式
AI Agent 工具	通过 markitdown-mcp 暴露为 MCP Server，供 Claude、Cursor 等 Agent 调用
文档批处理流水线	CLI + 管道，可在 shell / CI 中批量转换
OCR/多模态预处理	结合 LLM Vision 或 Azure Content Understanding 处理扫描件、音视频

---

三、主要特性

1. 支持的输入格式

• 办公文档：PDF、Word (docx)、PowerPoint (pptx)、Excel (xlsx/xls)、EPub、Outlook 邮件
• 网页与文本：HTML、CSV、JSON、XML
• 媒体：图片（EXIF 元数据 + OCR）、音频（EXIF + 语音转写）
• 特殊源：ZIP 包（递归处理）、YouTube 视频 URL（抓取字幕）

2. 多种调用方式

• 命令行 CLI
• Python API（from markitdown import MarkItDown）
• Docker 容器
• MCP Server（STDIO / Streamable HTTP / SSE）

3. 可扩展能力

• 插件系统：可加载第三方插件，GitHub 上以 #markitdown-plugin 标签发现；仓库内附 markitdown-sample-plugin 模板
• markitdown-ocr 插件：用 LLM Vision 对 PDF/DOCX/PPTX/XLSX 中嵌入的图片做 OCR
• Azure Document Intelligence：高质量云端 PDF 布局解析
• Azure Content Understanding：支持音视频、自定义分析器，可输出 YAML front matter 形式的结构化字段
• 自定义 LLM：为图片自动生成描述（支持任意 OpenAI 兼容客户端）

4. 三个独立子包（monorepo 结构）

packages/
├── markitdown/                  # 核心库 + CLI
├── markitdown-mcp/              # MCP Server 封装
├── markitdown-ocr/              # OCR 插件
└── markitdown-sample-plugin/    # 插件开发示例

5. 安全约束

工具以当前进程权限做 I/O；官方明确提醒不可直接传未经过滤的输入，并提供分级 API：convert()（最宽松）、convert_local()、convert_response()、convert_stream()（最窄），按需选用。

---

四、部署与使用

1. 前置条件

• Python ≥ 3.10（推荐 3.12）
• 建议使用虚拟环境（venv / uv / conda）

2. 安装

# 全功能安装（推荐）
pip install 'markitdown[all]'

# 按需安装
pip install 'markitdown[pdf,docx,pptx]'

可选依赖项包括：pptx / docx / xlsx / xls / pdf / outlook / az-doc-intel / az-content-understanding / audio-transcription / youtube-transcription。

3. 从源码安装

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

4. 命令行使用

# 转换并输出到 stdout
markitdown path-to-file.pdf > document.md

# 指定输出文件
markitdown path-to-file.pdf -o document.md

# 管道方式
cat path-to-file.pdf | markitdown

# 启用插件
markitdown --use-plugins path-to-file.pdf

# 列出已安装插件
markitdown --list-plugins

5. Python API

from markitdown import MarkItDown

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

结合 LLM 做图片描述：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o")
print(md.convert("example.jpg").text_content)

结合 Azure Content Understanding：

md = MarkItDown(cu_endpoint="<your-cu-endpoint>")
print(md.convert("meeting.mp4").markdown)

6. Docker 部署

仓库内自带 Dockerfile（基于 python:3.13-slim-bullseye，预装 ffmpeg / exiftool）：

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

7. 作为 MCP Server 给 Agent 使用

pip install markitdown-mcp

# STDIO 模式（默认，适合 Claude Desktop / Cursor 集成）
markitdown-mcp

# HTTP/SSE 模式（仅绑定 localhost，注意安全）
markitdown-mcp --http --host 127.0.0.1 --port 3001

它对外暴露一个工具 convert_to_markdown(uri)，支持 http:// / https:// / file:// / data: URI。

8. 开发与测试

cd packages/markitdown
pip install hatch
hatch shell
hatch test

# 提交 PR 前
pre-commit run --all-files

仓库根目录还提供 .devcontainer/，可直接用 VS Code Devcontainer 一键拉起完整开发环境。

---

五、小结

MarkItDown 本质上是把"异构文档 → Markdown"的能力封装成一个库 + 一个 CLI + 一个 MCP Server + 一个 Docker 镜像的产品矩阵，覆盖从开发者本地、批处理脚本到 AI Agent 调用的多种场景，特别适合作为构建 LLM 应用 / RAG / Agent 工具链时的文档预处理基座。