前言在大模型应用开发中文档解析是一个绕不开的问题。无论是构建 RAG 知识库、企业文档问答、智能搜索还是把 PDF、Word、PPT、Excel、网页、图片、音频等资料交给 LLM 分析第一步通常都是将各种复杂格式转换为模型更容易理解的文本。microsoft/markitdown正是为这个场景设计的开源工具。MarkItDown 是微软开源的轻量级 Python 工具主要作用是把多种文件格式转换为 Markdown。与普通文档转换器不同它的目标不是生成“排版完全一致”的可视化文档而是尽量保留文档结构和关键内容让输出结果更适合 LLM、RAG 和文本分析管线使用。项目官方定位可以概括为将各种文件和 Office 文档转换为 Markdown用于 LLM 和文本分析流程。发布时间(v0.1.6)2026-05-26一、项目背景为什么需要 MarkItDown在 LLM 应用中常见资料来源包括PDF 报告 Word 文档 PPT 课件 Excel 表格 HTML 网页 CSV / JSON / XML 数据 图片截图 音频录音 压缩包 YouTube 视频链接 EPub 电子书这些格式对人类阅读友好但对 LLM 不一定友好。如果直接把原始 PDF、PPT、Excel 丢给大模型可能会遇到以下问题表格结构丢失标题层级混乱页眉页脚干扰图片内容无法描述文档中的链接、列表、表格难以保留多模态文件需要额外 OCR 或转录不同格式需要不同解析库工程维护成本高。Markdown 的优势在于接近纯文本 结构清晰 对 LLM 友好 token 利用率高 可以表达标题、列表、表格、链接、代码块等结构因此MarkItDown 的核心价值是把复杂文档转成结构化 Markdown让后续的 LLM 处理更稳定。二、项目框架设计从仓库结构来看MarkItDown 采用 monorepo 风格核心代码位于packages/目录下。简化后的项目结构可以理解为markitdown/ ├── packages/ │ ├── markitdown/ # 核心 Python 包 │ │ ├── src/markitdown/ │ │ │ ├── __init__.py │ │ │ ├── _markitdown.py # 核心转换入口 │ │ │ ├── converters/ # 各类格式转换器 │ │ │ └── ... │ │ ├── tests/ # 测试用例 │ │ └── pyproject.toml │ │ │ ├── markitdown-mcp/ # MCP Server 支持 │ ├── markitdown-sample-plugin/ # 插件开发示例 │ └── markitdown-ocr/ # OCR 插件 │ ├── Dockerfile # Docker 构建文件 ├── README.md # 项目说明 ├── LICENSE # MIT License ├── SECURITY.md # 安全说明 └── .github/ # CI / Issue / PR 等配置整体设计可以拆成四层输入层本地文件、流、URL、管道输入 ↓ 识别层文件类型识别、MIME 判断、扩展名匹配 ↓ 转换层PDF / DOCX / PPTX / XLSX / HTML / 图片 / 音频等 Converter ↓ 输出层Markdown 文本、text_content、CLI 输出、Python API 返回这种结构的优势是不同格式各自有独立 Converter核心入口统一调度用户只需要调用一个convert()方法即可。三、支持格式根据官方 READMEMarkItDown 当前支持多种常见格式PDF PowerPoint Word Excel 图片EXIF 元数据和 OCR 音频EXIF 元数据和语音转录 HTML CSV / JSON / XML 等文本格式 ZIP遍历压缩包内容 YouTube URL EPub 更多格式持续扩展中这使它非常适合做企业知识库的预处理工具。例如一个企业内部知识库可能同时包含产品说明书 PDF 会议纪要 Word 销售数据 Excel 培训课件 PPT 网页归档 HTML 客服录音 MP3 合同扫描件图片MarkItDown 可以将这些异构文件统一转换为 Markdown后续再进入 embedding、向量库、检索增强生成等环节。四、关键功能解析与技术破局1. 多格式统一转换普通项目通常会为每种格式单独写解析逻辑PDF 用 pdfminer 或 PyMuPDF Word 用 python-docx 或 mammoth PPT 用 python-pptx Excel 用 openpyxl HTML 用 BeautifulSoup 图片用 OCR 音频用转录模型这会带来很高的集成成本。MarkItDown 的价值在于提供统一接口from markitdown import MarkItDown md MarkItDown() result md.convert(report.pdf) print(result.text_content)无论输入是 PDF、DOCX、PPTX、XLSX 还是 HTML开发者都可以使用近似一致的方式处理。2. 面向 LLM 的 Markdown 输出MarkItDown 的设计重点不是“格式还原”而是“语义结构保留”。它会尽量把文档中的重要结构转换为 Markdown例如标题 列表 表格 链接 段落 图片描述 页面内容 文本块这比直接提取纯文本更有价值。例如 PDF 中的章节标题如果能转为## 3. 系统架构设计那么 LLM 在摘要、问答、检索时更容易理解上下文结构。3. Office 文档解析MarkItDown 支持 Word、PowerPoint、Excel 等 Office 文档。这对企业用户非常重要因为实际知识资产大量存在于 Office 文件中合同 DOCX 项目计划 PPTX 财务报表 XLSX 技术方案 DOCX 产品培训 PPTX通过 MarkItDown可以将这些文件批量转换成 Markdown进一步送入知识库系统。4. PDF 解析与表格支持PDF 是最常见、也是最难解析的格式之一。MarkItDown 的 Release 记录中可以看到它持续修复和增强 PDF 转换能力例如 PDF 表格提取、列表解析、内存增长问题、扫描件 OCR 等。这说明项目的重点并不是简单读取文本而是在不断提高复杂 PDF 的结构化输出质量。5. 图片 OCR 与 LLM 视觉描述MarkItDown 支持图片处理包括 EXIF 元数据和 OCR。它还支持通过 LLM 为图片生成描述尤其适用于 PPTX 和图片文件。示例from markitdown import MarkItDown from openai import OpenAI client OpenAI() md MarkItDown( llm_clientclient, llm_modelgpt-4o, llm_prompt请描述图片中的关键信息 ) result md.convert(example.jpg) print(result.text_content)这类能力非常适合处理截图 流程图 PPT 插图 扫描图片 产品照片 图表图片6. 音频转录与 YouTube 支持MarkItDown 还支持音频文件元数据和语音转录并支持 YouTube URL 转换。这意味着它不仅能处理文档还能处理音视频内容中的文本信息。适用场景包括会议录音整理 课程音频转笔记 访谈内容提取 YouTube 视频内容摘要 播客内容知识库化对于构建多模态知识库这一点非常实用。7. ZIP 文件递归处理MarkItDown 支持 ZIP 文件并会遍历压缩包内容。这在实际场景中很常见例如用户上传一个压缩包里面包含多个 PDF 多个 Word 文档 Excel 表 图片 说明文件MarkItDown 可以把压缩包内的内容统一处理减少人工解压和逐个转换的步骤。8. 插件机制MarkItDown 支持第三方插件但默认禁用插件。用户可以通过命令查看已安装插件markitdown --list-plugins启用插件markitdown --use-plugins path-to-file.pdf官方还提供了示例插件packages/markitdown-sample-plugin以及 OCR 插件pip install markitdown-ocr插件机制让 MarkItDown 能够扩展到更多格式、更多 OCR 策略和更定制化的转换逻辑。9. Azure Document Intelligence 集成如果用户需要更高质量的 PDF 或文档布局解析可以接入 Azure Document Intelligence。CLI 示例markitdown path-to-file.pdf -o document.md -d -e document_intelligence_endpointPython API 示例from markitdown import MarkItDown md MarkItDown( docintel_endpointdocument_intelligence_endpoint ) result md.convert(test.pdf) print(result.text_content)适合场景扫描 PDF 复杂表格 多栏文档 版式复杂的企业报告 合同和票据10. Azure Content Understanding 集成MarkItDown 还支持 Azure Content Understanding。它相比内置转换器更适合多模态、结构化字段抽取场景。适合场景包括音频和视频文件处理 复杂文档结构化解析 票据、合同、发票字段抽取 扫描 PDF OCR 多模态统一分析CLI 示例markitdown path-to-file.pdf \ --use-cu \ --cu-endpoint content_understanding_endpointPython 示例from markitdown import MarkItDown md MarkItDown( cu_endpointcontent_understanding_endpoint ) result md.convert(report.pdf) print(result.markdown)如果使用自定义 analyzer还可以输出 YAML front matter用于结构化字段抽取。五、技术破局点总结MarkItDown 的技术突破不在于“单一格式转换能力最强”而在于它对 LLM 应用场景做了统一抽象。它解决的是一个工程问题多格式资料 ↓ 统一转 Markdown ↓ 进入 LLM / RAG / 搜索 / 摘要 / 问答管线这类工具在 RAG 项目中非常关键因为真正的企业数据往往不是干净的.txt文件而是分散在各种 PDF、PPT、Word、Excel、网页和音视频中。MarkItDown 的价值可以总结为降低文档预处理成本 统一多格式输入 保留文档结构 输出 LLM 友好的 Markdown 支持插件和云端增强能力六、使用教程1. 环境要求MarkItDown 要求Python 3.10 建议使用虚拟环境创建虚拟环境python -m venv .venv source .venv/bin/activateWindowspython -m venv .venv .venv\Scripts\activate如果使用 Condaconda create -n markitdown python3.12 conda activate markitdown2. 安装 MarkItDown安装全部可选依赖pip install markitdown[all]如果只需要部分格式可以按需安装pip install markitdown[pdf,docx,pptx]常见可选依赖包括[all]安装全部可选依赖 [pdf]PDF 支持 [docx]Word 支持 [pptx]PowerPoint 支持 [xlsx]Excel 支持 [xls]旧版 Excel 支持 [outlook]Outlook 消息支持 [audio-transcription]音频转录支持 [youtube-transcription]YouTube 转录支持 [az-doc-intel]Azure Document Intelligence 支持 [az-content-understanding]Azure Content Understanding 支持3. 从源码安装git clone https://github.com/microsoft/markitdown.git cd markitdown pip install -e packages/markitdown[all]4. 命令行使用把 PDF 转成 Markdownmarkitdown path-to-file.pdf document.md指定输出文件markitdown path-to-file.pdf -o document.md通过管道输入cat path-to-file.pdf | markitdown转换 Wordmarkitdown report.docx -o report.md转换 PowerPointmarkitdown slides.pptx -o slides.md转换 Excelmarkitdown data.xlsx -o data.md转换 HTMLmarkitdown page.html -o page.md5. Python API 基础用法from markitdown import MarkItDown md MarkItDown(enable_pluginsFalse) result md.convert(test.xlsx) print(result.text_content)也可以处理 PDFfrom markitdown import MarkItDown md MarkItDown() result md.convert(report.pdf) with open(report.md, w, encodingutf-8) as f: f.write(result.text_content)6. 使用 LLM 进行图片描述from markitdown import MarkItDown from openai import OpenAI client OpenAI() md MarkItDown( llm_clientclient, llm_modelgpt-4o, llm_prompt请提取图片中的文字、图表和关键信息。 ) result md.convert(example.jpg) print(result.text_content)适合处理截图、流程图、PPT 图片、产品图等。7. 使用 Azure Document Intelligencefrom markitdown import MarkItDown md MarkItDown( docintel_endpointdocument_intelligence_endpoint ) result md.convert(test.pdf) print(result.text_content)CLImarkitdown path-to-file.pdf \ -o document.md \ -d \ -e document_intelligence_endpoint8. 使用 Azure Content Understandingfrom markitdown import MarkItDown md MarkItDown( cu_endpointcontent_understanding_endpoint ) result md.convert(report.pdf) print(result.markdown)如果希望只让 PDF 使用 Content Understandingfrom markitdown import MarkItDown from markitdown.converters import ContentUnderstandingFileType md MarkItDown( cu_endpointcontent_understanding_endpoint, cu_file_types[ContentUnderstandingFileType.PDF] )9. 插件使用查看已安装插件markitdown --list-plugins启用插件markitdown --use-plugins path-to-file.pdf安装 OCR 插件pip install markitdown-ocr pip install openaiPython 使用插件from markitdown import MarkItDown from openai import OpenAI md MarkItDown( enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o ) result md.convert(document_with_images.pdf) print(result.text_content)10. Docker 使用构建镜像docker build -t markitdown:latest .运行转换docker run --rm -i markitdown:latest ~/your-file.pdf output.md11. 测试与开发进入 MarkItDown 包目录cd packages/markitdown安装测试工具pip install hatch运行测试hatch shell hatch test提交 PR 前运行pre-commit run --all-files七、安全注意事项MarkItDown 会以当前进程权限执行 I/O 操作。这意味着如果你把不可信输入直接传给 MarkItDown它可能访问当前进程有权限访问的本地路径、URL 或网络资源。在服务端或托管环境中建议限制上传文件类型 限制文件大小 限制可访问路径 禁止任意 URL 访问 阻断内网地址、metadata service、loopback、link-local 地址 使用最窄的 convert_* 函数 对用户输入做白名单校验 在沙箱或容器中执行转换这点非常重要尤其是在构建在线文档转换服务时。八、适合哪些场景MarkItDown 适合以下场景1. RAG 知识库预处理将 PDF、Word、PPT、Excel、HTML 批量转成 Markdown再进行切分、embedding 和入库。2. 企业文档问答把内部文档统一转换为 LLM 友好的格式用于问答、摘要、检索。3. 多格式资料归档把不同格式资料转换为 Markdown便于 Git 管理、版本控制和搜索。4. 课程和会议资料整理处理 PPT、PDF、音频和 YouTube 视频生成学习笔记或摘要。5. Agent 工具链作为 AI Agent 的文件读取工具让 Agent 能统一理解多种文件格式。6. 数据分析前处理把 Excel、CSV、JSON、XML 等转为 Markdown 说明方便 LLM 做分析解释。九、项目优势与不足优势第一多格式支持丰富。PDF、Office、图片、音频、HTML、压缩包、YouTube、EPub 等都可处理。第二输出格式对 LLM 友好。Markdown 能保留结构同时比 HTML、PDF 等格式更轻量。第三Python API 和 CLI 都很简单。既适合脚本自动化也适合命令行快速转换。第四可扩展能力强。支持插件机制也支持 Azure Document Intelligence 和 Azure Content Understanding。第五微软维护社区活跃度高。Star 数、Issue、PR 数都很高说明项目关注度和生态潜力较大。不足第一不适合高保真排版转换。如果你的目标是把 PDF 完美转换成排版一致的 Word 或 HTMLMarkItDown 不是最佳选择。第二复杂 PDF 仍可能解析不完美。多栏、扫描件、复杂表格、嵌套图片等仍需要更强 OCR 或 Azure 服务增强。第三部分格式依赖可选包。如果没有安装[all]或对应 extras某些格式可能无法转换。第四云端增强能力可能产生费用。Azure Document Intelligence 和 Azure Content Understanding 属于云服务调用使用时需要考虑费用和数据合规。第五服务端使用需要注意安全边界。对不可信文件和 URL 必须严格限制。十、总结microsoft/markitdown是一个非常适合 LLM 时代的文档预处理工具。它的核心价值不是做传统文档排版转换而是解决 AI 应用中的关键前置问题如何把各种复杂文件统一变成 LLM 更容易理解的 Markdown它把 PDF、Word、PPT、Excel、图片、音频、HTML、ZIP、YouTube、EPub 等格式统一抽象为 Markdown 输出让开发者可以更高效地构建RAG 系统 知识库问答 企业文档搜索 文档摘要工具 AI Agent 文件读取工具 多模态资料分析流程对于正在做大模型应用、知识库、文档智能、企业搜索或 AI Agent 的开发者来说MarkItDown 是一个非常值得关注和实践的开源项目。互动话题你在做 RAG 或知识库项目时最头疼的文档类型是哪一种PDFWordPowerPointExcel扫描图片音频/视频网页 HTML压缩包混合资料。欢迎在评论区分享你的经验和解决方案。
GitHub 开源项目解析：microsoft/markitdown —— 面向 LLM 的多格式文档转 Markdown 工具
发布时间：2026/6/4 19:35:16
前言在大模型应用开发中文档解析是一个绕不开的问题。无论是构建 RAG 知识库、企业文档问答、智能搜索还是把 PDF、Word、PPT、Excel、网页、图片、音频等资料交给 LLM 分析第一步通常都是将各种复杂格式转换为模型更容易理解的文本。microsoft/markitdown正是为这个场景设计的开源工具。MarkItDown 是微软开源的轻量级 Python 工具主要作用是把多种文件格式转换为 Markdown。与普通文档转换器不同它的目标不是生成“排版完全一致”的可视化文档而是尽量保留文档结构和关键内容让输出结果更适合 LLM、RAG 和文本分析管线使用。项目官方定位可以概括为将各种文件和 Office 文档转换为 Markdown用于 LLM 和文本分析流程。发布时间(v0.1.6)2026-05-26一、项目背景为什么需要 MarkItDown在 LLM 应用中常见资料来源包括PDF 报告 Word 文档 PPT 课件 Excel 表格 HTML 网页 CSV / JSON / XML 数据 图片截图 音频录音 压缩包 YouTube 视频链接 EPub 电子书这些格式对人类阅读友好但对 LLM 不一定友好。如果直接把原始 PDF、PPT、Excel 丢给大模型可能会遇到以下问题表格结构丢失标题层级混乱页眉页脚干扰图片内容无法描述文档中的链接、列表、表格难以保留多模态文件需要额外 OCR 或转录不同格式需要不同解析库工程维护成本高。Markdown 的优势在于接近纯文本 结构清晰 对 LLM 友好 token 利用率高 可以表达标题、列表、表格、链接、代码块等结构因此MarkItDown 的核心价值是把复杂文档转成结构化 Markdown让后续的 LLM 处理更稳定。二、项目框架设计从仓库结构来看MarkItDown 采用 monorepo 风格核心代码位于packages/目录下。简化后的项目结构可以理解为markitdown/ ├── packages/ │ ├── markitdown/ # 核心 Python 包 │ │ ├── src/markitdown/ │ │ │ ├── __init__.py │ │ │ ├── _markitdown.py # 核心转换入口 │ │ │ ├── converters/ # 各类格式转换器 │ │ │ └── ... │ │ ├── tests/ # 测试用例 │ │ └── pyproject.toml │ │ │ ├── markitdown-mcp/ # MCP Server 支持 │ ├── markitdown-sample-plugin/ # 插件开发示例 │ └── markitdown-ocr/ # OCR 插件 │ ├── Dockerfile # Docker 构建文件 ├── README.md # 项目说明 ├── LICENSE # MIT License ├── SECURITY.md # 安全说明 └── .github/ # CI / Issue / PR 等配置整体设计可以拆成四层输入层本地文件、流、URL、管道输入 ↓ 识别层文件类型识别、MIME 判断、扩展名匹配 ↓ 转换层PDF / DOCX / PPTX / XLSX / HTML / 图片 / 音频等 Converter ↓ 输出层Markdown 文本、text_content、CLI 输出、Python API 返回这种结构的优势是不同格式各自有独立 Converter核心入口统一调度用户只需要调用一个convert()方法即可。三、支持格式根据官方 READMEMarkItDown 当前支持多种常见格式PDF PowerPoint Word Excel 图片EXIF 元数据和 OCR 音频EXIF 元数据和语音转录 HTML CSV / JSON / XML 等文本格式 ZIP遍历压缩包内容 YouTube URL EPub 更多格式持续扩展中这使它非常适合做企业知识库的预处理工具。例如一个企业内部知识库可能同时包含产品说明书 PDF 会议纪要 Word 销售数据 Excel 培训课件 PPT 网页归档 HTML 客服录音 MP3 合同扫描件图片MarkItDown 可以将这些异构文件统一转换为 Markdown后续再进入 embedding、向量库、检索增强生成等环节。四、关键功能解析与技术破局1. 多格式统一转换普通项目通常会为每种格式单独写解析逻辑PDF 用 pdfminer 或 PyMuPDF Word 用 python-docx 或 mammoth PPT 用 python-pptx Excel 用 openpyxl HTML 用 BeautifulSoup 图片用 OCR 音频用转录模型这会带来很高的集成成本。MarkItDown 的价值在于提供统一接口from markitdown import MarkItDown md MarkItDown() result md.convert(report.pdf) print(result.text_content)无论输入是 PDF、DOCX、PPTX、XLSX 还是 HTML开发者都可以使用近似一致的方式处理。2. 面向 LLM 的 Markdown 输出MarkItDown 的设计重点不是“格式还原”而是“语义结构保留”。它会尽量把文档中的重要结构转换为 Markdown例如标题 列表 表格 链接 段落 图片描述 页面内容 文本块这比直接提取纯文本更有价值。例如 PDF 中的章节标题如果能转为## 3. 系统架构设计那么 LLM 在摘要、问答、检索时更容易理解上下文结构。3. Office 文档解析MarkItDown 支持 Word、PowerPoint、Excel 等 Office 文档。这对企业用户非常重要因为实际知识资产大量存在于 Office 文件中合同 DOCX 项目计划 PPTX 财务报表 XLSX 技术方案 DOCX 产品培训 PPTX通过 MarkItDown可以将这些文件批量转换成 Markdown进一步送入知识库系统。4. PDF 解析与表格支持PDF 是最常见、也是最难解析的格式之一。MarkItDown 的 Release 记录中可以看到它持续修复和增强 PDF 转换能力例如 PDF 表格提取、列表解析、内存增长问题、扫描件 OCR 等。这说明项目的重点并不是简单读取文本而是在不断提高复杂 PDF 的结构化输出质量。5. 图片 OCR 与 LLM 视觉描述MarkItDown 支持图片处理包括 EXIF 元数据和 OCR。它还支持通过 LLM 为图片生成描述尤其适用于 PPTX 和图片文件。示例from markitdown import MarkItDown from openai import OpenAI client OpenAI() md MarkItDown( llm_clientclient, llm_modelgpt-4o, llm_prompt请描述图片中的关键信息 ) result md.convert(example.jpg) print(result.text_content)这类能力非常适合处理截图 流程图 PPT 插图 扫描图片 产品照片 图表图片6. 音频转录与 YouTube 支持MarkItDown 还支持音频文件元数据和语音转录并支持 YouTube URL 转换。这意味着它不仅能处理文档还能处理音视频内容中的文本信息。适用场景包括会议录音整理 课程音频转笔记 访谈内容提取 YouTube 视频内容摘要 播客内容知识库化对于构建多模态知识库这一点非常实用。7. ZIP 文件递归处理MarkItDown 支持 ZIP 文件并会遍历压缩包内容。这在实际场景中很常见例如用户上传一个压缩包里面包含多个 PDF 多个 Word 文档 Excel 表 图片 说明文件MarkItDown 可以把压缩包内的内容统一处理减少人工解压和逐个转换的步骤。8. 插件机制MarkItDown 支持第三方插件但默认禁用插件。用户可以通过命令查看已安装插件markitdown --list-plugins启用插件markitdown --use-plugins path-to-file.pdf官方还提供了示例插件packages/markitdown-sample-plugin以及 OCR 插件pip install markitdown-ocr插件机制让 MarkItDown 能够扩展到更多格式、更多 OCR 策略和更定制化的转换逻辑。9. Azure Document Intelligence 集成如果用户需要更高质量的 PDF 或文档布局解析可以接入 Azure Document Intelligence。CLI 示例markitdown path-to-file.pdf -o document.md -d -e document_intelligence_endpointPython API 示例from markitdown import MarkItDown md MarkItDown( docintel_endpointdocument_intelligence_endpoint ) result md.convert(test.pdf) print(result.text_content)适合场景扫描 PDF 复杂表格 多栏文档 版式复杂的企业报告 合同和票据10. Azure Content Understanding 集成MarkItDown 还支持 Azure Content Understanding。它相比内置转换器更适合多模态、结构化字段抽取场景。适合场景包括音频和视频文件处理 复杂文档结构化解析 票据、合同、发票字段抽取 扫描 PDF OCR 多模态统一分析CLI 示例markitdown path-to-file.pdf \ --use-cu \ --cu-endpoint content_understanding_endpointPython 示例from markitdown import MarkItDown md MarkItDown( cu_endpointcontent_understanding_endpoint ) result md.convert(report.pdf) print(result.markdown)如果使用自定义 analyzer还可以输出 YAML front matter用于结构化字段抽取。五、技术破局点总结MarkItDown 的技术突破不在于“单一格式转换能力最强”而在于它对 LLM 应用场景做了统一抽象。它解决的是一个工程问题多格式资料 ↓ 统一转 Markdown ↓ 进入 LLM / RAG / 搜索 / 摘要 / 问答管线这类工具在 RAG 项目中非常关键因为真正的企业数据往往不是干净的.txt文件而是分散在各种 PDF、PPT、Word、Excel、网页和音视频中。MarkItDown 的价值可以总结为降低文档预处理成本 统一多格式输入 保留文档结构 输出 LLM 友好的 Markdown 支持插件和云端增强能力六、使用教程1. 环境要求MarkItDown 要求Python 3.10 建议使用虚拟环境创建虚拟环境python -m venv .venv source .venv/bin/activateWindowspython -m venv .venv .venv\Scripts\activate如果使用 Condaconda create -n markitdown python3.12 conda activate markitdown2. 安装 MarkItDown安装全部可选依赖pip install markitdown[all]如果只需要部分格式可以按需安装pip install markitdown[pdf,docx,pptx]常见可选依赖包括[all]安装全部可选依赖 [pdf]PDF 支持 [docx]Word 支持 [pptx]PowerPoint 支持 [xlsx]Excel 支持 [xls]旧版 Excel 支持 [outlook]Outlook 消息支持 [audio-transcription]音频转录支持 [youtube-transcription]YouTube 转录支持 [az-doc-intel]Azure Document Intelligence 支持 [az-content-understanding]Azure Content Understanding 支持3. 从源码安装git clone https://github.com/microsoft/markitdown.git cd markitdown pip install -e packages/markitdown[all]4. 命令行使用把 PDF 转成 Markdownmarkitdown path-to-file.pdf document.md指定输出文件markitdown path-to-file.pdf -o document.md通过管道输入cat path-to-file.pdf | markitdown转换 Wordmarkitdown report.docx -o report.md转换 PowerPointmarkitdown slides.pptx -o slides.md转换 Excelmarkitdown data.xlsx -o data.md转换 HTMLmarkitdown page.html -o page.md5. Python API 基础用法from markitdown import MarkItDown md MarkItDown(enable_pluginsFalse) result md.convert(test.xlsx) print(result.text_content)也可以处理 PDFfrom markitdown import MarkItDown md MarkItDown() result md.convert(report.pdf) with open(report.md, w, encodingutf-8) as f: f.write(result.text_content)6. 使用 LLM 进行图片描述from markitdown import MarkItDown from openai import OpenAI client OpenAI() md MarkItDown( llm_clientclient, llm_modelgpt-4o, llm_prompt请提取图片中的文字、图表和关键信息。 ) result md.convert(example.jpg) print(result.text_content)适合处理截图、流程图、PPT 图片、产品图等。7. 使用 Azure Document Intelligencefrom markitdown import MarkItDown md MarkItDown( docintel_endpointdocument_intelligence_endpoint ) result md.convert(test.pdf) print(result.text_content)CLImarkitdown path-to-file.pdf \ -o document.md \ -d \ -e document_intelligence_endpoint8. 使用 Azure Content Understandingfrom markitdown import MarkItDown md MarkItDown( cu_endpointcontent_understanding_endpoint ) result md.convert(report.pdf) print(result.markdown)如果希望只让 PDF 使用 Content Understandingfrom markitdown import MarkItDown from markitdown.converters import ContentUnderstandingFileType md MarkItDown( cu_endpointcontent_understanding_endpoint, cu_file_types[ContentUnderstandingFileType.PDF] )9. 插件使用查看已安装插件markitdown --list-plugins启用插件markitdown --use-plugins path-to-file.pdf安装 OCR 插件pip install markitdown-ocr pip install openaiPython 使用插件from markitdown import MarkItDown from openai import OpenAI md MarkItDown( enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o ) result md.convert(document_with_images.pdf) print(result.text_content)10. Docker 使用构建镜像docker build -t markitdown:latest .运行转换docker run --rm -i markitdown:latest ~/your-file.pdf output.md11. 测试与开发进入 MarkItDown 包目录cd packages/markitdown安装测试工具pip install hatch运行测试hatch shell hatch test提交 PR 前运行pre-commit run --all-files七、安全注意事项MarkItDown 会以当前进程权限执行 I/O 操作。这意味着如果你把不可信输入直接传给 MarkItDown它可能访问当前进程有权限访问的本地路径、URL 或网络资源。在服务端或托管环境中建议限制上传文件类型 限制文件大小 限制可访问路径 禁止任意 URL 访问 阻断内网地址、metadata service、loopback、link-local 地址 使用最窄的 convert_* 函数 对用户输入做白名单校验 在沙箱或容器中执行转换这点非常重要尤其是在构建在线文档转换服务时。八、适合哪些场景MarkItDown 适合以下场景1. RAG 知识库预处理将 PDF、Word、PPT、Excel、HTML 批量转成 Markdown再进行切分、embedding 和入库。2. 企业文档问答把内部文档统一转换为 LLM 友好的格式用于问答、摘要、检索。3. 多格式资料归档把不同格式资料转换为 Markdown便于 Git 管理、版本控制和搜索。4. 课程和会议资料整理处理 PPT、PDF、音频和 YouTube 视频生成学习笔记或摘要。5. Agent 工具链作为 AI Agent 的文件读取工具让 Agent 能统一理解多种文件格式。6. 数据分析前处理把 Excel、CSV、JSON、XML 等转为 Markdown 说明方便 LLM 做分析解释。九、项目优势与不足优势第一多格式支持丰富。PDF、Office、图片、音频、HTML、压缩包、YouTube、EPub 等都可处理。第二输出格式对 LLM 友好。Markdown 能保留结构同时比 HTML、PDF 等格式更轻量。第三Python API 和 CLI 都很简单。既适合脚本自动化也适合命令行快速转换。第四可扩展能力强。支持插件机制也支持 Azure Document Intelligence 和 Azure Content Understanding。第五微软维护社区活跃度高。Star 数、Issue、PR 数都很高说明项目关注度和生态潜力较大。不足第一不适合高保真排版转换。如果你的目标是把 PDF 完美转换成排版一致的 Word 或 HTMLMarkItDown 不是最佳选择。第二复杂 PDF 仍可能解析不完美。多栏、扫描件、复杂表格、嵌套图片等仍需要更强 OCR 或 Azure 服务增强。第三部分格式依赖可选包。如果没有安装[all]或对应 extras某些格式可能无法转换。第四云端增强能力可能产生费用。Azure Document Intelligence 和 Azure Content Understanding 属于云服务调用使用时需要考虑费用和数据合规。第五服务端使用需要注意安全边界。对不可信文件和 URL 必须严格限制。十、总结microsoft/markitdown是一个非常适合 LLM 时代的文档预处理工具。它的核心价值不是做传统文档排版转换而是解决 AI 应用中的关键前置问题如何把各种复杂文件统一变成 LLM 更容易理解的 Markdown它把 PDF、Word、PPT、Excel、图片、音频、HTML、ZIP、YouTube、EPub 等格式统一抽象为 Markdown 输出让开发者可以更高效地构建RAG 系统 知识库问答 企业文档搜索 文档摘要工具 AI Agent 文件读取工具 多模态资料分析流程对于正在做大模型应用、知识库、文档智能、企业搜索或 AI Agent 的开发者来说MarkItDown 是一个非常值得关注和实践的开源项目。互动话题你在做 RAG 或知识库项目时最头疼的文档类型是哪一种PDFWordPowerPointExcel扫描图片音频/视频网页 HTML压缩包混合资料。欢迎在评论区分享你的经验和解决方案。
