markitdown

MarkItDown

概述

MarkItDown 是一个 Python 工具，可将各种文件格式转换为 Markdown 格式，专为大模型和文本分析工作流优化。它在生成简洁、节省 token 的 Markdown 输出的同时，会保留文档结构（标题、列表、表格、超链接）。

适用场景

在用户请求以下操作时使用此工具：

• 将文档转换为 Markdown 格式
• 从 PDF、Word、PowerPoint 或 Excel 文件中提取文本
• 对图像执行 OCR 以提取文本
• 将音频文件转录为文本
• 提取 YouTube 视频字幕
• 将 HTML、EPUB 或网页内容转换为 Markdown
• 将结构化数据（CSV、JSON、XML）转换为易读的 Markdown
• 批量转换多个文件或 ZIP 压缩包
• 为大模型分析或 RAG 系统准备文档

核心功能

1. 文档转换

将 Office 文档和 PDF 转换为 Markdown，同时保留文档结构。

支持的格式：

• PDF 文件（可选集成 Azure Document Intelligence）
• Word 文档（DOCX）
• PowerPoint 演示文稿（PPTX）
• Excel 电子表格（XLSX、XLS）

基本用法：

from markitdown import MarkItDown

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

命令行：

markitdown document.pdf -o output.md

有关文档专属功能的详细说明，请参阅 references/document_conversion.md。

2. 媒体处理

使用 OCR 从图像中提取文本，并将音频文件转录为文本。

支持的格式：

• 图像（JPEG、PNG、GIF 等），支持提取 EXIF 元数据
• 音频文件，支持语音转录（需要 speech_recognition）

图像 OCR：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("image.jpg")
print(result.text_content)  # Includes EXIF metadata and OCR text

音频转录：

result = md.convert("audio.wav")
print(result.text_content)  # Transcribed speech

有关高级媒体处理选项，请参阅 references/media_processing.md。

3. 网页内容提取

将网页内容和电子书转换为 Markdown。

支持的格式：

• HTML 文件和网页
• YouTube 视频字幕（通过 URL）
• EPUB 书籍
• RSS 订阅源

YouTube 字幕：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

有关网页内容提取的详情，请参阅 references/web_content.md。

4. 结构化数据处理

将结构化数据格式转换为易读的 Markdown 表格。

支持的格式：

• CSV 文件
• JSON 文件
• XML 文件

将 CSV 转换为 Markdown 表格：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.csv")
print(result.text_content)  # Formatted as Markdown table

有关特定格式的选项，请参阅 references/structured_data.md。

5. 高级集成

利用 AI 功能提升转换质量。

Azure Document Intelligence： 通过更出色的表格提取和版面分析，增强 PDF 处理效果：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<endpoint>", docintel_key="<key>")
result = md.convert("complex.pdf")

由大模型驱动的图像描述： 使用 GPT-4o 生成详细的图像描述：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("presentation.pptx")  # Images described with LLM

有关集成详情，请参阅 references/advanced_integrations.md。

6. 批量处理

一次处理多个文件或整个 ZIP 压缩包。

ZIP 文件处理：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("archive.zip")
print(result.text_content)  # All files converted and concatenated

批处理脚本： 使用提供的批处理脚本转换目录：

python scripts/batch_convert.py /path/to/documents /path/to/output

有关实现详情，请参阅 scripts/batch_convert.py。

安装

完整安装（所有功能）：

uv pip install 'markitdown[all]'

模块化安装（指定功能）：

uv pip install 'markitdown[pdf]'           # PDF support
uv pip install 'markitdown[docx]'          # Word support
uv pip install 'markitdown[pptx]'          # PowerPoint support
uv pip install 'markitdown[xlsx]'          # Excel support
uv pip install 'markitdown[audio]'         # Audio transcription
uv pip install 'markitdown[youtube]'       # YouTube transcripts

要求：

• Python 3.10 或更高版本

输出格式

MarkItDown 会生成简洁、节省 token、适合大模型使用的 Markdown：

• 保留标题、列表和表格
• 保留超链接和格式
• 在适用时包含元数据（EXIF、文档属性）
• 不会创建临时文件（采用流式处理）

常见工作流

为 RAG 准备文档：

from markitdown import MarkItDown

md = MarkItDown()

# Convert knowledge base documents
docs = ["manual.pdf", "guide.docx", "faq.html"]
markdown_content = []

for doc in docs:
    result = md.convert(doc)
    markdown_content.append(result.text_content)

# Now ready for embedding and indexing

文档分析工作流：

# Convert all PDFs in directory
for file in documents/*.pdf; do
    markitdown "$file" -o "markdown/$(basename "$file" .pdf).md"
done

插件系统

MarkItDown 支持可扩展插件，可用于自定义转换逻辑。出于安全考虑，插件默认处于禁用状态：

from markitdown import MarkItDown

# Enable plugins if needed
md = MarkItDown(enable_plugins=True)

资源

此技能包含各项功能的全面参考文档：

• references/document_conversion.md - PDF、DOCX、PPTX、XLSX 转换选项详解
• references/media_processing.md - 图片 OCR 和音频转录详情
• references/web_content.md - HTML、YouTube 和 EPUB 提取
• references/structured_data.md - CSV、JSON、XML 转换格式
• references/advanced_integrations.md - Azure Document Intelligence 和大模型集成
• scripts/batch_convert.py - 用于目录的批量处理工具