MinerU文档解析服务代码实例：批量处理PDF截图文件夹，自动生成结构化JSON报告-开发者社区

MinerU文档解析服务代码实例：批量处理PDF截图文件夹，自动生成结构化JSON报告

1. 为什么你需要一个能“读懂”PDF截图的工具

你有没有遇到过这样的情况：手头有一堆PDF截图——可能是会议记录的手机拍照、财务报表的屏幕快照、学术论文的关键页截取，或是PPT演示文稿的逐页保存。这些图片里藏着大量信息，但它们只是“图”，不是“文本”。复制不了、搜不到、没法整理，更别提自动分析。

传统OCR工具往往在复杂版面前“卡壳”：表格错位、公式乱码、多栏排版识别混乱；而大模型直接“看图说话”又常忽略文档特有的结构逻辑——比如标题层级、段落归属、表格行列关系。

MinerU不一样。它不是通用图文模型，而是专为“文档图像”生的。它把一张PDF截图当作一份有结构的文档来理解，而不是一张普通照片。它知道哪里是标题、哪里是正文、哪块是表格、哪行是公式。这种“文档意识”，让它的输出不只是文字堆砌，而是可被程序直接消费的结构化内容。

本文不讲部署、不聊参数，只做一件实在事：用几行Python代码，把一整个文件夹里的PDF截图，自动喂给MinerU服务，批量生成带章节、段落、表格字段的JSON报告。你不需要打开网页、不用手动上传、不用复制粘贴——运行一次脚本，结果就静静躺在你的硬盘里。

2. MinerU服务的核心能力：它到底“懂”什么

MinerU基于OpenDataLab/MinerU2.5-2509-1.2B模型构建，名字里的“1.2B”容易让人误以为是“小模型”，但它在文档理解这件事上，是实打实的“小身材，大本事”。

它不是简单地把图片转成文字。它在三个层面真正“理解”文档：

视觉结构层：能准确识别页面中的标题、子标题、正文段落、列表项、页眉页脚、分栏区域。哪怕截图里有阴影、轻微倾斜或背景水印，它也能稳定定位内容区块。
语义逻辑层：知道“图3-2”后面大概率跟着图表说明，“表4.1”对应的是下方的表格数据，“参考文献”部分必然包含作者、年份、标题三要素。它能把零散的文字块，按逻辑重新组织。
内容类型层：对不同文档类型有预设理解模式。处理财务报表时，它会主动寻找“营业收入”“净利润”等关键字段；解析学术论文时，它能区分“摘要”“方法”“结论”；看到PPT截图，则优先提取要点式短句而非长段落。

这使得它的输出远超传统OCR：不是一行行原始文字流，而是带层级、带类型、带上下文关系的结构化数据。这也是我们能用它批量生成JSON报告的根本前提——因为它的返回结果，本身就是“可编程”的。

3. 批量处理实战：从文件夹到结构化JSON的完整流程

3.1 环境准备与服务连接

MinerU镜像启动后，会提供一个本地Web服务地址（如http://localhost:7860）。我们不需要打开浏览器，而是通过HTTP API与它通信。以下代码使用requests库完成调用，无需额外安装复杂依赖。

import os import json import requests from pathlib import Path from typing import Dict, List, Any # 配置服务地址（根据你实际启动的端口调整） MINERU_API_URL = "http://localhost:7860/api/predict" # 指定待处理的截图文件夹路径 INPUT_FOLDER = Path("./pdf_screenshots") OUTPUT_JSON = "./batch_report.json"

注意：MinerU WebUI默认API接口为/api/predict，它接受Gradio格式的请求。我们模拟前端提交行为，无需修改服务端配置。

3.2 构建标准请求体：让MinerU知道你要什么

MinerU的API不是“传图就完事”，它需要明确指令。我们设计一条通用指令，兼顾准确性与泛用性：

“请完整提取图中所有可见内容，并以结构化JSON格式返回：包含文档标题（若存在）、正文段落列表、识别出的表格列表（每张表含表头和行数据）、以及任何独立公式或代码块。请保持原文语言和格式，不要总结、不要改写。”

这条指令的关键在于：

“完整提取”避免模型自行删减；
“结构化JSON格式”明确输出目标；
明确列出要提取的元素类型（标题、段落、表格、公式），引导模型激活对应解析模块；
“保持原文”确保信息保真，为后续处理留足空间。

def build_mineru_payload(image_path: Path) -> Dict[str, Any]: """构建发送给MinerU API的标准请求体""" with open(image_path, "rb") as f: image_bytes = f.read() # Base64编码图片（MinerU WebUI API要求） import base64 image_b64 = base64.b64encode(image_bytes).decode("utf-8") # 构造Gradio兼容的输入格式：[image, prompt, temperature, top_p] # 温度和top_p使用默认值，保证输出稳定 return { "data": [ f"data:image/png;base64,{image_b64}", # 图片base64 "请完整提取图中所有可见内容，并以结构化JSON格式返回：包含文档标题（若存在）、正文段落列表、识别出的表格列表（每张表含表头和行数据）、以及任何独立公式或代码块。请保持原文语言和格式，不要总结、不要改写。", # 指令 0.1, # temperature 0.9 # top_p ], "event_data": None, "fn_index": 1, # 对应WebUI中"Analyze Image"函数索引 "trigger_id": 1 }

3.3 发送请求并解析响应：拿到真正的结构化结果

MinerU返回的是一段HTML字符串（WebUI渲染用），但其中嵌入了模型生成的JSON数据。我们用正则精准提取，避免HTML解析的复杂性：

import re def call_mineru_api(payload: Dict[str, Any]) -> Dict[str, Any]: """调用MinerU API，返回解析后的结构化JSON""" try: response = requests.post(MINERU_API_URL, json=payload, timeout=120) response.raise_for_status() # MinerU返回的是HTML，JSON藏在<script>标签的window.data中 html_content = response.json()["data"][0] # 提取 window.data = {...} 中的JSON部分 json_match = re.search(r'window\.data\s*=\s*({.*?});', html_content, re.DOTALL) if json_match: json_str = json_match.group(1) # 修复常见JSON格式问题（如末尾逗号、单引号） json_str = json_str.replace("'", '"').rstrip(',') return json.loads(json_str) else: # 若未匹配到，尝试直接解析返回的纯文本（某些版本返回更干净结果） try: return response.json()["data"][0] if isinstance(response.json()["data"][0], dict) else {} except: return {"error": "无法从响应中提取有效JSON", "raw_response": html_content[:200]} except Exception as e: return {"error": f"API调用失败: {str(e)}"} # 示例：处理单张图片 # sample_img = INPUT_FOLDER / "report_page1.png" # result = call_mineru_api(build_mineru_payload(sample_img)) # print(json.dumps(result, indent=2, ensure_ascii=False))

3.4 批量处理主流程：文件夹遍历 + 并行加速

现在，把单张处理封装成函数，再套上文件夹遍历和错误处理，就是完整的批量流水线：

from concurrent.futures import ThreadPoolExecutor, as_completed import time def process_single_image(image_path: Path) -> Dict[str, Any]: """处理单张图片，返回带元数据的结果""" start_time = time.time() payload = build_mineru_payload(image_path) result = call_mineru_api(payload) end_time = time.time() # 添加元数据便于追踪 return { "filename": image_path.name, "filepath": str(image_path), "processing_time_sec": round(end_time - start_time, 2), "result": result } def batch_process_folder(input_folder: Path, max_workers: int = 3) -> List[Dict[str, Any]]: """批量处理整个文件夹，支持并发""" image_files = list(input_folder.glob("*.png")) + list(input_folder.glob("*.jpg")) + list(input_folder.glob("*.jpeg")) if not image_files: print(f"警告：文件夹 {input_folder} 中未找到PNG/JPG图片") return [] print(f"开始批量处理 {len(image_files)} 张图片（并发数：{max_workers}）...") results = [] with ThreadPoolExecutor(max_workers=max_workers) as executor: # 提交所有任务 future_to_image = {executor.submit(process_single_image, img): img for img in image_files} # 收集结果 for future in as_completed(future_to_image): try: result = future.result() results.append(result) print(f"✓ 已处理 {result['filename']} ({result['processing_time_sec']}s)") except Exception as e: print(f"✗ 处理 {future_to_image[future]} 时出错：{e}") return results # 执行批量处理 if __name__ == "__main__": all_results = batch_process_folder(INPUT_FOLDER, max_workers=2) # 保存为结构化JSON报告 report = { "generated_at": time.strftime("%Y-%m-%d %H:%M:%S"), "total_images_processed": len(all_results), "results": all_results } with open(OUTPUT_JSON, "w", encoding="utf-8") as f: json.dump(report, f, indent=2, ensure_ascii=False) print(f"\n 批量处理完成！结构化报告已保存至：{OUTPUT_JSON}")

4. 生成的JSON报告长什么样？真实效果展示

运行上述脚本后，你会得到一个清晰、分层、可直接用于下游应用的JSON文件。以下是典型输出结构（已简化）：

{ "generated_at": "2024-06-15 14:22:36", "total_images_processed": 3, "results": [ { "filename": "financial_summary.png", "filepath": "./pdf_screenshots/financial_summary.png", "processing_time_sec": 4.21, "result": { "title": "2023年度财务摘要", "paragraphs": [ "公司全年实现营业收入12.8亿元，同比增长15.3%。", "净利润达2.1亿元，较上年增长22.7%，主要得益于成本优化与新业务放量。" ], "tables": [ { "caption": "主要财务指标（单位：亿元）", "headers": ["项目", "2023年", "2022年", "同比变动"], "rows": [ ["营业收入", "12.80", "11.10", "+15.3%"], ["净利润", "2.10", "1.71", "+22.7%"], ["研发投入", "1.45", "1.28", "+13.3%"] ] } ], "formulas": [] } }, { "filename": "research_paper_method.png", "filepath": "./pdf_screenshots/research_paper_method.png", "processing_time_sec": 5.87, "result": { "title": "3. Methodology", "paragraphs": [ "We propose a two-stage framework: first, a vision encoder extracts multi-scale features from the input document image...", "Second, a layout-aware decoder generates structured output conditioned on both visual and positional embeddings." ], "tables": [], "formulas": [ "E_{vis} = \\text{ViT}(I), \\quad E_{pos} = \\text{Embed}(P)" ] } } ] }

这个JSON的价值在于：

字段明确：title、paragraphs、tables、formulas四个一级键，覆盖文档核心元素；
表格结构化：headers和rows分离，可直接导入Excel或数据库；
保留原始性：所有文字未经改写，确保法律、财务等场景的严谨性；
附带元数据：处理时间、文件路径，方便审计与调试。

5. 实用技巧与避坑指南：让批量处理更稳更快

5.1 CPU环境下的速度优化建议

MinerU在CPU上已足够快，但批量处理时仍有提升空间：

并发数不宜过高：1.2B模型虽轻，但每张图仍需加载视觉编码器。实测max_workers=2~3在4核CPU上达到最佳吞吐，再高反而因内存竞争导致整体变慢；
预热模型：首次调用延迟略高（约6-8秒），可在批量循环前，先用一张测试图调用一次，让模型“热起来”；
图片尺寸预处理：MinerU对1024x1440左右的截图效果最佳。过大（如4K截图）会显著拖慢，建议用PIL提前缩放：“img.resize((1024, int(1024 * img.height / img.width)), Image.LANCZOS)”。

5.2 常见问题与应对方案

问题现象	可能原因	解决方案
返回HTML中找不到`window.data`	MinerU版本差异或API路径变更	检查WebUI是否为最新版；尝试将`fn_index`改为`0`或`2`；启用`--debug`启动参数查看日志
表格识别错行、漏列	截图分辨率过低或表格边框模糊	提高截图DPI；用画图工具加粗表格线；在指令中加入“请特别注意表格边框，严格按行列提取”
公式识别为乱码	截图中公式为矢量图或字体缺失	优先使用PDF导出为PNG（非截图）；在指令末尾追加“公式请用LaTeX格式输出”