扫描件 PDF 转 Markdown：MarkItDown 接入视觉大模型的实操记录

扫描件 PDF 转 MarkdownMarkItDown 接入视觉大模型的实操记录【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown手头有一批扫描件 PDF走常规解析管线得到的全是空文本因为扫描件里没有真实的文字层只有图片。我花了一个下午用 MarkItDown 把整条链路跑通它是个把 PDF、Office 文档、网页批量转成 Markdown 的 Python 工具装上视觉大模型后还能顺手把扫描件里的字认出来。下面按我实际操作顺序记录所有命令都可以直接照抄。搭建环境与跑通第一个转换先准备 Python 3.10 环境从源码装核心包git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[pdf] # [pdf] 额外装 PDF 解析依赖装完直接拿一份发票类 PDF 试 CLI一行出结果markitdown path/to/invoice.pdf -o invoice.md更短的路径是 Python API四行代码和 CLI 走的是同一套内部流程from markitdown import MarkItDown md MarkItDown() print(md.convert(invoice.pdf).text_content)我用的样本是仓库里自带的收据 PDF输出保留了商品行、小计、税费、合计这些结构表格区域被整理成 Markdown 表格后面两个场景都基于它展开。仓库测试目录里的收据 PDF用来验证表格提取效果跑通三个典型场景场景一普通 PDF 里的表格。带框线表格的 PDF 直接解析就行内置转换器优先用 pdfplumber 抽表格纯文字页再退回 pdfminer不用额外配置。上一条命令的输出就是例子商品、数量、单价、合计逐行对齐。场景二给图片生成描述。这是主包自带的多模态能力构造时把 OpenAI 兼容客户端传进去图片包括嵌在 PPTX、DOCX 里的图片会被编码成>import openai from markitdown import MarkItDown client openai.OpenAI() # 需要环境变量 OPENAI_API_KEY md MarkItDown(llm_clientclient, llm_modelgpt-4o) print(md.convert(test.jpg).text_content)对仓库里的测试图输出先是一行 EXIF 元数据然后是# Description:标题下面跟着模型写的描述。用于验证视觉大模型图片描述能力的测试图含一段提示文字和一个红色圆形、一个蓝色方形场景三扫描件 PDF。前两个场景的 PDF 都有文本层扫描件没有内置解析拿到的就是空内容。仓库里的 markitdown-ocr 插件专门处理这个pip install -e packages/markitdown-ocrfrom markitdown import MarkItDown import openai client openai.OpenAI() md MarkItDown( enable_pluginsTrue, # 启用插件机制 llm_clientclient, # OCR 复用的同一个客户端 llm_modelgpt-4o, ) print(md.convert(scan.pdf).text_content)插件拿到 llm_client 后创建视觉 OCR 服务把 PDF 每一页交给模型识别默认提示词要求只返回提取的文字保持原始顺序不加任何描述所以输出就是接近原文的文本而不是看图说话。理解两个关键机制第一个是优先级。MarkItDown内部按 priority 给转换器排序数值小的先试具体格式转换器是 0.0兜底的纯文本、HTML、Zip 转换器是 10.0。插件注册的 OCR 转换器用 -1.0排在最前面等于把内置的 PDF、DOCX 转换器顶掉了。理解这一点后就能明白装了插件后同一份文件会走哪条路以及多个插件同时装时谁先响应。第二个是 LLM 参数的下发方式。llm_client、llm_model、llm_prompt在构造MarkItDown时传入一次之后每次转换时自动塞给具体转换器转换器自己只管读参数。这就是为什么换模型只改一行构造参数以及为什么 OCR 插件和主包的图片描述用的是同一套配置——两边读的是同一组参数。这个设计让接入任何 OpenAI 兼容服务自建网关、其他厂商的视觉模型都不需要改转换器代码。踩过的四个坑转 PDF 报缺依赖pip install markitdown只装核心PDF 解析要[pdf]extraspptx、docx、xlsx 同理按需加 extras。从 stdin 读文件猜不出类型cat file | markitdown会失败加-x pdf给个扩展名提示即可。输出里的 base64 被截断DOCX、PPTX 内嵌图片默认输出成data:image/png;base64...这是有意截断防止 Markdown 被撑爆要完整数据加--keep-data-uris。扫描件直接转 PDF 得到空内容内置 PDF 转换器只解析文本层不识别图片这类文件必须走 OCR 插件或云端的 Document Intelligence-d --endpoint选项。整套链路跑下来普通文档转换是本地纯离线、速度很快瓶颈都在 LLM 调用上图片多的 PPTX 会比较慢批量处理时建议控制并发。想深入看转换器怎么注册、插件如何按优先级接管文件可以从 packages/markitdown/src/markitdown/_markitdown.py 入手。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考