MarkItDown 使用教程

项目地址：https://github.com/microsoft/markitdown
作者：Microsoft | 协议：MIT | 语言：Python
版本：v0.1.5 | Stars：115k ⭐

一、什么是 MarkItDown？

MarkItDown 是微软开源的轻量级 Python 工具，专门将各种文件格式转换为 Markdown 格式，为 LLM（大语言模型）和文本分析管道而设计。

核心优势

二、支持的文件格式

三、安装

前置要求

• Python 3.10+

方式 1：pip 安装（推荐）

# 安装全部依赖（推荐新手）
pip install 'markitdown[all]'

# 按需安装，节省空间
pip install 'markitdown[pdf]'# 仅 PDF
pip install 'markitdown[docx]'# 仅 Word
pip install 'markitdown[pptx]'# 仅 PowerPoint
pip install 'markitdown[xlsx]'# 仅 Excel
pip install 'markitdown[pdf,docx,pptx]' # 多格式组合

方式 2：虚拟环境安装（项目隔离）

# 创建虚拟环境
python -m venv .venv

# 激活（Windows）
.venv\Scripts\activate

# 激活（Linux/macOS）
source .venv/bin/activate

# 安装
pip install 'markitdown[all]'

方式 3：从源码安装（开发者）

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

方式 4：Docker

# 构建镜像
docker build -t markitdown:latest .

# 使用（管道模式）
docker run --rm -i markitdown:latest < your-file.pdf > output.md

四、命令行使用

基础用法

# 转换文件，输出到终端
markitdown document.pdf

# 转换文件，保存到文件
markitdown document.pdf -o output.md

# 管道输入
cat document.pdf | markitdown

# 转换 Word 文档
markitdown report.docx -o report.md

# 转换 PowerPoint
markitdown presentation.pptx -o slides.md

# 转换 Excel
markitdown data.xlsx -o data.md

结合 Azure Document Intelligence（高精度 OCR）

markitdown document.pdf -o output.md -d -e "<your_document_intelligence_endpoint>"

插件管理

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

# 启用插件进行转换
markitdown --use-plugins document.pdf

五、Python API 使用

5.1 基础转换

from markitdown import MarkItDown

# 创建实例
md = MarkItDown(enable_plugins=False)  # True 则启用插件

# 转换文件
result = md.convert("document.pdf")

# 获取 Markdown 文本
print(result.text_content)

# 保存到文件
with open("output.md", "w", encoding="utf-8") as f:
    f.write(result.text_content)

5.2 转换不同格式

from markitdown import MarkItDown

md = MarkItDown()

# 转换 Word 文档
result = md.convert("report.docx")

# 转换 Excel
result = md.convert("data.xlsx")

# 转换 PowerPoint
result = md.convert("slides.pptx")

# 转换网页（URL）
result = md.convert("https://example.com/page.html")

# 转换 YouTube 视频（获取字幕）
result = md.convert("https://www.youtube.com/watch?v=xxxxx")

print(result.text_content)

5.3 使用 LLM 生成图片描述

from markitdown import MarkItDown
from openai import OpenAI

# 初始化 OpenAI 客户端
client = OpenAI()

# 配置 MarkItDown 使用 LLM
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="请详细描述图片中的内容"# 可选，自定义提示词
)

# 转换图片（LLM 会生成详细描述）
result = md.convert("photo.jpg")
print(result.text_content)

5.4 使用 Azure Document Intelligence

from markitdown import MarkItDown

# 配置 Azure Document Intelligence 端点
md = MarkItDown(docintel_endpoint="https://your-resource.cognitiveservices.azure.com/")

# 高精度 PDF 转换
result = md.convert("scanned_document.pdf")
print(result.text_content)

5.5 安全的流式转换

from markitdown import MarkItDown
import requests

md = MarkItDown()

# 方式一：仅处理本地文件（最安全）
result = md.convert_local("local_document.pdf")

# 方式二：处理 HTTP 响应流（可控 URI 获取）
response = requests.get("https://trusted-site.com/doc.pdf")
result = md.convert_response(response)

# 方式三：处理字节流（最高控制权）
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f)

print(result.text_content)

六、可选依赖一览

七、插件系统

启用内置 OCR 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX、XLSX 添加 OCR 能力，使用 LLM Vision 从图片中提取文字。

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,          # 启用插件
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)

# 含图片文字的 PDF 也能准确提取
result = md.convert("scanned_report.pdf")
print(result.text_content)

开发自定义插件

参考官方示例：packages/markitdown-sample-plugin
发布插件后添加 #markitdown-plugin 话题标签即可被社区发现。

八、安全注意事项

⚠️ MarkItDown 使用当前进程权限执行 I/O 操作，在处理不可信输入时需格外谨慎。

九、典型应用场景

场景 1：批量文档转 Markdown 供 LLM 处理

import os
from markitdown import MarkItDown

md = MarkItDown()
docs_dir = "./documents"
output_dir = "./markdown"

os.makedirs(output_dir, exist_ok=True)

for filename in os.listdir(docs_dir):
if filename.endswith((".pdf", ".docx", ".pptx", ".xlsx")):
        input_path = os.path.join(docs_dir, filename)
        output_path = os.path.join(output_dir, filename.rsplit(".", 1)[0] + ".md")

        result = md.convert(input_path)
with open(output_path, "w", encoding="utf-8") as f:
            f.write(result.text_content)
print(f"✅ 已转换：{filename}")

场景 2：结合 LLM 实现文档问答

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown()

# 1. 将文档转为 Markdown
result = md.convert("annual_report.pdf")
document_text = result.text_content

# 2. 使用 LLM 进行问答
question = "请总结这份报告的主要财务数据"
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个文档分析助手"},
        {"role": "user", "content": f"文档内容：\n\n{document_text}\n\n问题：{question}"}
    ]
)
print(response.choices[0].message.content)

场景 3：提取网页内容

from markitdown import MarkItDown

md = MarkItDown()

# 直接转换网页 URL
result = md.convert("https://docs.python.org/3/tutorial/")
print(result.text_content[:2000])  # 输出前 2000 字符

十、常见问题

Q：转换 PDF 后中文乱码？
A：确保安装了 [pdf] 依赖，对于扫描版 PDF 建议启用 OCR 插件或使用 Azure Document Intelligence。

Q：图片无法提取文字？
A：需配置 llm_client 参数或使用 markitdown-ocr 插件（需要 OpenAI API Key）。

Q：ZIP 文件如何处理？
A：MarkItDown 会自动解压并迭代转换 ZIP 内的每个文件，无需手动解压。

Q：音频转录需要什么条件？
A：安装 [audio-transcription] 依赖，并配置支持 Whisper 等语音识别的 LLM 客户端。

Q：如何提高转换质量？
A：对于结构复杂的文档，推荐使用 Azure Document Intelligence（-d 参数）获得最高精度。

十一、快速参考卡

# 安装
pip install 'markitdown[all]'

# 命令行转换
markitdown input.pdf -o output.md

# Python 最简用法
python -c "from markitdown import MarkItDown; print(MarkItDown().convert('file.pdf').text_content)"