备忘录：微软开源MarkItDown，万能文档转Markdown神器

MarkItDown（GitHub: microsoft/markitdown）是微软开源的Python 万能文档→Markdown 转换引擎，专为 LLM / RAG 预处理设计。核心逻辑：统一接口 + 插件式转换器 + 流式处理 + 结构化 Markdown 输出。

一、核心定位

• 目标：把 PDF / Word / PPT / Excel / 图片 / 音频等15+ 格式统一转成结构完整的 Markdown
• 设计思想：单一 API，万物转 MD
• 面向场景：LLM 输入、RAG 知识库、文档索引、内容挖掘

二、整体架构（四层）

1. 入口层（MarkItDown 主类）

• 统一对外接口：convert()/convert_stream()
• 自动格式识别（文件头 + 后缀）
• 转换器路由与优先级调度
• 元数据提取、附件管理、警告收集

2. 转换器注册中心（Plugin Registry）

• 全局注册表：_converters（按优先级排序）
• 抽象基类：DocumentConverter
  • accepts(stream, info)：判断是否支持该文件
  • convert(stream, info)：执行转换
• 内置转换器：
  • PDFConverter（pdfminer.six）
  • DocxConverter（mammoth）
  • XlsxConverter（openpyxl）
  • ImageConverter（PIL + Tesseract OCR）
  • AudioConverter（SpeechRecognition）
  • HtmlConverter,EPUBConverter,ZipConverter等

3. 格式解析层（各 Converter 实现）

通用流程（以 PDF 为例）：

plaintext

1. 文本提取 → 2. 结构分析（标题/列表/表格）→ 3. 表格重建 → 4. MD 格式化

Word 增强：

• 样式映射（Heading1 →#）
• 保留复杂列表、嵌套、表格
• 图片提取与内联

图像 OCR：

• 自动检测含文字图片
• Tesseract 多语言支持
• 输出：> OCR: 提取的文字

4. 输出层（MarkdownBuilder）

• 统一输出结构体：DocumentConverterResult
  • markdown: 标准 MD 文本
  • metadata: 标题 / 作者 / 时间
  • attachments: 图片 / 附件列表
  • warnings: 转换警告
• 结构保真：标题层级、列表、表格、链接、代码块

三、核心代码逻辑（伪代码）

python

运行

# 1. 初始化 from markitdown import MarkItDown md = MarkItDown() # 自动加载所有转换器 # 2. 转换主流程（convert 核心） def convert(file_path): # a. 打开二进制流 with open(file_path, "rb") as stream: # b. 识别文件信息（后缀、MIME、头） info = detect_stream_info(stream, file_path) # c. 匹配转换器（按优先级轮询 accepts） converter = None for conv in self._converters: if conv.accepts(stream, info): converter = conv break # d. 执行转换 result = converter.convert(stream, info) # e. 后处理（优化 MD、清理、元数据） result.markdown = post_process(result.markdown) return result # 3. 转换器示例（PDF） class PDFConverter(DocumentConverter): def accepts(self, stream, info): return info.extension == ".pdf" def convert(self, stream, info): # 1. 提取文本与布局 text, layout = extract_pdf_text_and_layout(stream) # 2. 解析结构（标题、段落、表格） structure = parse_structure(text, layout) # 3. 生成 Markdown md = build_markdown(structure) # 4. 提取元数据 meta = extract_pdf_metadata(stream) # 5. 返回结果 return DocumentConverterResult( markdown=md, metadata=meta )

四、关键技术特性

• 无临时文件：全程流式二进制处理
• 优先级调度：精准转换器优先（如 PDF 专用 > 通用文本）
• 插件化：轻松自定义转换器
• LLM 增强：可接入 GPT-4o 做图像理解、复杂表格修复
• 批量 / 递归：支持目录批量转换

五、典型用法

python

运行

# 基础 md.convert("report.pdf") md.convert("slide.pptx") md.convert("photo.png") # OCR md.convert("speech.mp3") # 语音转文字 # LLM 增强（图像理解） from openai import OpenAI md = MarkItDown(mlm_client=OpenAI()) md.convert("diagram.jpg") # 输出图片描述+OCR

六、与传统工具对比

• pandoc：通用转换，结构易丢，配置复杂
• textract：纯文本提取，无结构
• MarkItDown：结构保真、LLM 优化、单一 API、插件生态