MinerU 部署调研报告：NVIDIA 与海光 DCU 双路径

风险声明

⚠️ 本文为调研报告，未经实测验证。所有命令均来自 MinerU 官方文档（opendatalab/MinerU）、海光开发者社区文档、FlyAIBox/dcu-in-action 实战仓库及对应 GitHub Issues。实际落地前请在目标环境复现，并核对当前最新版本号。

一、MinerU 项目现状

项	值
仓库	github.com/opendatalab/MinerU
当前版本	3.4.0（PyPI，2026-06-18 发布）
Star 数	71k（截至 2026-06-28）
许可	自定义 Apache 2.0（3.1.0 起，原 AGPLv3 替换）
Python	3.10 – 3.13
平台	Linux / Windows（3.10-3.12）/ macOS 14+
文档站	https://opendatalab.github.io/MinerU/

支持的输入格式（3.1 起全格式原生）

PDF（含扫描件自动 OCR）
DOCX（3.0 起原生，无需先转 PDF）
PPTX（3.1 起原生）
XLSX（3.1 起原生）
图片（PNG / JPG / TIFF 等）

解析能力

OCR：内置 PP-OCRv6（3.4 升级），支持 109 种语言
公式 → LaTeX
表格 → HTML（含跨页表格合并）
阅读顺序自动还原（去除页眉页脚脚注）
扫描件检测：自动识别图像型 PDF 并启用 OCR
印章识别、竖排文本、行内公式编号（3.0 pipeline 后端新增）

解析后端（5 种）

后端	准确率（OmniDocBench v1.6）	纯 CPU	显存	适用
pipeline	86.47	✅	4GB	通用，CPU/GPU 都行，扫描件 OCR 强
hybrid-engine（high）	95.39	❌	8GB	高精度
hybrid-engine（medium）	95.26	❌	8GB	3.3 默认，速度快 35-220%
vlm-engine	95.30	❌	8GB	纯 VLM
hybrid-http-client / vlm-http-client	同上	✅	2GB	客户端连 OpenAI 兼容服务

推荐选型：

扫描件多、要稳 → pipeline
综合体验最好 → hybrid-engine medium（默认）
极致精度 → hybrid-engine high 或 vlm-engine

二、NVIDIA GPU 部署路径（标准路径）

2.1 系统要求

GPU：Volta 架构及以后（V100 / T4 / A10 / A100 / RTX 20/30/40/50 系列）
显存：pipeline 4GB / VLM 后端 8GB
内存：≥ 16GB，推荐 32GB+
磁盘：≥ 20GB SSD
CUDA：由 PyTorch wheel 自带（无需单独装 CUDA Toolkit，但需 NVIDIA 驱动 ≥ 525）

2.2 安装方式

方式一：pip/uv 安装（推荐简单场景）

1
2
3

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

mineru[all] 包含所有核心依赖，已自动选择匹配 CUDA 的 PyTorch wheel。

方式二：源码安装

1
2
3

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

方式三：Docker 部署（推荐生产）

# 拉 compose 模板
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/compose.yaml

# 启动 API 服务（FastAPI，8000 端口）
docker compose -f compose.yaml --profile api up -d

# 或者只跑 OpenAI 兼容服务（30000 端口）
docker compose -f compose.yaml --profile openai-server up -d

# 多 GPU 路由（8002 端口）
docker compose -f compose.yaml --profile router up -d

# WebUI（7860 端口）
docker compose -f compose.yaml --profile gradio up -d

镜像需要本地构建（docker build -t mineru:latest），依赖 NVIDIA Container Toolkit。

2.3 模型下载

首次运行会自动从 ModelScope / HuggingFace 下载模型（约几 GB）。可设置 MINERU_MODEL_SOURCE=local 走本地缓存，3.4 起支持自动选择更优源。

2.4 验证

1	mineru -p demo.pdf -o ./output -b pipeline

三、海光 DCU K100 部署路径

3.1 现状

README 顶部将 Hygon 列为受支持的国产 AI 芯片之一
官方文档没有单独章节讲 DCU 部署路径
实际机制：DTK（Deep Computing Toolkit）提供 ROCm/HIP 兼容层，PyTorch 在 DCU 上伪装为 CUDA 设备（torch.cuda.is_available() 返回 True、torch.cuda.0 指 DCU 0）
也就是说：MinerU 代码本身不需要改，只要把 PyTorch 换成海光自家编译的 wheel + 装好 DTK 即可

3.2 系统与硬件要求

项	要求
DCU 型号	K100 / K100-AI / Z100 / Z100L / BW100
操作系统	CentOS 7.6+ / Ubuntu 20.04+ / Anolis / Kylin v10 / openEuler 22.03 / UOS 1021e
DCU 驱动	rock-6.3.8（2026-04 时点）
DTK 版本	DTK 25.04+（与 PyTorch wheel 强绑定，必须匹配）
用户组	非 root 用户必须加入 `gid=39`（render 组）

3.3 部署步骤（物理机 + Docker 两种）

方式 A：Docker 容器化部署（推荐）

# 1. 装 Docker（略）

# 2. 从光源镜像仓库拉取带 DCU 支持的 PyTorch 基础镜像
docker pull image.sourcefind.cn:5000/dcu/admin/base/pytorch:1.10.0-centos7.6-dtk-22.10-py38-latest

# 3. 启动容器（关键参数：DCU 设备 + 用户组 39）
docker run -it \
  --name=mineru-dcu \
  --device=/dev/kfd \
  --device=/dev/dri \
  --security-opt seccomp=unconfined \
  --cap-add=SYS_PTRACE \
  --ipc=host \
  --network host \
  --shm-size=16G \
  --group-add 39 \
  -v /opt/hyhal:/opt/hyhal \
  image.sourcefind.cn:5000/dcu/admin/base/pytorch:1.10.0-centos7.6-dtk-22.10-py38-latest

# 4. 容器内装 MinerU
pip install uv
uv pip install -U "mineru[all]"

# 5. 启动 API 服务
mineru-api --host 0.0.0.0 --port 8000

注意：源码仓库 FlyAIBox/dcu-in-action 给出的示例镜像是 dtk-22.10，实际部署时建议向光源平台申请 dtk-25.04 镜像，与当前 MinerU 3.4 的 PyTorch 2.4+/torch2.9.0 兼容。

方式 B：物理机部署

# 1. 装驱动（rock-*.run，需要重启）
chmod 755 rock*.run && ./rock*.run && reboot

# 2. 加入 render 组
usermod -a -G 39 $USER

# 3. 装依赖
yum install -y epel-release centos-release-scl
yum groupinstall -y "Development tools"
yum install -y cmake hwloc openmpi glog-devel lmdb-devel opencv-devel openblas-devel \
               libibverbs-devel gflags-devel gstreamer1* ...

# 4. 装 DTK（从 hpccube 开发者社区下载 DTK-25.04.tar.gz）
tar -xvf DTK-*.tar.gz -C /opt/
ln -s /opt/dtk-* /opt/dtk

# 5. 写入环境变量
cat > /etc/profile.d/dtk.sh <<'EOF'
export LD_LIBRARY_PATH=/usr/local/lib/:/usr/local/lib64/:$LD_LIBRARY_PATH
export PATH=/usr/local/bin:$PATH
source /opt/dtk/env.sh
EOF
source /etc/profile.d/dtk.sh

# 6. 验证 DTK
rocm-smi
rocminfo | grep gfx   # 应看到 K100 的 gfx90a 或类似代号

# 7. 装海光版 PyTorch wheel（DTK 25.04 对应）
wget https://download.sourcefind.cn:65024/file/4/torch/DAS1.5/torch-2.4.1+das.opt2.dtk2504-cp310-cp310-manylinux_2_28_x86_64.whl
pip install torch-2.4.1+das.opt2.dtk2504-cp310-cp310-manylinux_2_28_x86_64.whl

# 8. 验证 PyTorch + DCU
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
# 应输出 2.4.1+das.opt2.dtk2504 True

# 9. 装 MinerU
pip install uv
uv pip install -U "mineru[all]"

# 10. 启动 API
mineru-api --host 0.0.0.0 --port 8000

3.4 DCU 上 MinerU 的已知坑（来自 issue）

问题	说明	建议
VLM 后端在国产卡上有识别精度退化（issue #4583）	同一 PDF，昇腾 910B 的 vlm-vllm-async-engine 把 `SZL15-1.25-T` 错识别为 `SZE15-1.23-1`	DCU 也可能有同样问题，保守起见生产先用 pipeline 后端，VLM 待官方适配
`pipeline` 后端在国产卡上目前是稳定的	issue #4583 确认昇腾 910B 上 pipeline 解析与官网一致	用 pipeline 起步最稳
国产芯片 OCR 语言选择受限	3.4 移除了日语/繁体/英语/拉丁选项，统一路由到 ch 模型	多语种场景需要确认目标语言支持
torch 版本严格匹配 DTK	DTK 25.04 必须配 `torch-2.4.1+das.opt2.dtk2504-...` wheel	升级 DTK 时同步换 PyTorch wheel
Docker 镜像目前没有官方 DCU 版	官方 compose.yaml 写的是 `driver: nvidia`，DCU 不识别	必须自构建，或用 `image.sourcefind.cn` 上的 dcu pytorch 镜像为基础包

四、API 服务化（满足”提供 HTTP API”要求）

结论：MinerU 自带的 mineru-api（FastAPI）完全够用，无需自写包装。

4.1 启动方式

# 默认 8000 端口
mineru-api --host 0.0.0.0 --port 8000

# 多 GPU 路由（自动负载均衡）
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

# OpenAI 兼容端点（30000 端口，方便接 RAG 工具链）
mineru-openai-server --host 0.0.0.0 --port 30000

4.2 API 端点（来自源码 `mineru/cli/fast_api.py`）

端点	方法	说明
`/file_parse`	POST	同步解析（小文件、即时返回）
`/tasks`	POST	3.0+ 异步任务提交（适合大批量）
`/tasks/{task_id}`	GET	异步任务状态查询
`/tasks/{task_id}/result`	GET	异步任务结果拉取
`/health`	GET	健康检查（compose.yaml 里 healthcheck 就用这个）

请求参数（典型）：

1
2
3

curl -X POST http://localhost:8000/file_parse \
  -F "file=@report.pdf" \
  -F 'options={"backend":"pipeline","lang":"ch"}'

4.3 三种服务选型

服务	端口	适用
`mineru-api`	8000	主用，FastAPI，完整功能
`mineru-openai-server`	30000	接 OpenAI 兼容生态（LangChain / Dify / RAGFlow）
`mineru-router`	8002	多 GPU 统一入口 + 负载均衡（接口与 api 完全兼容）

4.4 多卡并行 / 路由

mineru-router 是 3.0 引入的多机多卡统一入口：

# 本机自动发现所有 DCU/GPU
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto

# 或聚合外部 mineru-api 服务
mineru-router --host 0.0.0.0 --port 8002 \
  --local-gpus none \
  --upstream-url http://api-node-1:8000 \
  --upstream-url http://api-node-2:8000

五、格式与扫描件覆盖核对

要求	MinerU 支持	验证方式
PDF 文本提取	✅	默认 pipeline
PDF 扫描件 OCR	✅	pipeline 自动检测图像型 PDF 并启用 OCR，PP-OCRv6 引擎
图片 OCR（PNG/JPG 等）	✅	直接作为输入
Word（DOCX）	✅（3.0 起原生，无需转 PDF）	直接输入
Excel（XLSX）	✅（3.1 起原生）	直接输入
PPT（PPTX）	✅（3.1 起原生）	直接输入
表格识别	✅ → HTML，含跨页合并	pipeline + hybrid
多语言 OCR	✅ 109 种	设置 `lang` 参数

六、推荐部署方案

方案 A：NVIDIA 单卡/多卡（最稳）

# 装依赖
pip install uv
uv pip install -U "mineru[all]"

# 启动（pipeline 后端，4GB 显存够用）
mineru-api --host 0.0.0.0 --port 8000 --backend pipeline

方案 B：海光 DCU K100 单卡（pipeline 后端）

# 1. 装驱动 + DTK 25.04（参考第三节）
# 2. 装 PyTorch 海光 wheel
pip install torch-2.4.1+das.opt2.dtk2504-cp310-cp310-manylinux_2_28_x86_64.whl
# 3. 装 MinerU（DTK 下 uv pip install 行为不变）
uv pip install -U "mineru[all]"
# 4. 启动
mineru-api --host 0.0.0.0 --port 8000 --backend pipeline

方案 C：混合（NVIDIA + 海光共存）

用 mineru-router 聚合两边：

1
2
3

mineru-router --host 0.0.0.0 --port 8002 \
  --upstream-url http://nvidia-node:8000 \
  --upstream-url http://hygon-node:8000

客户端只对 router 8002，开发不用关心后端跑哪张卡

七、执行清单

立刻可做

✅ API 选 mineru-api（8000 端口）—— 不需要自己写 FastAPI
✅ 后端先用 pipeline —— 4GB 显存即可、支持扫描件 OCR、国产卡上最稳
✅ PDF/Word/Excel/PPT/图片全格式都直接传 —— 3.1 起原生，无需先转 PDF

DCU K100 上线注意

DTK 版本与 PyTorch wheel 必须严格匹配（DTK 25.04 ↔ torch-2.4.1+das.opt2.dtk2504-...）
容器跑要给 --device=/dev/kfd --device=/dev/dri --group-add 39
第一批先跑 pipeline 验证——不要一上来就上 vlm/hybrid
驱动/DTK/wheel 三个东西都从海光官方源拿，不要混用第三方编译版本

长期规划

等 MinerU 官方对国产芯片的 VLM 后端适配完成（issue #4583 已暴露问题）
多卡场景直接上 mineru-router 聚合，不用自己写调度
接 RAG 工具链时用 mineru-openai-server（30000 端口），对接 LangChain / Dify / RAGFlow 都是 OpenAI 兼容协议

八、信息源

MinerU 仓库：https://github.com/opendatalab/MinerU
MinerU 文档站：https://opendatalab.github.io/MinerU/
PyPI mineru 3.4.0：https://pypi.org/project/mineru/
官方 compose.yaml：https://github.com/opendatalab/MinerU/blob/master/docker/compose.yaml
Docker 部署文档：https://opendatalab.github.io/MinerU/quick_start/docker_deployment/
API 端点源码：mineru/cli/fast_api.py（行 1228 / 1276 / 1296 / 1305 / 1352）
DCU 实战仓库：https://github.com/FlyAIBox/dcu-in-action
DTK 安装手册：https://github.com/FlyAIBox/dcu-in-action/blob/main/docs/01-DTK安装.md
海光开发者社区：https://developer.hpccube.com/
光源镜像仓库：https://sourcefind.cn/
Issue #4583：昇腾/NVIDIA 上 VLM 后端识别精度问题
Issue #852：国产 NPU 支持讨论（官方回复将在 1.0 提供 npu 支持，已落地）
MinerU 技术报告 arXiv：2409.18839（v1）/ 2509.22186（v2.5）/ 2604.04771（v2.5 Pro）

附录：调研元信息

调研时间：2026-06-29
信息源：GitHub opendatalab/MinerU README / 源码、官方文档、Pypi、国内 DCU 实战仓库、Issues
后续行动：建议在拿到 DCU K100 物理机或 NVIDIA 测试卡后，按”方案 A/B”实测一遍，将实测结果回填到本文「执行清单」与「风险声明」两节。