MinerU 昇腾 NPU 部署实战:从 910B 驱动到文档解析 API

适用:Atlas 800T A2 / 900 A2 PoD、Ascend 910B3、310P
目标:把 MinerU 的 pipeline / hybrid / VLM 后端跑在昇腾 NPU 上,输出 Markdown/JSON,接 RAG/Agent
一、昇腾部署核心思路

MinerU 原生以 CUDA 为主,但底层是 PyTorch 推理。
昇腾迁移的本质不是改模型,而是:
用 torch_npu 替换 CUDA 后端 + CANN 算子库 + 设备调度环境变量
架构对照:
|
NVIDIA 栈 |
昇腾栈 |
作用 |
|---|---|---|
|
Driver |
Ascend Driver |
内核驱动 |
|
CUDA |
CANN Toolkit |
算子/图编译 |
|
torch.cuda |
torch_npu |
PyTorch NPU 后端 |
|
vllm |
vllm-ascend |
VLM 推理加速 |
|
nvidia-smi |
npu-smi |
设备监控 |
MinerU 在 NPU 上分两层能力:
- 小模型推理(pipeline):版面/OCR/公式/表格 → torch_npu 直接跑
- VLM 推理(hybrid/vlm):MinerU2.5 系列 1.2B → vllm-ascend 加速
二、环境基线(非常重要)

2.1 硬件与系统
- 服务器:Atlas 800T A2(910B)、Atlas 300I Duo(310P)
- OS:Ubuntu 22.04 / 麒麟 V10 / openEuler 22.03
- 架构:aarch64(推荐)或 x86_64
- NPU:910B3(64G HBM)或 310P(24G)
2.2 软件版本配套(以 910B 为例)
|
组件 |
推荐版本 |
|---|---|
|
Ascend Driver |
25.x(配套 CANN) |
|
CANN |
8.2.rc1 及以上 |
|
Python |
3.11(3.12 需验证 torch_npu 轮子) |
|
PyTorch |
2.7.1 / 2.9.0(必须与 torch_npu 同版本) |
|
torch_npu |
同 PyTorch 小版本严格一致 |
|
vllm-ascend |
0.10.2rc1 / 0.18.x(看 MinerU 版本) |
|
MinerU |
2.5+ / 3.x(hybrid 用 mineru-kit) |
⚠️ 铁律:torch 与 torch_npu 版本号必须一致,否则
libtorch_npu.so符号错误。
三、最稳方案:昇腾官方加速镜像(生产首选)

昇腾社区已提供 MinerU Acceleration Image,基于 vllm-ascend 构建,省掉 90% 依赖地狱。
3.1 镜像选择
昇腾 Hub 镜像(示例):
mineru:0.1.22-ubuntu22.04-py3.11-aarch64
内部已包含:
- CANN Toolkit
- torch_npu
- PyTorch
- vllm-ascend
- mineru_vl_utils
- MinerU 解析流水线
3.2 宿主机准备
宿主机只需装:
- Ascend Driver(提供
/dev/davinci0等设备节点) - docker / containerd
- 模型权重目录
检查 NPU:
npu-smi info
ls /dev/davinci*
3.3 启动容器
docker run -u root -itd --name mineru-npu --network=host \
--device=/dev/davinci_manager \
--device=/dev/hisi_hdc \
--device=/dev/devmm_svm \
--device=/dev/davinci0 \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
-v /usr/local/sbin:/usr/local/sbin:ro \
-v /data/models:/data/models \
-v /data/out:/data/out \
mineru:0.1.22-ubuntu22.04-py3.11-aarch64 bash
多卡环境把 davinci0 改成对应卡号,或挂 davinci0,davinci1...
进入容器:
docker exec -it mineru-npu bash
3.4 模型准备
VLM 模型(放本地):
mkdir -p /data/models
# 从 ModelScope 下
export MINERU_MODEL_SOURCE=modelscope
mineru-models-download -s modelscope -m all
或手动放:
/data/models/MinerU2.5-2509-1.2B/
开启加速开关(改模型 config.json):
{
"prune_encoder": true,
"process_single_image": true
}
3.5 环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
export MINERU_DEVICE_MODE=npu
export MINERU_MODEL_SOURCE=local
export MINERU_MODEL_DIR=/root/.cache/mineru_models
export HCCL_OP_EXPANSION_MODE=AIV
export ASCEND_DEVICE_ID=0
export MINERU_SPAWN_DEVICE_LIST=ascend
export LOCAL_API_LAUNCH_MODE=spawn
说明:
spawn模式是昇腾强制项——fork 子进程会死锁 NPU 上下文。
四、Pipeline 后端:先跑通再谈 VLM

4.1 单页测试
mineru -p /data/docs/demo.pdf -o /data/out -b pipeline -d npu
或新 CLI:
mineru-kit parse /data/docs/demo.pdf -o /data/out/demo.md --tier basic
观察点:
- Layout 检测是否出框
- OCR 中文是否识别
- 公式是否转 LaTeX
- 表格是否出 HTML
4.2 批量解析
mineru -p /data/docs -o /data/out -b pipeline -d npu
适合:
- 扫描件合同
- 财报
- 中文论文
- 对精度要求中等、吞吐优先
五、Hybrid / VLM 后端:昇腾加速关键
5.1 后端选择
|
后端 |
NPU 支持 |
说明 |
|---|---|---|
|
pipeline |
✅ 稳 |
小模型 torch_npu |
|
hybrid-engine |
✅ 推荐 |
原生文本 + VLM 补位 |
|
vlm-engine |
✅ 需 vllm-ascend |
整页视觉理解 |
|
vlm-sglang |
❌ 昇腾支持弱 |
优先用 vllm-ascend |
5.2 启动 hybrid(标准生产)
mineru-kit parse /data/docs/paper.pdf \
-o /data/out/paper.md \
--tier standard
等价于:
- 有文本层:直接抽
- 扫描区:OCR
- 公式/表格:专用模型
- 复杂区:VLM(NPU 加速)
5.3 启动 API 服务
mineru-kit api-server \
--host 0.0.0.0 \
--port 8000 \
--tier standard \
--concurrency 2 \
--preload-models
调用:
curl -X POST http://localhost:8000/file_parse \
-F "files=@demo.pdf" \
-F "return_md=true"
六、源码部署(自定义开发/打补丁)
适合你要改:
- 模型路由逻辑
- 公式后处理
- 表格 HTML 清洗
- MCP Server 内嵌
6.1 基础容器(不用加速镜像也行)
用 quay.io/ascend/vllm-ascend:v0.11.0 或 v0.10.2rc1 作底包:
FROM quay.io/ascend/vllm-ascend:v0.10.2rc1
RUN apt update && apt install -y \
git python3.11-venv build-essential libgl1 poppler-utils
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH=/opt/venv/bin:$PATH
RUN pip install -U pip uv
# 先确认 torch_npu 已存在
python -c "import torch_npu; print('npu ok')"
# 装 mineru 源码
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]
6.2 关键适配点
MinerU 新版本已支持:
device = "npu" if MINERU_DEVICE_MODE == "npu" else "cuda"
x = x.to(device)
源码里如果看到 torch.cuda:
torch.cuda.is_available()→ 改成torch.npu.is_available()判断封装.cuda()→.npu()torch.device("cuda")→torch.device("npu")
但优先用环境变量,别大面积改代码:
export MINERU_DEVICE_MODE=npu
6.3 验证 NPU 生效
import torch, torch_npu
x = torch.randn(2,2).npu()
print(x.mm(x))
再跑:
mineru-gradio --device npu --server-name 0.0.0.0 --server-port 7860
七、多卡与并发部署
7.1 单卡配置(910B 64G)
export ASCEND_DEVICE_ID=0
mineru-kit api-server --concurrency 2 --tier standard
7.2 多卡 router
mineru-router \
--workers 2 \
--gpu-ids 0,1 \
--port 8000
(MinerU 把 NPU 抽象成设备列表,router 按卡调度)
7.3 并发参数
export MINERU_API_MAX_CONCURRENT_REQUESTS=12
export MINERU_HYBRID_BATCH_RATIO=16
export MINERU_PDF_RENDER_THREADS=8
八、OOM 与性能调优(昇腾真实坑)
8.1 NPU OOM 碎片化
现象:
NPU out of memory. Tried to allocate 54.00 MiB
910B 有 64G,但碎片导致分配失败。
解决:
- 降低并发
--concurrency 1
- 减小 batch / window
export MINERU_HYBRID_BATCH_RATIO=8
- 强制 spawn(必须)
export LOCAL_API_LAUNCH_MODE=spawn
- 每次任务后清缓存(代码层)
import torch
torch.npu.empty_cache()
8.2 精度模式
export INFER_PRECISION=bf16
# 或
export INFER_PRECISION=fp16
VLM 推理建议 bf16(910B 支持好)。
8.3 渲染线程
PDF 渲染是 CPU 密集:
export MINERU_PDF_RENDER_THREADS=8
别把 NPU 卡等渲染上。
九、信创场景:麒麟 V10 + 910B
9.1 系统依赖
yum install -y \
python3.11 python3.11-devel \
libglvnd-glx mesa-libGL \
poppler-utils
9.2 模型离线
export MINERU_MODEL_SOURCE=local
export MINERU_MODEL_DIR=/data/models/mineru
模型提前拷好:
/data/models/mineru/
├── pipeline/
├── vlm/MinerU2.5-Pro-2604-1.2B/
└── formula/
9.3 关遥测
export MINERU_TELEMETRY_DISABLED=1
9.4 权限
- NPU 设备节点给运行用户
- 不要用 root 跑业务进程(容器里可 root,宿主机建议普通用户加组)
十、Docker Compose 生产模板
version: "3.8"
services:
mineru:
image: mineru:0.1.22-ubuntu22.04-py3.11-aarch64
network_mode: host
ipc: host
shm_size: 32g
environment:
- MINERU_DEVICE_MODE=npu
- MINERU_MODEL_SOURCE=local
- MINERU_MODEL_DIR=/data/models/mineru
- ASCEND_DEVICE_ID=0
- LOCAL_API_LAUNCH_MODE=spawn
- MINERU_API_MAX_CONCURRENT_REQUESTS=8
volumes:
- /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro
- /data/models:/data/models
- /data/out:/data/out
devices:
- /dev/davinci0
command: >
mineru-kit api-server
--host 0.0.0.0
--port 8000
--tier standard
--concurrency 2
--preload-models
十一、API 接入 RAG / Agent

11.1 解析结果结构
{
"md_content": "# 标题\n\n正文",
"content_list": [
{"type": "text", "content": "..."},
{"type": "table", "html": "<table>..."},
{"type": "equation", "latex": "E=mc^2"}
]
}
11.2 MCP 封装伪代码
def parse_document(file_path: str):
r = requests.post("http://mineru:8000/file_parse",
files={"files": open(file_path, "rb")},
data={"return_md": True})
data = r.json()["results"]["xxx"]
return {
"markdown": data["md_content"],
"blocks": data["content_list"]
}
Agent 侧:
- 正文 → 向量
- 表格 → JSON/图检索
- 公式 → LaTeX 摘要
十二、部署检查清单
跑通标准
- [ ]
npu-smi info能看到卡 - [ ]
import torch_npu成功 - [ ] pipeline 后端出 Markdown
- [ ] hybrid 后端 VLM 走 NPU(不是 CPU 兜底)
- [ ] API
/health正常 - [ ] 100 页 PDF 不 OOM
- [ ] 模型全部本地化(离线环境)
性能基线(910B 单卡参考)
|
场景 |
吞吐 |
|---|---|
|
pipeline 扫描件 |
3~6 页/秒 |
|
hybrid standard |
1~3 页/秒 |
|
vlm 高精度 |
0.5~1.5 页/秒 |
(受页数复杂度、表格/公式密度影响)
十三、常见报错速查
1. libascendcl.so: cannot open shared object
source /usr/local/Ascend/ascend-toolkit/set_env.sh
ldconfig
2. undefined symbol in libtorch_npu.so
torch 与 torch_npu 版本不一致,重装同版本。
3. fork: NPU context error
必须:
export LOCAL_API_LAUNCH_MODE=spawn
4. VLM 跑 CPU 不跑 NPU
- 没设
MINERU_DEVICE_MODE=npu - vllm-ascend 没装
- 模型 config 没开加速字段
5. 模型下不下来
export MINERU_MODEL_SOURCE=modelscope
# 或离线拷模型到 MINERU_MODEL_DIR
十四、总结:昇腾部署推荐路径

别从裸机 pip 起步,先走加速镜像。
生产推荐顺序:
- 昇腾加速镜像起容器
- pipeline 后端先验证小模型 NPU 推理
- 切 hybrid-standard 跑业务
- API + router 多卡
- 离线模型 + 本地源 + 关遥测
- 接 RAG / MCP
一句话:
MinerU 上昇腾,不是“移植模型”,是“把 PyTorch 后端从 CUDA 切到 NPU + 把 VLM 推理切到 vllm-ascend”。
部署路径已经明确,接下来可以把落地环节继续做深:
更多推荐




所有评论(0)