MinerU 测试报告

日期: 2026-03-05

环境: ub2 (RTX 4090 24GB, Ubuntu 20.04, Python 3.10)

版本: MinerU 2.7.6

简介

MinerU 是上海 AI 实验室（OpenDataLab）开源的 PDF → Markdown/JSON 转换工具，专注复杂文档（论文、扫描件）的结构化提取。GitHub 30K+ stars。

三种后端

后端	原理	VRAM 需求
pipeline	传统流水线：布局检测(YOLO) → OCR → 公式/表格识别	~4-6GB
vlm	1.2B 视觉语言模型直接"看"文档	20GB+
hybrid（默认）	vlm + pipeline 结合，文本 PDF 直接提取，扫描件走 VLM	20GB+

安装过程

基础安装


python3.10 -m venv ~/mineru-venv
source ~/mineru-venv/bin/activate
pip install mineru          # 基础版，不含 torch/vllm
pip install torch torchvision  # 从清华镜像，~3GB

踩坑:

pip install mineru[all] 会拉 vllm + ray + triton，依赖链极深（~5GB+），且 torch 2.10 下载 900MB 容易超时断连
基础版不含 torch，运行时报 NameError: name 'torch' is not defined
清完 67GB pip 缓存后才有足够磁盘空间安装 torch

依赖地狱

依赖	问题	解决
torch 2.10	`weights_only=True` 默认行为与 YOLO 模型不兼容	需降级到 2.5.x
transformers 4.45.2	`from_pretrained` 处理 safetensors metadata=None 崩溃	升级到 4.48（但与 struct-eqtable <=4.45.2 冲突）
tokenizers	4.48 要求 >=0.21,<0.22，需精确匹配 0.21.1	`pip install --no-deps tokenizers==0.21.1`
accelerate	vlm 后端必需，基础安装不含	`pip install accelerate>=0.26.0`
doclayout_yolo	pipeline 后端必需，基础安装不含	`pip install doclayout_yolo ultralytics`

核心矛盾: torch 2.10 (最新) vs MinerU 的 YOLO 模型格式（需要旧版 torch 的 pickle 加载）。transformers 4.45.2 (MinerU 锁定) vs safetensors 新版（需要 4.46+ 修复）。

测试结果

Pipeline 后端 ❌


_pickle.UnpicklingError: Weights only load failed.
Unsupported global: GLOBAL doclayout_yolo.nn.tasks.YOLOv10DetectionModel

torch 2.10 默认 weights_only=True，拒绝加载 YOLO 的 pickle 权重。需要降级 torch 或修改 MinerU 源码添加 torch.serialization.add_safe_globals()。

VLM 后端 ❌


torch.OutOfMemoryError: CUDA out of memory.
Tried to allocate 16.09 GiB. GPU has 23.65 GiB total, 3.01 GiB free.

模型加载: ~20GB VRAM
推理（单页 PDF）: 额外 16GB+
总需求: ~36GB，4090 (24GB) 无法运行
即使只处理 2 页也 OOM

模型下载

VLM 模型 opendatalab/MinerU2.5-2509-1.2B (2.15GB):

HuggingFace: ❌ 需翻墙，下载中断
ModelScope: ✅ 国内直连，~3 分钟完成
设置: export MINERU_MODEL_SOURCE=modelscope

Pipeline 模型 opendatalab/PDF-Extract-Kit-1.0:

HuggingFace: ❌ 同样需翻墙
未测试 ModelScope（pipeline 后端因 torch 版本问题未跑通）

结论

MinerU 在 ub2 (4090 24GB) 上目前无法运行，核心原因:

1. Pipeline: torch 2.10 安全策略变更，与 YOLO 模型不兼容

2. VLM: 1.2B 模型 + 高分辨率 PDF 图片的 attention 计算，24GB VRAM 不够

可行方案（如需后续尝试）

方案	操作	预期效果
降级 torch 到 2.5.x	新建 venv，装旧版 torch	Pipeline 应能跑通
VLM API 模式	`vlm-http-client`，接远端 GPU	VLM 效果，不受本地 VRAM 限制
用 marker 替代	`pip install marker-pdf`	类似工具，依赖更轻
等 MinerU 适配	等官方修复 torch 2.10 兼容	最省事

环境信息


MinerU: 2.7.6
Python: 3.10.11
torch: 2.10.0+cu128
transformers: 4.48.0 (强制装，与 struct-eqtable 冲突)
GPU: RTX 4090 24GB
CUDA: 12.8
OS: Ubuntu 20.04