MinerU PDF 解析（Mac M1 部署 + 使用）

触发条件

• 需要把 PDF（含扫描件/图片型 PDF）解析成 Markdown、JSON、结构化文本
• 用户发来 PDF 要提取内容/做知识库
• MinerU 报模型缺失/下载失败

环境（2026-08-27 实测，macOS Apple Silicon）

• 位置：<你的工作目录>/mineru-venv/（独立 venv，mineru 3.4.5）
• 模型目录：<你的工作目录>/mineru-models/（15 个文件 1.0GB，sha256 全部验证过）
• 配置：~/mineru.json → models-dir.pipeline: <你的工作目录>/mineru-models
• 中文公式支持默认关（MINERU_FORMULA_CH_SUPPORT 未设时用 unimernet_small 而非 pp_formulanet）

基本用法

unset PYTHONPATH   # 必须！否则加载 Hermes venv 的包
<你的工作目录>/mineru-venv/bin/mineru \
  -p "输入.pdf" -o 输出目录 -b pipeline

• -b pipeline：本地模型解析（默认 hybrid-engine 需要 VLM 模型，别用）
• 输出：输出目录/<文件名>/auto/ 下含 *.md、*_model.json、*_span.pdf、images/
• 252 页书全量解析约 4-6 分钟（M1 Pro，原生文字版）
• 扫描版中文书慢 3-4 倍：走 OCR 逐页识别，实测 484 页扫描书 >20 分钟——属正常，别当卡死杀进程；窗口 32 全程稳定不崩
• 长书推荐后台跑：任务尾加 echo "MINERU_EXIT=$?" 便于判定成功；启动后先确认过了模型加载阶段（早崩都是 PYTHONPATH/模型缺失类），之后等完成通知即可
• 大文件可拆段并行（2 worker 实测 2.1x，32GB 上限 2 个）：见 MiJi 主 skill「大文件并行解析」与 tools/split_pdf.py

⚠️ 关键坑（全部实测踩过）

1. 模型下载失败（国内网络）

• 根因 A：hf download opendatalab/PDF-Extract-Kit-1.0 会拉整个 repo 10GB+，但 MinerU 3.4.5 pipeline 只需要 7 个子路径约 1GB（Layout/PP-DocLayoutV2、MFR/unimernet_hf_small_2503、OCR/paddleocr_torch、TabRec/SlanetPlus、TabRec/UnetStructure、TabCls/paddle_table_cls；pp_formulanet 仅当开中文公式时才要）
• 根因 B：hf-mirror 直连 = 0 字节（被墙），必须走代理（6.2MB/s）；或直接 modelscope + 代理（4.9MB/s，aria2 -x8 下 810MB 仅 20 秒）
• hf CLI 走 hf-mirror 会报 does not seem to be on huggingface.co（域名校验）→ 别用 hf CLI，用 curl/aria2 直下 resolve URL

2. M1 Mac 内存崩溃

• 默认窗口 64 页/批，长文档跑 3-4 批后 MPS 内存累积崩溃（Layout Predict 中途报错，无 traceback，输出目录空）
• 解法：export MINERU_PROCESSING_WINDOW_SIZE=32（32 页/批稳定跑完 252 页）
• 症状特征：前几批正常、最后批 Layout 阶段进程退出 + resource_tracker: leaked semaphore objects

3. PYTHONPATH 污染

• Hermes 会话注入的 PYTHONPATH 会污染 mineru venv → 跑前必须 unset PYTHONPATH

4. 下载验证

• 大文件 sha256 验证：HF resolve URL 的 ?download=true HEAD 响应里 x-linked-etag 就是官方 sha256，shasum -a 256 对比
• aria2 从 modelscope 下的文件也要验（之前 hf-mirror 的 aria2 下载就损坏过一次：大小对但 sha 不对）

模型文件清单（验证过的完整列表）

models/Layout/PP-DocLayoutV2/{config.json, preprocessor_config.json, model.safetensors 214MB}
models/MFR/unimernet_hf_small_2503/{config.json, generation_config.json, special_tokens_map.json, tokenizer.json, tokenizer_config.json, README.md, model.safetensors 810MB}
models/OCR/paddleocr_torch/{ch_PP-OCRv6_small_det_infer.safetensors 9.9MB, ch_PP-OCRv6_small_rec_infer.safetensors 21.2MB}
models/TabRec/SlanetPlus/slanet-plus.onnx 7.7MB
models/TabRec/UnetStructure/unet.onnx 8.3MB
models/TabCls/paddle_table_cls/PP-LCNet_x1_0_table_cls.onnx 6.7MB

相关

• book-to-skill skill：把解析出的 Markdown 打包成可复用 skill
• 模型下载替代方案：modelscope snapshot_download（MinerU 官方支持 MINERU_MODEL_SOURCE=modelscope）