MarkItDown解析

1. 概述

MarkItDown 是微软开源的一个轻量级 Python 工具，用于将各种文件格式转换为 Markdown。它专为 LLM（大语言模型）和文本分析管道设计，与 textract 类似，但更专注于保留文档结构（标题、列表、表格、链接等）。

核心价值主张：

• 输出 Markdown 格式，LLM 原生理解
• 保留文档结构，便于下游处理
• Token 效率高

---

2. MarkItDown架构

d:/daku/markitdown-main/
├── packages/
│   ├── markitdown/           # 核心包
│   ├── markitdown-mcp/       # MCP 服务器集成
│   ├── markitdown-ocr/       # OCR 插件（LLM Vision）
│   └── markitdown-sample-plugin/  # 插件开发示例
├── Dockerfile
└── README.md

---

3. MarkItDown设计

3.1 MarkItDown核心类结构

┌─────────────────────────────────────┐
│         MarkItDown (主入口)          │
│  - 管理转换器注册表                    │
│  - 协调转换流程                       │
│  - 处理多种输入源                      │
└─────────────────────────────────────┘
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
┌────────┐ ┌────────┐ ┌────────┐
│内置转换器│ │插件转换器│ │Azure文档 │
│(20+种) │ │(动态加载)│ │智能转换器 │
└────────┘ └────────┘ └────────┘
    │
    ▼
┌─────────────────────────────────────┐
│    DocumentConverter (抽象基类)      │
│  - accepts()  # 判断是否可处理         │
│  - convert()  # 执行转换              │
└─────────────────────────────────────┘
              │
    ┌─────────┼─────────┬─────────┐
    ▼         ▼         ▼         ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│PDF    │ │DOCX   │ │XLSX   │ │PPTX   │
│Converter│ │Converter│ │Converter│ │Converter│
└───────┘ └───────┘ └───────┘ └───────┘

3.2 MarkItDown支持的文件格式

类别	格式	依赖
文档	PDF	pdfminer.six, pdfplumber
Office	DOCX, PPTX, XLSX	python-pptx, mammoth, pandas
网页	HTML, RSS, Wikipedia	beautifulsoup4
媒体	图片(OCR), 音频(转录)	SpeechRecognition, pydub
数据	CSV, JSON, XML, ZIP	内置
其他	YouTube, EPub, Outlook	youtube-transcript-api

---

4. MarkItDown核心代码解析

4.1 主类 MarkItDown

class MarkItDown:
    def __init__(self, *, enable_builtins=True, enable_plugins=False, **kwargs):
        # 支持 LLM 客户端配置（用于图片描述）
        self._llm_client = kwargs.get("llm_client")
        self._llm_model = kwargs.get("llm_model")
        
        # 使用 Magika 进行文件类型检测
        self._magika = magika.Magika()
        
        # 转换器注册表（带优先级）
        self._converters: List[ConverterRegistration] = []

4.2 转换器优先级系统

PRIORITY_SPECIFIC_FILE_FORMAT = 0.0   # 特定格式（如 .pdf, .docx）
PRIORITY_GENERIC_FILE_FORMAT = 10.0   # 通用格式（如 text/*）

优先级规则：

• 数值越小，优先级越高
• 相同优先级时，后注册的优先
• 插件可以通过设置优先级来覆盖内置转换器

4.3 MarkItDown转换流程

def convert(self, source):
    # 1. 识别输入类型（本地文件/URL/流/Response）
    # 2. 获取 StreamInfo 猜测列表
    # 3. 按优先级排序转换器
    # 4. 逐个尝试转换器
    # 5. 返回第一个成功的结果

4.4 文件类型检测（Magika 集成）

def _get_stream_info_guesses(self, file_stream, base_guess):
    # 1. 基于扩展名猜测 MIME 类型
    # 2. 使用 Magika 进行内容分析
    # 3. 使用 charset-normalizer 检测编码
    # 4. 返回兼容的猜测列表

---

5. 转换器实现示例

5.1 HTML 转换器

class HtmlConverter(DocumentConverter):
    def accepts(self, file_stream, stream_info, **kwargs):
        # 基于 MIME 类型或扩展名判断
        mimetype = (stream_info.mimetype or "").lower()
        extension = (stream_info.extension or "").lower()
        return extension in [".html", ".htm"] or \
               mimetype.startswith("text/html")
    
    def convert(self, file_stream, stream_info, **kwargs):
        # 1. 使用 BeautifulSoup 解析
        # 2. 移除 script/style 标签
        # 3. 使用自定义 markdownify 转换
        # 4. 处理递归深度超限的回退

5.2 PDF 转换器（最复杂）

class PdfConverter(DocumentConverter):
    def convert(self, file_stream, stream_info, **kwargs):
        # 1. 使用 pdfplumber 提取文本和表格
        # 2. 将表格转换为 Markdown 格式
        # 3. 处理 MasterFormat 部分编号
        # 4. 合并文本和表格输出

---

6. 插件系统

6.1 插件注册机制

使用 Python 的 entry_points 系统：

# pyproject.toml
[project.entry-points."markitdown.plugin"]
ocr = "markitdown_ocr"

6.2 插件接口

__plugin_interface_version__ = 1

def register_converters(markitdown: MarkItDown, **kwargs):
    markitdown.register_converter(MyCustomConverter())

6.3 OCR 插件详解

功能：

• 使用 LLM Vision 提取 PDF/DOCX/PPTX/XLSX 中嵌入图片的文字
• 支持扫描 PDF 的全页 OCR
• 保持文档结构和阅读顺序

工作流程：

1. 插件以优先级 -1.0 注册（高于内置转换器的 0.0）
2. 接受文件并提取嵌入图片
3. 将图片发送到 LLM 进行 OCR
4. 将识别文本内联插入到文档中

---

7. MCP 服务器集成

MCP (Model Context Protocol) 是 Anthropic 推出的开放协议，用于标准化 AI 应用与外部工具的集成。

# markitdown-mcp 提供：
# - STDIO 传输（默认）
# - Streamable HTTP 传输
# - SSE 传输

# 暴露的工具：
convert_to_markdown(uri)  # 支持 http:, https:, file:, data: URI

Claude Desktop 配置示例：

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    }
  }
}

---

8. 测试体系

tests/
├── _test_vectors.py          # 测试向量定义
├── test_cli_vectors.py       # CLI 测试
├── test_module_vectors.py    # 模块 API 测试
├── test_pdf_*.py             # PDF 专项测试
└── test_files/               # 测试文件

测试向量模式：

@dataclass
class FileTestVector:
    filename: str
    mimetype: str | None
    charset: str | None
    url: str | None
    must_include: List[str]      # 必须包含的内容
    must_not_include: List[str]  # 必须不包含的内容

---

9. 依赖管理策略

采用可选依赖分组（extras）：

[project.optional-dependencies]
all = ["..."]                    # 全部依赖
pdf = ["pdfminer.six", "pdfplumber"]
docx = ["mammoth", "lxml"]
pptx = ["python-pptx"]
xlsx = ["pandas", "openpyxl"]
audio-transcription = ["pydub", "SpeechRecognition"]
youtube-transcription = ["youtube-transcript-api"]
az-doc-intel = ["azure-ai-documentintelligence"]

安装方式：

pip install 'markitdown[all]'      # 完整功能
pip install 'markitdown[pdf,docx]' # 仅 PDF 和 Word

---

10. MarkItDown关键技术

技术	用途
Magika	Google 的文件类型检测库，基于深度学习
charset-normalizer	字符编码自动检测
BeautifulSoup + markdownify	HTML → Markdown 转换
pdfplumber	PDF 文本和表格提取
python-pptx/mammoth	Office 文档处理
Entry Points	插件发现和加载机制

---

11. 使用场景

1. RAG 系统：将企业文档转换为 Markdown 供 LLM 处理
2. 文档分析：批量提取文档内容进行分析
3. 内容迁移：将旧格式文档迁移到 Markdown 系统
4. AI 工作流：作为 Claude Desktop 等工具的文档处理能力