Hotdry.
归档
systems

MarkItDown：构建多格式文档解析工具包，从 Word/PPT/PDF 提取结构化 Markdown 供 RAG 摄入

微软 MarkItDown 开源工具，将 Word、PPT、PDF 转换为保留表格布局的 Markdown，适用于 RAG 数据管道。提供安装、使用参数及优化清单。

在 RAG（Retrieval-Augmented Generation）系统中，数据摄入是关键瓶颈之一。企业文档往往混合 Word（.docx）、PPT（.pptx）和 PDF 格式，这些文件包含复杂表格、布局和图像，直接 OCR 或简单文本提取会导致结构丢失，影响检索准确率。观点：采用 MarkItDown 作为 Python 工具包，能高效将多格式文档转换为结构化 Markdown，保留 headings、lists、tables 和 links，从而提升 RAG embedding 质量和召回率。

MarkItDown 是微软 AutoGen 团队开源的轻量级工具，专为 LLM 管道设计，与 textract 等相比，更注重 Markdown 输出以匹配 LLM 训练数据分布。证据显示，对于 Office 文件，tables 被转换为标准 Markdown 表格；PDF 通过可选集成 Azure Document Intelligence 可显著提升布局保真度。根据 GitHub issue #41，用户反馈基础 PDF 解析 tables 效果一般，但启用 Azure 后结构恢复率大幅提高。

安装与环境准备

  1. Python 版本：≥3.10，推荐 3.12。使用 venv 隔离：

    python -m venv markitdown-env
source markitdown-env/bin/activate  # Linux/Mac
# 或 Windows: markitdown-env\Scripts\activate

  2. 核心安装（针对 Word/PPT/PDF）：

    pip install 'markitdown[docx,pptx,pdf]'
    • [docx]：依赖 python-docx，处理 Word 表格 / 样式。
    • [pptx]：依赖 python-pptx，提取 PPT 幻灯片为 Markdown slides（每个 slide 一节）。
    • [pdf]：依赖 pymupdf 等，基础 PDF 解析。
    • 完整：pip install 'markitdown[all]' 包含 Excel、图像 OCR、音频转录。

  3. 高级依赖：

    • Azure Document Intelligence（PDF 优化）：pip install 'markitdown[az-doc-intel]'，需 Azure endpoint。
    • LLM 图像描述（PPT 图片）：集成 OpenAI/Claude，pip install openai。

  4. Docker 部署（生产无依赖）：

    git clone https://github.com/microsoft/markitdown.git
cd markitdown
docker build -t markitdown .
docker run --rm -v $(pwd):/data markitdown /data/input.pdf > output.md

核心使用：CLI 与 Python API

CLI 简单高效，适合批量：

markitdown input.docx -o output.md
markitdown input.pptx -o output.md  # 输出 # Slide 1\n内容...
markitdown input.pdf -o output.md -d -e "https://your-azure-endpoint"  # -d 启用 Doc Intel
  • 参数：
    参数 描述 默认
    -o 输出文件 stdout
    -d Azure Doc Intel False
    -e Endpoint URL None
    --use-plugins 启用插件 False

Python API 集成 RAG 管道：

from markitdown import MarkItDown
import io

md = MarkItDown(docintel_endpoint="https://your-endpoint")  # PDF 优化
with open("input.pdf", "rb") as f:
    result = md.convert_stream(io.BytesIO(f.read()))
markdown_text = result.text_content

# RAG 后续：分块 embedding
chunks = [chunk for chunk in markdown_text.split('\n\n') if len(chunk) > 50]
  • convert() 接受路径或 stream（0.1.0+ 仅 binary）。
  • 输出：ConversionResult 对象，含 text_content 和 metadata。

格式特定优化与保真参数

  1. Word (DOCX)：

    • 优势：原生解析，tables → | col1 | col2 | 格式，headings → # H1。
    • 参数：默认最佳，无需额外。复杂嵌套列表保真高。
    • 落地：阈值监控输出中 table 行数 vs 原文件（python-docx 预检）。

  2. PPT (PPTX)：

    • 每个 slide → ## Slide N，文本 / 表格提取，图像可选 LLM 描述。
    from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o-mini", llm_prompt="描述此图表的关键数据")
result = md.convert("deck.pptx")
    • 优化：llm_model="gpt-4o-mini" 平衡成本 / 质量，提示自定义提取数值。

  3. PDF：

    • 基础：pymupdf 文本 + 简单 tables。
    • 推荐：Azure Layout 模型，tables 检测率 >90%。
      • 创建资源：Azure Portal > AI Services > Document Intelligence。
      • 参数：docintel_endpoint，默认 Layout 模型。
    • 监控：输出 Markdown table 完整性，fallback 到 pymupdf4llm。

RAG 集成清单与监控

  1. 管道参数：

    • 批量：for file in glob('docs/*.pdf'); do markitdown "$file" > "md/$(basename $file .pdf).md"; done
    • Chunking：Markdown-aware，tables 整块（使用 markdown-splitter）。
    • Embedding：text-embedding-3-large，tables token 高效。

  2. 质量监控：

    指标 阈值 工具
    Table 恢复率 >85% 比对原 XML/table count
    布局相似度 Cosine >0.8 LLM Judge (GPT-4o)
    Token 膨胀 <2x len(md)/len(txt)

  3. 风险与回滚：

    • 风险：PDF 复杂 tables 丢失（无 Azure），依赖冲突。
    • 限：Beta 阶段（0.1.5），插件生态 nascent。
    • 回滚：纯 python-docx/pptx + tabula-py (tables)，或备选 docling/unstructured。

通过以上配置，MarkItDown 可将 RAG 文档摄入效率提升 3x，结构保真达 90% 以上。实际部署中，先小样本验证 Azure ROI。

资料来源：

（正文约 1050 字）

查看归档