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
解决无头服务器问题：用 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 版本配套关系
迁移成功的前提是各组件版本严格匹配。以下为本次验证通过的版本组合：
组件 版本 说明 CANN 8.5.0 昇腾异构计算架构 PyTorch 2.8.0 必须精确匹配 torch-npu torch-npu 2.8.0.post2 对应 CANN 8.5.0 torchvision 0.23.0 对应 torch 2.8.0 MinerU 2.7.6 文档解析主程序 transformers 4.57.6 必须 4.x（5.x 不兼容） huggingface-hub 0.36.2 必须 <1.0（与 transformers 4.x 配套） doclayout-yolo 0.0.4 Pipeline 布局检测 opencv-python-headless 4.13.0.92 无头版本，替代 opencv-python
torch-npu 与 CANN 对应关系速查：
CANN 版本 torch-npu 版本 torch 版本 8.5.0 2.8.0.post2 2.8.0 8.0.x 2.5.1.post1 2.5.1 7.0.x 2.1.0.post17 2.1.0
具体可查阅
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 设备可见
执行命令：
预期输出（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 版本
执行命令：
预期输出：
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 ...
执行命令：
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 ...
为什么限制版本？
步骤 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],
检查点：标题、正文、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 支持的后端模式
后端 说明 命令参数 pipeline 传统流水线（布局→公式→OCR→表格），通用性好 -b pipeline -d npu vlm-auto-engine 使用本地 VLM 模型，精度高 -b vlm-auto-engine hybrid-auto-engine 混合模式（默认），新一代高精度方案 -b hybrid-auto-engine vlm-http-client 远程 VLM 服务 -b vlm-http-client -u hybrid-http-client 混合+远程 VLM -b hybrid-http-client -u
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'
项目 说明 出现时机 导入 torch_npu 时 原因 torch-npu 内部直接导入 yaml，但未在 pip 依赖中声明 解决 执行 pip install pyyaml
问题 2：libhccl.so: cannot open shared object file
ImportError: libhccl.so: cannot open shared object file: No such file or directory
项目 说明 出现时机 导入 torch_npu 时 原因 未加载 CANN 环境变量，LD_LIBRARY_PATH 中缺少 CANN 库路径 解决 执行 source /usr/local/Ascend/ascend-toolkit/set_env.sh 预防 将上述命令写入 ~/.bashrc 以实现自动加载
问题 3：libxcb.so.1: cannot open shared object file
ImportError: libxcb.so.1: cannot open shared object file: No such file or directory
项目 说明 出现时机 导入 cv2 时 原因 opencv-python（GUI 版）依赖 X11 图形库，而服务器无图形环境 解决 卸载 GUI 版，安装 headless 版（参见步骤 6）
问题 4：pip 显示 opencv 已安装但 import cv2 失败
>>> import cv2
ModuleNotFoundError: No module named 'cv2'
>>> # 但 pip list 显示 opencv-python-headless 4.13.0.92
项目 说明 出现时机 卸载 opencv-python 后 原因 两个 opencv 包共享同一 cv2/ 目录，卸载一个时共享文件被一并删除 解决 执行 pip install --force-reinstall --no-deps opencv-python-headless==4.13.0.92
问题 5：No module named 'doclayout_yolo' 或 'ultralytics'
ModuleNotFoundError: No module named 'doclayout_yolo'
项目 说明 出现时机 运行 mineru -b pipeline 时 原因 MinerU 的 pipeline 后端运行时动态导入这些包，但未在 pip 依赖中声明 解决 执行 pip install doclayout-yolo ultralytics（参见步骤 5）
问题 6：doclayout-yolo 将 torch 升级导致 torch-npu 不兼容
torch-npu 2.8.0.post2 requires torch==2.8.0, but you have torch 2.10.0
项目 说明 出现时机 安装 doclayout-yolo 之后 原因 doclayout-yolo 的依赖链拉取最新版 torch，覆盖已安装的 2.8.0 解决 pip install torch==2.8.0 torchvision==0.23.0 --no-deps（见步骤 5） 预防 安装后立即检查 python3 -c "import torch; print(torch.version )"
问题 7：无法导入名称 'find_pruneable_heads_and_indices'
ImportError: cannot import name 'find_pruneable_heads_and_indices'
from 'transformers.pytorch_utils'
项目 说明 出现时机 MinerU 加载 UnimerNet 公式识别模型时 原因 transformers 5.x 移除了该函数，MinerU 的 UnimerNet 仍在使用 解决 pip install 'transformers>=4.49.0,<5.0.0' --no-deps（见步骤 4）
问题 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
项目 说明 出现时机 transformers 初始化时 原因 transformers 4.x 限制 huggingface-hub < 1.0，但 mineru 默认拉取 1.x 解决 pip install 'huggingface-hub>=0.34.0,<1.0'（见步骤 4）
问题 9：No module named 'decorator' + ACL 错误码 500001
ModuleNotFoundError: No module named 'decorator'
SetPrecisionMode ... error code is 500001
项目 说明 出现时机 NPU 推理阶段 原因 CANN 内部 Python 组件（te、superkernel 等）依赖 decorator/attrs，缺失导致精度模式设置异常 解决 pip install decorator attrs（见步骤 2）
问题 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.
项目 说明 出现时机 MFD（公式检测）阶段 原因 torchvision 的 NMS 算子尚未适配 NPU，自动回退 CPU 执行 影响 无需处理。功能不受影响，仅有轻微性能损耗
问题 11：首次运行模型初始化极慢（约 170 秒）
DocAnalysis 初始化中，此过程可能需要一些时间......
# 等待 2~3 分钟
DocAnalysis 初始化完成！
模型初始化耗时：162.7
项目 说明 出现时机 首次运行 mineru 命令时 原因 需加载所有子模型（Layout YOLO、MFD YOLO、UnimerNet、OCR 等）到 NPU，且 ModelScope 会校验本地缓存 影响 仅首次较慢，后续运行（同进程内）模型已缓存在内存中
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 快速参考
完整版本矩阵
包名 版本 备注 mineru 2.7.6 主程序 torch 2.8.0 必须精确匹配 torch-npu torch-npu 2.8.0.post2 对应 CANN 8.5.0 torchvision 0.23.0 对应 torch 2.8.0 transformers 4.57.6 必须 4.x（5.x 不兼容） huggingface-hub 0.36.2 必须 <1.0 doclayout-yolo 0.0.4 Pipeline 布局检测 ultralytics 8.4.23 YOLO 推理框架 opencv-python-headless 4.13.0.92 替代 opencv-python accelerate 1.13.0 模型加速 rapid-table 3.0.1 表格识别 pyyaml 6.0.3 torch-npu 隐式依赖 decorator 5.2.1 CANN 运行时隐式依赖 attrs 25.4.0 CANN 运行时隐式依赖 dill 0.4.1 模型反序列化依赖 shapely 2.1.2 几何计算 pyclipper 1.4.0 多边形裁剪 omegaconf 2.3.0 配置管理
日常使用命令速查
# 加载环境（每次新终端必须执行，或写入 ~/.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
