markitdown

MarkItDown

概述

MarkItDown 是一款 Python 工具，可将各种文件格式转换为 Markdown 格式，并针对大模型和文本分析工作流进行了优化。它会保留文档结构（标题、列表、表格、超链接），同时生成简洁且节省令牌的 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

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

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)

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

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

6. 批量处理

一次处理多个文件或整个 ZIP 存档。

ZIP 文件处理：

from markitdown import MarkItDown

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

批量转换：

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
for source in Path("documents").rglob("*.pdf"):
    result = md.convert(str(source))
    Path(f"output/{source.stem}.md").write_text(result.text_content, encoding="utf-8")

安装

完整安装（包含所有功能）：

pip install 'markitdown[all]'

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

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

要求：

• Python 3.10 或更高版本

输出格式

MarkItDown 会生成简洁且节省令牌、针对大模型处理进行优化的 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)

资源

• GitHub 上的 MarkItDown