MinerU 2.7.6 迁移部署指导书（昇腾 910B）

1 模型与工具简介

MinerU 是一款开源的高质量文档解析工具，支持将 PDF、图片等文档转换为 Markdown、JSON 等结构化格式。其核心能力包括版面分析（Layout）、公式检测与识别（MFD/MFR）、OCR 文字识别、表格识别等，底层依赖 PyTorch 进行深度学习推理。

MinerU 原生支持 CUDA GPU 推理。本文档记录将其迁移到 昇腾 910B NPU 上运行的完整过程，包括迁移思路、逐步操作、预期结果及常见问题处理。

2 迁移思路总览

2.1 迁移原理

昇腾 NPU 迁移的核心思路是：用 torch-npu 替代 CUDA 后端，使 PyTorch 模型无需修改代码即可在 NPU 上运行。整体迁移路径如下：

原始环境（GPU）                    目标环境（NPU）
┌──────────────────┐             ┌──────────────────┐
│  MinerU 2.7.6   │            │  MinerU 2.7.6   │
│  PyTorch + CUDA │  ──迁移──>  │  PyTorch + NPU  │
│  transformers   │            │  torch-npu      │
│  GPU 推理       │             │  NPU 推理       │
└──────────────────┘             └──────────────────┘

2.2 迁移关键点

MinerU 本身是一个 应用层工具（非单一模型），内部集成了多个子模型。迁移时不需要修改 MinerU 源码，只需要：

搭建 NPU 基础环境：安装 CANN 驱动 → PyTorch → torch-npu，使 torch.npu.is_available() 返回 True

安装 MinerU 及其依赖：处理好版本兼容性（transformers、huggingface-hub 等）

解决无头服务器问题：用 opencv-python-headless 替代 opencv-python

补齐隐式依赖：安装 pip 未声明但运行时必需的包（pyyaml、decorator、dill 等）

运行时指定 NPU 设备：通过 --device npu 参数将推理调度到 NPU

2.3 迁移流程概览

步骤1             步骤2             步骤3             步骤4             步骤5
确认硬件环境  ──>  安装 PyTorch  ──>  安装 MinerU   ──>  下载模型     ──>  验证推理
·CANN版本         +torch-npu        +处理依赖冲突      ·Pipeline模型     ·创建测试PDF
·NPU设备          ·版本严格匹配      ·OpenCV适配       ·VLM模型          ·NPU推理
·Python版本                         ·补齐隐式依赖                       ·检查输出

2.4 版本配套关系

迁移成功的前提是各组件版本严格匹配。以下为本次验证通过的版本组合：

torch-npu 与 CANN 对应关系速查：

具体可查阅

torch-npu 发布页

3 环境准备与确认

3.1 确认 CANN 已安装

执行命令：

cat /usr/local/Ascend/ascend-toolkit/latest/compiler/version.info | head -1

预期输出：

Version=8.5.0

如版本不同，请根据实际 CANN 版本选择对应的 torch-npu 版本（参见 2.4 节）。

3.2 确认 NPU 设备可见

执行命令：

ls /dev/davinci*

预期输出（8 卡环境）：

/dev/davinci0  /dev/davinci1  /dev/davinci2  /dev/davinci3
/dev/davinci4  /dev/davinci5  /dev/davinci6  /dev/davinci7
/dev/davinci_manager

3.3 加载 CANN 环境变量

执行命令：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

说明：每次新开终端都需要执行此命令。建议写入 ~/.bashrc 实现自动加载：

echo 'source /usr/local/Ascend/ascend-toolkit/set_env.sh' >> ~/.bashrc

为什么需要这一步？该脚本会将 CANN 的库路径（如 libhccl.so 所在目录）加入 LD_LIBRARY_PATH。若跳过此步，后续 import torch_npu 时会报 ImportError: libhccl.so: cannot open shared object file。

3.4 确认 Python 版本

执行命令：

python3 --version

预期输出：

Python 3.11.14

支持 Python 3.9 ~ 3.11。

4 逐步迁移操作

步骤 1：安装 PyTorch + torch-npu

执行命令：

pip install torch==2.8.0 torch-npu==2.8.0.post2

预期输出（关键行）：

Successfully installed ... torch-2.8.0 torch-npu-2.8.0.post2 ...

验证命令：

source /usr/local/Ascend/ascend-toolkit/set_env.sh
python3 -c "
import torch
import torch_npu
print('torch:', torch.__version__)
print('torch_npu:', torch_npu.__version__)
print('NPU available:', torch.npu.is_available())
print('NPU count:', torch.npu.device_count())
"

预期输出：

torch: 2.8.0+cpu
torch_npu: 2.8.0.post2
NPU available: True
NPU count: 8

检查点： NPU available 必须为 True。若为 False，请检查 CANN 驱动安装和环境变量加载。

步骤 2：安装基础隐式依赖

torch-npu 和 CANN 运行时隐式依赖以下包，pip 不会自动安装：

执行命令：

pip install pyyaml numpy decorator attrs

预期输出：

Successfully installed PyYAML-6.0.3 numpy-2.4.3 decorator-5.2.1 attrs-25.4.0

为什么需要这些包？

pyyaml：torch-npu 的 _memory_viz.py 直接 import yaml，缺失会导致 torch_npu 整体加载失败

numpy：torch 的 tensor 与 numpy 转换功能依赖此包

decorator / attrs：CANN 内部 Python 组件（te、superkernel 等）的依赖，缺失会导致 NPU 推理时报 ACL 错误

步骤 3：安装 MinerU 主程序

执行命令：

pip install mineru==2.7.6

预期输出（关键行）：

Successfully installed ... mineru-2.7.6 ...

步骤 4：安装兼容版本的 transformers 生态

MinerU 的公式识别模型（UnimerNet）依赖 transformers，但存在版本兼容问题，需手动控制：

执行命令：

pip install 'transformers>=4.49.0,<5.0.0' 'huggingface-hub>=0.34.0,<1.0' accelerate

预期输出（关键行）：

Successfully installed ... transformers-4.57.6 huggingface-hub-0.36.2 accelerate-1.13.0 ...

为什么限制版本？

transformers 5.x 移除了 find_pruneable_heads_and_indices 函数，MinerU 的 UnimerNet 模型仍在使用它

transformers 4.x 要求 huggingface-hub < 1.0，而 MinerU 默认会拉取 1.x 版本

步骤 5：安装 Pipeline 后端运行时依赖

MinerU 的 pipeline 后端在运行时动态导入多个包，它们不在 mineru 的 pip 依赖列表中，需手动安装：

执行命令：

pip install doclayout-yolo ultralytics ftfy shapely pyclipper rapid-table omegaconf dill

预期输出（关键行）：

Successfully installed ... doclayout-yolo-0.0.4 ultralytics-8.4.23 ...

❗ 重要：立即修复 torch 版本

doclayout-yolo 的依赖链会将 torch 拉升到最新版（如 2.10.0），破坏 torch-npu 兼容性。安装后必须立即回退：

修复命令：

pip install torch==2.8.0 torchvision==0.23.0 --no-deps

验证命令：

python3 -c "import torch; print(torch.__version__)"

预期输出：

2.8.0+cpu

若输出为 2.10.0 或其他版本，说明修复未生效，请重新执行修复命令。

步骤 6：处理 OpenCV 无头服务器适配

昇腾服务器通常无图形界面，而步骤 5 中 doclayout-yolo / ultralytics 会拉入依赖 X11 图形库的 opencv-python，导致 import cv2 时报 libxcb.so.1: cannot open shared object file。

需要用无头版本替代：

执行命令：

pip uninstall opencv-python -y
pip install --force-reinstall --no-deps opencv-python-headless==4.13.0.92

验证命令：

python3 -c "import cv2; print('OpenCV:', cv2.__version__)"

预期输出：

OpenCV: 4.13.0

注意： opencv-python 和 opencv-python-headless 共享同一个 cv2 目录。 卸载其中一个时，共享文件会被一并删除。因此必须用 --force-reinstall 重新安装 headless 版本。 如果只做 pip uninstall + 普通 pip install，可能出现 pip 显示已安装但 import cv2 失败的情况。

步骤 7：下载模型

MinerU 内置支持从 HuggingFace 或 ModelScope 下载模型。国内环境推荐使用 ModelScope：

执行命令：

export MINERU_MODEL_SOURCE=modelscope
,[object Object],
,[object Object],
,[object Object],
,[object Object],

print('[下载] MinerU2.5-2509-1.2B ...')
p2 = snapshot_download('OpenDataLab/MinerU2.5-2509-1.2B')
print(f'VLM 模型已保存到: {p2}')
"

预期输出：

[下载] PDF-Extract-Kit-1.0 ...
Processing 178 items: 100%|██████████| 178/178 [03:40<00:00, 1.24s/it]
Download model 'OpenDataLab/PDF-Extract-Kit-1.0' successfully.
Pipeline 模型已保存到: /root/.cache/modelscope/hub/models/OpenDataLab/PDF-Extract-Kit-1___0
[下载] MinerU2.5-2509-1.2B ...
Processing 14 items: 100%|██████████| 14.0/14.0 [00:46<00:00, 3.32s/it]
Download model 'OpenDataLab/MinerU2.5-2509-1.2B' successfully.
VLM 模型已保存到: /root/.cache/modelscope/hub/models/OpenDataLab/MinerU2___5-2509-1___2B

说明：

Pipeline 模型约 3~5 GB，VLM 模型约 2.2 GB，总计约 7 GB

模型默认缓存在 ~/.cache/modelscope/hub/models/ 目录下

只使用 pipeline 后端时，可仅下载 Pipeline 模型

5 推理验证

5.1 创建测试 PDF

执行命令：

python3 -c "
from reportlab.lib.pagesizes import A4
from reportlab.pdfgen import canvas
c = canvas.Canvas('/tmp/test_mineru.pdf', pagesize=A4)
c.setFont('Helvetica', 16)
c.drawString(100, 700, 'MinerU Test Document on Ascend 910B')
c.setFont('Helvetica', 12)
c.drawString(100, 660, 'This is a test document to verify MinerU deployment.')
c.drawString(100, 630, 'Testing NPU inference with torch-npu on CANN 8.5.0')
c.drawString(100, 600, 'E = mc^2')
c.save()
print('测试 PDF 已创建: /tmp/test_mineru.pdf')
"

预期输出：

测试 PDF 已创建: /tmp/test_mineru.pdf

5.2 执行 NPU 推理

执行命令：

source /usr/local/Ascend/ascend-toolkit/set_env.sh
export MINERU_MODEL_SOURCE=modelscope

mineru -p /tmp/test_mineru.pdf -o /tmp/mineru_output -b pipeline -d npu

预期输出（关键日志）：

INFO | mineru.backend.pipeline.pipeline_analyze:doc_analyze:129 - Batch 1/1: 1 pages/1 pages
INFO | mineru.backend.pipeline.model_init:__init__:209 - DocAnalysis init, this may take some times......
INFO | mineru.backend.pipeline.model_init:__init__:271 - DocAnalysis init done!
INFO | mineru.backend.pipeline.pipeline_analyze:custom_model_init:65 - model init cost: 162.7
Layout Predict: 100%|██████████| 1/1 [00:19<00:00, 19.65s/it]
MFD Predict: 100%|██████████| 1/1 [00:04<00:00,  4.29s/it]
MFR Predict: 100%|██████████| 1/1 [00:06<00:00,  6.56s/it]
OCR-det Predict: 100%|██████████| 1/1 [00:34<00:00, 34.41s/it]
Processing pages: 100%|██████████| 1/1 [00:12<00:00, 12.71s/it]
INFO | mineru.cli.common:_process_output:168 - local output dir is /tmp/mineru_output/test_mineru/auto

说明：

首次运行模型初始化较慢（约 170 秒），后续运行（同进程内）模型已缓存，速度正常

Layout Predict → MFD Predict → MFR Predict → OCR-det Predict → Processing pages 为完整的 Pipeline 推理流程

可能出现 torchvision::nms ... will fall back to run on the CPU 告警，属正常现象（NMS 算子尚未适配 NPU，自动回退 CPU，不影响功能）

5.3 检查输出结果

执行命令：

cat /tmp/mineru_output/test_mineru/auto/test_mineru.md

预期输出：

# MinerU Test Document on Ascend 910B
,[object Object],
,[object Object],
,[object Object],

undefined

检查点：标题、正文、LaTeX 公式均被正确识别即为验证通过。

查看完整输出目录：

ls -la /tmp/mineru_output/test_mineru/auto/

预期输出：

test_mineru.md                # Markdown 结果
test_mineru_content_list.json  # 结构化内容列表
test_mineru_middle.json        # 中间 JSON
test_mineru_model.json         # 模型检测结果
test_mineru_layout.pdf         # 布局可视化
test_mineru_span.pdf           # Span 可视化
test_mineru_origin.pdf         # 原始 PDF 副本
images/                        # 提取的图片

5.4 支持的后端模式

5.5 便捷命令

部署过程中创建了便捷脚本 /usr/local/bin/mineru-npu，自动加载 CANN 环境并指定 NPU 设备：

mineru-npu -p <PDF文件> -o <输出目录> -b pipeline

6 常见问题与解决方法

以下问题均为实际调测过程中遇到并验证过的，按出现顺序排列。

问题 1：No module named 'yaml'

File "torch_npu/npu/_memory_viz.py", line 10, in <module>
    import yaml
ModuleNotFoundError: No module named 'yaml'

问题 2：libhccl.so: cannot open shared object file

ImportError: libhccl.so: cannot open shared object file: No such file or directory

问题 3：libxcb.so.1: cannot open shared object file

ImportError: libxcb.so.1: cannot open shared object file: No such file or directory

问题 4：pip 显示 opencv 已安装但 import cv2 失败

>>> import cv2
ModuleNotFoundError: No module named 'cv2'
>>> # 但 pip list 显示 opencv-python-headless 4.13.0.92

问题 5：No module named 'doclayout_yolo' 或 'ultralytics'

ModuleNotFoundError: No module named 'doclayout_yolo'

问题 6：doclayout-yolo 将 torch 升级导致 torch-npu 不兼容

torch-npu 2.8.0.post2 requires torch==2.8.0, but you have torch 2.10.0

问题 7：无法导入名称 'find_pruneable_heads_and_indices'

ImportError: cannot import name 'find_pruneable_heads_and_indices'
  from 'transformers.pytorch_utils'

问题 8：需要 huggingface-hub>=0.34.0,<1.0

ImportError: huggingface-hub>=0.34.0,<1.0 is required ... but found huggingface-hub==1.7.1

问题 9：No module named 'decorator' + ACL 错误码 500001

ModuleNotFoundError: No module named 'decorator'
SetPrecisionMode ... error code is 500001

问题 10：torchvision::nms ... 将回退到 CPU 运行

Warning: The operator 'torchvision::nms' is not currently supported on the NPU backend
  and will fall back to run on the CPU.

问题 11：首次运行模型初始化极慢（约 170 秒）

DocAnalysis 初始化中，此过程可能需要一些时间......
# 等待 2~3 分钟
DocAnalysis 初始化完成！
模型初始化耗时：162.7

7 一键安装脚本

基于上述全部调测经验，以下脚本可在全新环境中一键完成部署：

#!/bin/bash
# MinerU 2.7.6 昇腾 910B 一键部署脚本
# 前置条件：CANN 8.5.0 已安装，Python 3.11
set -e
,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],

echo "=============================="
echo "部署完成！验证命令："
echo "  source /usr/local/Ascend/ascend-toolkit/set_env.sh"
echo "  export MINERU_MODEL_SOURCE=modelscope"
echo "  mineru -p <PDF文件> -o <输出目录> -b pipeline -d npu"
echo "=============================="

8 快速参考

完整版本矩阵

日常使用命令速查

# 加载环境（每次新终端必须执行，或写入 ~/.bashrc）
source /usr/local/Ascend/ascend-toolkit/set_env.sh
export MINERU_MODEL_SOURCE=modelscope
,[object Object],
,[object Object],
,[object Object],
,[object Object],
,[object Object],

mineru-npu -p input.pdf -o output_dir -b pipeline