MarkItDown – AI 时代的文档转换利器

01背景与简介

2024 年 12 月 13 日，Microsoft 正式开源了 MarkItDown，一个专为 AI 工作流设计的文件格式转换工具。 它诞生于 Microsoft Research 的 AutoGen 项目内部，核心使命只有一个： 将任意格式的文档转成干净、结构化的 Markdown，让大模型可以更好地理解。

发布仅两周，项目便在 GitHub 积累了超过 25,000 颗 Stars。截至今日， 它已成为 Microsoft 旗下最受欢迎的 Python 仓库之一，拥有 123K+ Stars、8.3K+ Forks， 这个数字在文件转换工具里堪称史无前例。

🌐 项目地址

https://github.com/microsoft/markitdown  — 99.7% Python，MIT 许可，当前稳定版 v0.1.4

02为什么选择 Markdown

主流大语言模型（GPT-4o、Claude、Llama 等）的训练语料中含有大量 Markdown 格式文本， 它们天然”会说” Markdown。相比直接扔进去一个 .docx 或 .pptx 的 XML 噪音， 结构干净的 Markdown 能让模型：

🎯

更好地理解层级结构

标题、列表、表格在 Markdown 中清晰呈现，模型无需猜测文档结构

🪙

节省 Token 消耗

Markdown 极度接近纯文本，相较于 HTML/XML 大幅减少无效 token，降低 API 成本

🔗

适配 RAG 管道

向量检索、分块切割在 Markdown 上效果更优，语义边界清晰

🔒

内存处理无临时文件

MarkItDown 全程内存处理，不产生临时文件，兼顾性能与安全

03安装指南

MarkItDown 要求 Python 3.10 或更高版本。建议使用虚拟环境隔离依赖。

创建虚拟环境（推荐）

 python -m venv .venv source .venv/bin/activate# Windows: .venv\Scripts\activate

基础安装（仅核心功能）

 pip install markitdown

安装全部可选依赖（推荐）

 pip install “markitdown[all]”# 包含 PDF、Office 文档、图片 OCR、音频转写等所有格式支持

按需安装特定格式

 pip install “markitdown[pdf]”# PDF 支持 pip install “markitdown[docx]”# Word 文档 pip install “markitdown[xlsx,pptx]”# Excel + PowerPoint

✅ 验证安装

运行 markitdown --version 或在 Python 中执行 from markitdown import MarkItDown，无报错即安装成功。

04支持的格式

MarkItDown 采用模块化转换架构，每种格式由独立的 DocumentConverter 类处理，可随时扩展。

📄

.pdf

PDF 文档

📘

.docx

Word 文档

📊

.xlsx

Excel 表格

📑

.pptx

PowerPoint

🌐

.html

网页文件

🖼️

图片

OCR + 元数据

🔊

音频

语音转文字

📋

.csv

逗号分隔值

🔧

.json

JSON 数据

📁

.zip

ZIP 压缩包

📰

.xml

XML 文件

📝

纯文本

.txt .md .rst

05基础用法

Python API — 转换本地文件

Python

from markitdown importMarkItDown# 实例化转换器md = MarkItDown()# 转换 PDFresult = md.convert("report.pdf")print(result.text_content)# 转换 Word 文档result = md.convert("proposal.docx")# 转换 Excel 表格（自动转为 Markdown 表格）result = md.convert("data.xlsx")# 转换 PowerPoint 演示文稿result = md.convert("slides.pptx")# 保存结果到文件withopen("output.md", "w", encoding="utf-8") as f:     f.write(result.text_content)

转换 URL（直接抓取网页）

Python

result = md.convert("https://example.com/article")print(result.text_content)

从文件流转换

Python

withopen("document.pdf", "rb") as f:     result = md.convert_stream(f, file_extension=".pdf")    print(result.text_content)

批量转换整个目录

Python

import osfrom pathlib importPathfrom markitdown importMarkItDownmd = MarkItDown() docs_dir = Path("./documents")for file in docs_dir.rglob("*"):    if file.suffix in {".pdf", ".docx", ".pptx", ".xlsx"}:        try:             result = md.convert(str(file))             output = file.with_suffix(".md")             output.write_text(result.text_content, encoding="utf-8")            print(f"✓ {file.name}")        exceptExceptionas e:            print(f"✗ {file.name}: {e}")

06进阶用法

图片描述（接入 LLM Vision）

MarkItDown 支持调用视觉模型为图片生成描述文字，使图片内容也能进入 AI 管道。

Python

from markitdown importMarkItDownfrom openai importOpenAIclient = OpenAI()  # 或使用其他兼容 OpenAI 协议的客户端md = MarkItDown(     llm_client=client,     llm_model="gpt-4o-mini"# 指定视觉模型)# 图片将被自动描述为 Markdown 文本result = md.convert("architecture_diagram.png")print(result.text_content)

音频文件转写

Python

# 会议录音 → Markdown 文字稿result = md.convert("meeting_recording.mp3")print(result.text_content)

ZIP 压缩包批处理

Python

# 直接处理 ZIP 包，自动遍历其中所有文件result = md.convert("documents_bundle.zip")print(result.text_content)# 所有文件内容合并为一个 Markdown 文档

自定义插件扩展新格式

Python

from markitdown importMarkItDown, DocumentConverter, DocumentConverterResultclassMyCustomConverter(DocumentConverter):    defconvert(self, local_path, **kwargs) -> DocumentConverterResult:        withopen(local_path) as f:             content = f.read()        # 处理自定义格式，返回 MarkdownreturnDocumentConverterResult(             title="My Document",             text_content=f"# Converted\n\n{content}"         )  md = MarkItDown() md.register_converter(MyCustomConverter())  # 注册插件

07命令行工具

MarkItDown 同时提供功能完整的命令行界面，无需编写任何代码即可完成转换。

基本转换

 markitdown report.pdf# 输出到 stdout

输出到文件

 markitdown slides.pptx-oslides.md

从 URL 转换

 markitdown https://example.com/page-opage.md

管道组合（配合其他工具）

 markitdown document.docx | wc -w# 统计文档字数 markitdown data.xlsx | grep “关键词”# 在表格内容中搜索

⚠️ 注意

命令行转换图片/音频时，需要通过环境变量或参数传入 OpenAI API Key 以启用 LLM 描述功能： OPENAI_API_KEY=sk-xxx markitdown photo.jpg

08RAG 实战场景

MarkItDown 最核心的使用场景是为 RAG（检索增强生成）管道准备高质量数据。

原始文件

PDF / DOCX / XLSX

→

MarkItDown

格式转换

→

文本分块

Chunking

→

向量嵌入

Embedding

→

向量数据库

检索存储

构建企业知识库

Python — RAG 准备流水线

from markitdown importMarkItDownfrom pathlib importPathimport json  md = MarkItDown() knowledge_base = []for file inPath("./company_docs").rglob("*.*"):    try:         result = md.convert(str(file))        if result.text_content.strip():             knowledge_base.append({                "source": str(file),                "content": result.text_content,                "title": result.title or file.stem             })    except:        pass# 保存为 JSONL，直接供嵌入模型使用withopen("knowledge_base.jsonl", "w") as f:    for doc in knowledge_base:         f.write(json.dumps(doc, ensure_ascii=False) + "\n")print(f"✅ 已索引 {len(knowledge_base)} 份文档")

09MCP 集成

MarkItDown 原生支持 Model Context Protocol (MCP)， 可直接作为 MCP Server 集成到 Claude Desktop、Cursor 等支持 MCP 的 AI 工具中， 让 AI 助手能够直接调用文件转换能力。

安装 MCP 服务

 pip install “markitdown[mcp]”

在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件 claude_desktop_config.json：

JSON — claude_desktop_config.json

{  "mcpServers": {    "markitdown": {      "command": "python",      "args": ["-m", "markitdown.mcp"]     }   } }

配置完成后，Claude Desktop 重启即可直接对话：”帮我把这个 PDF 转成 Markdown”。

10总结

MarkItDown 的成功并非偶然。它精准切中了 AI 工程化落地中一个被忽视已久的痛点： 如何把现实世界中杂乱的文档格式，高质量地”喂”给大模型。

它不试图做全功能的文档处理平台，而是专注于一件事——转成 Markdown——并把这件事做到极致： 模块化架构易于扩展、内存处理兼顾性能与安全、MCP 集成无缝融入 AI 工作流。

🚀 快速开始

三行代码体验 MarkItDown：pip install "markitdown[all]"from markitdown import MarkItDownprint(MarkItDown().convert("your_file.pdf").text_content)

无论是构建 RAG 知识库、准备 LLM 微调数据集，还是日常的文档预处理工作， MarkItDown 都值得成为你 AI 工具箱中的常驻工具。