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（按优先级排序） - 抽象基类：
DocumentConverteraccepts(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）
- 统一输出结构体：
DocumentConverterResultmarkdown: 标准 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、插件生态
