适用: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

内核驱动 /dev/davinci*

CUDA

CANN Toolkit

算子/图编译

torch.cuda

torch_npu

PyTorch NPU 后端

vllm

vllm-ascend

VLM 推理加速

nvidia-smi

npu-smi

设备监控

MinerU 在 NPU 上分两层能力:

  1. 小模型推理(pipeline):版面/OCR/公式/表格 → torch_npu 直接跑
  2. 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,但碎片导致分配失败。

解决:

  1. 降低并发
--concurrency 1
  1. 减小 batch / window
export MINERU_HYBRID_BATCH_RATIO=8
  1. 强制 spawn(必须)
export LOCAL_API_LAUNCH_MODE=spawn
  1. 每次任务后清缓存(代码层)
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 起步,先走加速镜像。

生产推荐顺序:

  1. 昇腾加速镜像起容器
  2. pipeline 后端先验证小模型 NPU 推理
  3. 切 hybrid-standard 跑业务
  4. API + router 多卡
  5. 离线模型 + 本地源 + 关遥测
  6. 接 RAG / MCP

一句话:

MinerU 上昇腾,不是“移植模型”,是“把 PyTorch 后端从 CUDA 切到 NPU + 把 VLM 推理切到 vllm-ascend”。


部署路径已经明确,接下来可以把落地环节继续做深:

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐