MarkItDown 完整上手指南：把 PDF、Office 文档批量转成结构完整的 Markdown

MarkItDown 完整上手指南把 PDF、Office 文档批量转成结构完整的 Markdown【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown上周帮朋友调试一个 RAG 知识库的数据管线发现瓶颈根本不在模型而在文档预处理二十多份 PDF 财报和 Word 合同用脚本提取后全成了丢失表格和标题的纯文本流喂进向量库后检索质量惨不忍睹。他随口问有没有工具能把各种格式统一转成 Markdown我推荐了微软开源的 MarkItDown——它把喂给 LLM 的文档预处理这件事做得最省心支持 20 余种文件格式一条命令完成转换且优先保留标题、列表、表格、链接等结构信息。一句话说清它的定位MarkItDown 是一个面向 LLM 和文本分析管线的 Python 文档转换工具把 PDF、Word、Excel、PPT、图片、音频乃至网页统一输出为结构完整的 Markdown。它与传统文本提取工具的本质区别在于输出的是带骨架的 Markdown 而非压平后的纯文本这让下游的大模型或向量检索能真正读懂文档结构。⚡ 先跑起来3 分钟完成第一个转换安装只需要一条命令建议先建好虚拟环境再装pip install markitdown[all]命令行转换单个文件用-o指定输出路径markitdown 报告.pdf -o 报告.md想快速看效果直接输出到终端即可。我拿项目自带的测试数据实测过转换质量下面这张图是测试集里一篇学术论文的首页截图来自packages/markitdown/tests/test_files/test.jpgPDF 里原本的多栏排版、图表标题、参考文献转换后都归位为清晰的标题层级和段落对影城订座单这类表格密集型文档每一张表都被规整还原成标准 Markdown 表格语法字段名、金额、日期分列对齐可直接拿去喂给模型做结构化抽取。Python API 的用法同样直观from markitdown import MarkItDown md MarkItDown() # 初始化转换器 result md.convert(报表.xlsx) # 一步完成转换 print(result.markdown) # 输出 Markdown 文本convert()返回DocumentConverterResult对象.markdown属性即转换结果.title是可选标题。 原理白话版一个按优先级派单的文档分拣中心把 MarkItDown 的工作流程想象成快递分拣中心所有包裹文件进来后先由一台识别机内置的 Magika 模型读取文件头部字节判断它是什么格式然后分拣员根据类型把包裹交给不同的专业小组转换器。核心代码在packages/markitdown/src/markitdown/_markitdown.py启动时会注册一批内置转换器每个只认一种格式self.register_converter(DocxConverter()) # Word 文档 self.register_converter(PdfConverter()) # PDF self.register_converter(XlsxConverter()) # Excel self.register_converter(ImageConverter()) # 图片每个转换器都实现两个方法accepts()判断这个文件归我管吗convert()负责真正干活。派单遵循优先级规则纯文本、HTML 这类通用转换器优先级低、负责兜底特定格式转换器优先级高、优先接单某个转换器转失败时框架会记录异常并继续尝试下一个全部失败才抛出UnsupportedFormatException。这套注册—探测—尝试—降级机制正是它扩展性好的根基。至于为什么输出选 Markdown它极度接近纯文本、token 消耗低而主流 LLM 原生会说Markdown能被大模型以最小成本准确理解。⚖️ 与 textract、pandoc 横向对比该选谁同为转 Markdown同类工具侧重完全不同。我在三个方案间做过实测对比维度MarkItDowntextractpandoc安装成本低pip 一条命令中系统依赖多低但 PDF 需额外引擎格式覆盖20 种含图片、音频、网页约 10 种偏文本覆盖广偏格式互转结构保留标题/表格/链接全保留以纯文本为主依赖输入输出格式对LLM 友好度高专为 LLM 设计低中插件扩展支持插件默认关闭无有 filter 机制结论很明确如果目标是把文件整理成资料喂给 LLM 或向量库MarkItDown 是首选pandoc 更适合追求排版保真的 docx↔latex 类互转textract 定位偏老维护活跃度不如前两者。 三个超出官方示例的进阶用法1. 直接转换网页与内存字节流convert()支持字符串路径、requests.Response、二进制流三种输入。我在实际项目中用它抓取网页正文并转 Markdownmd MarkItDown() result md.convert(https://example.com/某文章页) # 网页直接转换配合convert_stream()还能把内存中的字节流直接转换适合做 Web 服务——上传文件不必落盘到临时目录。2. 用 LLM 为图片生成智能描述传入 OpenAI 兼容客户端后图片转换器会自动调用多模态模型生成图像描述并附带 EXIF 元数据from openai import OpenAI md MarkItDown(llm_clientOpenAI(), llm_modelgpt-4o) result md.convert(示意图.png)下面这张是项目测试用的 LLM 图像样例红圆与蓝方重叠图专门用来验证描述生成是否到位位于packages/markitdown/tests/test_files/test_llm.jpg再装一个markitdown-ocr插件PDF、Word、PPT、Excel 里的扫描图片文字也能被 OCR 提取复用同一套llm_client配置无需额外安装重量级 OCR 库。3. 字段级结构化抽取接 Azure Content Understanding对发票、合同这类需要结构化字段的场景传入cu_endpoint后转换结果会自动带上 YAML front matter 形式的结构化字段如VendorName、InvoiceDate这是内置离线转换器不具备的能力。注意这是付费云端 API每次调用都计费可用cu_file_types参数限定只有特定格式才走云端。⚠️ 新手最容易踩的 5 个坑插件默认不启用装了第三方插件后CLI 必须加--use-pluginsPython 侧要设enable_pluginsTrue否则插件静默失效不报任何错。可选依赖缺失pip install markitdown只装核心库PDF、docx、pptx 各自是可选依赖。转换失败先检查是否装了markitdown[all]或对应的 extras。权限与安全MarkItDown 以当前进程权限执行 I/O行为等同open()。服务端处理不可信文件时务必先消毒输入尽量调用最窄的convert_local()/convert_stream()而非全功能的convert()。Python 版本要求 3.10老环境直接报错建议用 venv 隔离依赖避免与其他包冲突。stdin 输入要先给提示从管道读取内容时用-x、-m、-c分别给出扩展名、MIME 类型、字符集提示否则文件类型探测容易走弯路。 下一步该做什么现在就可以打开终端用你手头最乱的一份文档试效果pip install markitdown[all] markitdown 你的文档.pdf想深入源码或二次开发可以git clone https://gitcode.com/GitHub_Trending/ma/markitdown。官方示例插件在packages/markitdown-sample-plugin/所有内置转换器实现都在packages/markitdown/src/markitdown/converters/下读完一个_docx_converter.py基本就掌握了扩展套路。把格式转换这类脏活交给工具把时间留给真正有创造性的部分——这正是 MarkItDown 想帮你做到的事。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考