MinerU：4GB 显存跑通文档解析，输出 LLM 可用的 Markdown 与 JSON

MinerU：4GB 显存跑通文档解析，输出 LLM 可用的 Markdown 与 JSON

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

📌 场景：把一批扫描件和 Office 报告喂进 RAG 管线

你正在给 RAG（检索增强生成）管线喂语料，手里是一堆扫描版论文加几份 Office 报告。转成 Markdown 后双栏阅读顺序错乱、跨页表格断成两半、行内公式变成乱码，而想调用 72B 级的 VLM（视觉语言大模型）来救场，显存又不够。MinerU 要解决的就是这类问题：把 PDF、图片、DOCX、PPTX、XLSX 一次转成结构化 Markdown 和带坐标的 JSON，且最低 4GB 显存、纯 CPU 也能跑。

MinerU 是什么：本地后端的文档解析工具

MinerU 是一个文档解析工具（当前 3.4.4，基于 Apache 2.0 的开源许可）。输入 PDF、图片、DOCX、PPTX、XLSX，输出 Markdown、middle.json、content_list.json等结构化文件，块级带 0–1000 归一化坐标。它和 pdfplumber 这类纯文本提取库的差别在于有布局理解模型：公式还原成 LaTeX（数学公式标记语言）、表格还原成 HTML，而不是一串裸字符串；它和 72B 级 VLM 服务的差别在资源门槛：pipeline 后端最低 4GB 显存、支持纯 CPU，OmniDocBench（公开文档解析评测集）v1.6 得分 86.47，与 8GB 显存的 VLM 后端（95.30）相差约 9 分，换来的是 CPU 可运行和更低部署成本。

⚙️ 从零跑通：装、配、跑、看输出

装：Python 要求 3.10–3.13，用 uv（Rust 写的加速包管理器）装全功能包，包含 vlm、pipeline、gradio 三个组件。

pip install --upgrade pip pip install uv uv pip install -U "mineru[all]"

配：默认从 huggingface 拉模型，国内网络切换成 modelscope 镜像源即可；不配则保持默认。

# 仅国内网络需要；首次运行会自动下载模型到本地缓存 export MINERU_MODEL_SOURCE=modelscope

跑：一条命令完成解析，-p是输入文件（也支持目录），-o是输出目录；未传--api-url时 CLI 自动拉起本地临时服务。

# GPU 机器（Volta 及以后架构或 Apple Silicon）默认走 hybrid-engine 后端 mineru -p ./demo/pdfs/demo1.pdf -o ./output # 纯 CPU 或低显存机器，显式指定 pipeline 后端 mineru -p ./demo/pdfs/demo1.pdf -o ./output -b pipeline

看输出：输出目录按后端名和输入文件名分层，核心是demo1.md（带公式和表格的 Markdown）；另有*_middle.json（含 bbox 坐标的中间结构）、*_content_list.json（按阅读顺序平铺的块列表）、*_layout.pdf（每页检测框可视化，框上数字是阅读顺序），pipeline 后端还会多出*_span.pdf（行内 span 标注）。

首次运行自动下载模型，README 建议磁盘 20GB 以上（推荐 SSD）、内存最低 16GB、推荐 32GB 以上；Windows 上 CUDA 加速若不可用，按 PyTorch 官网对应版本重装 torch。

🧩 能力拆解：三个让你愿意换 MinerU 的点

公式还原成 LaTeX。你拿到的是行内$...$、独立公式直接成块的 Markdown，content_list.json里 equation 块的text_format明确标注latex，二次开发不用猜。背后是mineru/model/mfr/下的 Unimernet 公式识别模型，配合管线层的公式替换逻辑（mineru/backend/pipeline/）；3.4 版本 pipeline 后端换用 PP-OCRv6 后，OCR 相关指标提升约 11%，OCR 处理速度提升约 100%，这些收益直接反映在公式密集文档的吞吐上。

表格还原成 HTML，跨页自动拼接。你拿到的是能直接渲染的<table>，表题、脚注随表保留，跨页断开的表格拼回一张。结构识别实现在mineru/model/table/（SLANet+ 与 UNet 两条路线），跨页合并在mineru/utils/table_merge.py；同一 OmniDocBench v1.6 上，hybrid-engine 后端（high）95.39 分、vlm-engine 95.30 分，明显高于 pipeline 的 86.47 分，复杂表格场景建议直接上 8GB 显存的 engine 后端。

Office 格式原生解析，OCR 覆盖 109 种语言。传 DOCX 不用先转 PDF，mineru/model/docx/、mineru/model/pptx/、mineru/model/xlsx/直接读 OOXML（Office 文档内部 XML 结构），README 标注 DOCX 原生解析端到端比"先转 PDF 再解析"快数十倍；扫描件走mineru/model/ocr/的 OCR 链路，支持 109 种语言检测与识别，扫描版和乱码 PDF 会自动识别并启用 OCR。

📊 选型对比：5 个后端的显存与精度取舍

数据来源：README「本地部署」后端对比表与 3.3/3.4 更新记录。选型建议：没有 GPU 或只有一台 4GB 显存的机器，选 pipeline，接受 86.47 分的精度换 CPU 可运行；单机追求精度就用默认 hybrid-engine，effort取medium比high快 35%–220% 而精度只低 0.13 分；已有 vLLM 等推理服务时，用*-http-client后端把本地显存压到 2GB。

🧭 适用与不适用

✓ 推荐场景

• RAG 语料生产：多格式混排（PDF + 扫描件 + Office），要带坐标的 JSON 做后续切块
• 公式、表格密集的科技文献、技术报告，且机器只有 CPU 或 4GB 显存
• 需要可视化质检（_layout.pdf、_span.pdf）的批量解析任务

✗ 不建议场景

• 要求秒级返回的在线单文档服务：本地解析是分钟级，应走mineru-api异步接口或远端推理服务
• 极低清扫描、潦草手写：OCR 有错误率，README 建议先用在线版验证效果再部署
• 只要提取 PPTX 里一张表格：直接走mineru/model/pptx/原生解析比截图走 OCR 稳定

资源入口

• 源码安装：git clone https://gitcode.com/GitHub_Trending/mi/MinerU，随后uv pip install -e .[all]
• 官方文档：docs/zh/usage/index.md，含命令行参数、模型源配置、Docker 部署
• 输出格式说明：docs/zh/reference/output_files.md，middle.json 与 content_list 字段定义
• FAQ：docs/zh/faq/index.md，安装与 CUDA 加速问题大多有现成答案

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU