MinerU 海光 DCU 加速卡部署实践：构建 vLLM 镜像、启动容器与解析后端选择指南
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
本文围绕 MinerU 官方仓库中的海光（Hygon）加速卡适配文档（docs/zh/usage/acceleration_cards/Hygon.md）展开，讲解如何在海光 DCU（Deep Computing Unit）平台上通过 Docker 部署 MinerU：包括使用仓库内置的dcu.Dockerfile构建 vLLM 推理镜像、带 DCU 设备直通参数启动容器、在容器内选择 pipeline / vlm / hybrid 等解析后端运行服务，以及用hy-smi监控与指定空闲加速卡的操作方法。读完本文，你可以完整复现一套在海光 DCU 上稳定运行 MinerU 命令行工具、FastAPI 服务与 Gradio WebUI 的部署方案。
1. 支持范围总览：哪些运行形态可以在 DCU 上使用
在开始部署之前，先确认 MinerU 对 Hygon DCU 的支持面。官方文档以矩阵形式给出了“使用场景 × 容器环境（vLLM）”下的支持情况，当前版本中各组合均为 🟢（支持，运行较稳定，精度与 Nvidia GPU 基本一致）：
| 使用场景 | 解析后端 | DCU（容器 + vLLM）支持情况 |
|---|---|---|
命令行工具（mineru） | pipeline | 🟢 |
命令行工具（mineru） | <vlm/hybrid>-engine | 🟢 |
命令行工具（mineru） | <vlm/hybrid>-http-client | 🟢 |
FastAPI 服务（mineru-api） | pipeline | 🟢 |
FastAPI 服务（mineru-api） | <vlm/hybrid>-engine | 🟢 |
FastAPI 服务（mineru-api） | <vlm/hybrid>-http-client | 🟢 |
Gradio 界面（mineru-gradio） | pipeline | 🟢 |
Gradio 界面（mineru-gradio） | <vlm/hybrid>-engine | 🟢 |
Gradio 界面（mineru-gradio） | <vlm/hybrid>-http-client | 🟢 |
OpenAI 兼容服务（mineru-openai-server） | — | 🟢 |
图例含义：🟢 表示支持、运行较稳定，精度与 Nvidia GPU 基本一致；🟡 表示支持但较不稳定，某些场景下可能出现异常或精度存在一定差异；🔴 表示不支持、无法运行或精度存在较大差异。
其中<vlm/hybrid>是占位写法，对应源码 mineru/cli/backend_options.py 中定义的五种后端常量：pipeline、vlm-engine、hybrid-engine、vlm-http-client、hybrid-http-client。也就是说，上表中vlm-engine与hybrid-engine表示 VLM 推理引擎在本机进程内运行，而vlm-http-client与hybrid-http-client则是轻量远程 client，通过 HTTP 连接一个独立运行的 OpenAI 兼容服务器（即mineru-openai-server）。这一点决定了后文两种部署形态：单机 all-in-one 容器与client/server 分离部署。
2. 测试平台基线
官方文档给出的验证环境如下，可作为你自查宿主机环境是否对齐的基线：
os: Ubuntu 22.04.3 LTS cpu: Hygon C86-4G(x86-64) dcu: BW200 driver: 6.3.13-V1.12.0a docker: 20.10.24需要注意两点适用前提：其一，DCU 走的是类 AMD ROCm/HIP 的软硬件栈（DTK 工具链），因此本文方案不适用于其他品牌的加速卡（昇腾、昆仑芯、摩尔线程等），那些平台需参考 docs/zh/usage/acceleration_cards/ 目录下各自的适配文档；其二，仓库内 docker/compose.yaml 提供的编排模板面向 Nvidia GPU（使用driver: nvidia设备预留），不能直接用于 DCU，DCU 部署应以下文docker run设备直通方式为准。
3. 环境准备：用仓库内置 Dockerfile 构建 DCU 镜像
官方推荐的镜像构建方式为直接拉取仓库中的 DCU 专用 Dockerfile 并构建：
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/dcu.Dockerfile docker build --network=host -t mineru:dcu-vllm-latest -f dcu.Dockerfile .构建完成后可用docker images | grep mineru:dcu-vllm-latest验证镜像是否就绪。
3.1 镜像内部都做了什么
逐行阅读仓库内的 docker/china/dcu.Dockerfile，可以清楚这个镜像的四层构成：
- vLLM 推理底座：基于
harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.9.2-ubuntu22.04-dtk25.04.2-1226-das1.7-py3.10-20251226基础镜像，内含 vLLM 0.9.2、DTK 25.04.2、DAS 1.7 与 Python 3.10 的完整海光软件栈，要求 amd64（x86-64）CPU + Hygon DCU。这正是支持矩阵中“容器环境 = vllm”的来源——<vlm/hybrid>-engine与mineru-openai-server依赖的 vLLM 运行时已在基础镜像内完成对 DTK 的适配。 - 中文字体：安装
fonts-noto-core、fonts-noto-cjk与fontconfig并刷新字体缓存。MinerU 的渲染/输出链路（如 HTML/图片类内容的中文显示）依赖系统字体，缺字体会导致中文渲染为方块。 - MinerU 本体：通过阿里云 PyPI 镜像安装
mineru[gradio]>=3.4.0及ftfy、shapely、pyclipper、omegaconf、固定版本的numpy==1.25.0、opencv-python==4.11.0.86等运行依赖，并清理 pip 缓存以缩小镜像体积。 - 模型预下载 + 本地模型源入口：构建阶段即执行
mineru-models-download -s modelscope -m all，把全部模型下载到镜像内；最后将ENTRYPOINT设置为export MINERU_MODEL_SOURCE=local && exec "$@"，保证容器内所有 MinerU 命令默认走本地模型目录，无需联网拉模型。
关于MINERU_MODEL_SOURCE的语义可以参见 docs/zh/usage/model_source.md：取值支持huggingface、modelscope、local，环境变量优先级高于mineru.json中的model-source字段。DCU 镜像选择在构建期预置模型并强制local，本质上是把“模型获取”从运行时前移到构建期，使离线环境也能开箱即用。
4. 启动 Docker 容器：设备直通参数逐项解读
进入交互式终端的官方启动命令如下（引自 Hygon.md）：
docker run -u root --name mineru_docker \ --network=host \ --ipc=host \ --shm-size=16G \ --device=/dev/kfd \ --device=/dev/mkfd \ --device=/dev/dri \ -v /opt/hyhal:/opt/hyhal \ --group-add video \ --cap-add=SYS_PTRACE \ --security-opt seccomp=unconfined \ -e MINERU_MODEL_SOURCE=local \ -it mineru:dcu-vllm-latest \ /bin/bash各参数在海光 DCU 场景下的作用如下：
| 参数 | 作用 |
|---|---|
--device=/dev/kfd | 直通 KFD（Kernel Driver）设备节点，是用户态程序通过 HSA/HIP 运行时访问 DCU 的核心通道 |
--device=/dev/mkfd | 海光驱动特有的设备节点（DCU 栈中的补充通道） |
--device=/dev/dri | 直通 DRM 渲染/显存管理节点，部分显存分配路径依赖它 |
-v /opt/hyhal:/opt/hyhal | 挂载宿主机海光 HAL（硬件抽象层）库目录，使容器内的 DTK 运行时能调用宿主机驱动 |
--shm-size=16G | 扩大共享内存，满足多进程推理（如 vLLM 的 TP 多进程）对共享内存的需求 |
--ipc=host/--network=host | 与宿主机共享 IPC 与网络命名空间，简化服务端口暴露与共享内存通信 |
--group-add video | 让容器进程加入宿主机 video 组，获得/dev/dri的读写权限（配合-u root使用） |
--cap-add=SYS_PTRACE/--security-opt seccomp=unconfined | 放宽安全限制，允许推理框架的调试/性能分析调用与必要的系统调用 |
-e MINERU_MODEL_SOURCE=local | 与镜像 ENTRYPOINT 双重保险，确保运行期一律使用镜像内预置的本地模型 |
执行该命令后你会进入容器的交互式终端，可以直接运行 MinerU 相关命令。若不需要交互，把末尾的/bin/bash替换为服务启动命令（如mineru-api、mineru-gradio、mineru-openai-server及其参数）即可一步拉起服务，命令形态与 docs/zh/usage/quick_usage.md 中“通过 api、webui、http-client/server 进阶使用”一节保持一致。
5. 容器内使用 MinerU：三种典型形态
5.1 命令行解析
最基本的用法与平台无关：
mineru -p <input_path> -o <output_path>其中<input_path>可以是本地 PDF/图片/DOCX/PPTX/XLSX 文件或目录，<output_path>为输出目录。通过-b参数选择解析后端即可切换 pipeline 与 VLM 形态，例如：
# pipeline 后端（纯传统模型链路，无需 vLLM） mineru -p ./demo/pdfs/demo1.pdf -o ./output -b pipeline # hybrid-engine 后端（本容器内 vLLM 引擎，DCU 上为 🟢 支持） mineru -p ./demo/pdfs/demo1.pdf -o ./output -b hybrid-engine5.2 服务化部署：mineru-api 与 mineru-gradio
- FastAPI 服务：
mineru-api --host 0.0.0.0 --port 8000浏览器访问http://127.0.0.1:8000/docs查看 API 文档；健康检查为GET /health，异步提交POST /tasks、同步解析POST /file_parse，详见 docs/zh/usage/quick_usage.md。
- Gradio WebUI：
mineru-gradio --server-name 0.0.0.0 --server-port 7860访问http://127.0.0.1:7860使用可视化前端。
5.3 OpenAI 兼容服务器 + http-client 分离部署
支持矩阵中mineru-openai-server为 🟢，意味着可以走 client/server 分离形态：
# 终端一：启动 OpenAI 兼容服务器（需要镜像内的 vLLM 环境） mineru-openai-server --port 30000 # 终端二：轻量远程 client 连接 mineru -p <input_path> -o <output_path> -b hybrid-http-client -u http://127.0.0.1:30000vlm-http-client是轻量远程 client，用法上不要求本地安装torch；hybrid-http-client则要求本地具备mineru[pipeline]及torch等 pipeline 依赖。在 DCU 容器内两者依赖均已随镜像就绪。
从源码结构看，mineru-openai-server的启动入口 mineru/model/vlm/vllm_server.py 本质上是对 vLLM CLI 的封装：自动补全默认--port 30000、默认--gpu-memory-utilization（未显式指定时由set_default_gpu_memory_utilization()计算）、自动解析本地 vlm 模型路径（auto_download_and_get_model_root_path），并在需要时注入 MinerU 自定义的--logits-processors mineru_vl_utils:MinerULogitsProcessor，最终调用vllm serve。这也解释了为什么所有 vLLM/lmdeploy 官方支持的参数都能透传给mineru、mineru-api、mineru-gradio、mineru-router等命令——常见参数的整理见 docs/zh/usage/advanced_cli_parameters.md。另外该入口还会在OMP_NUM_THREADS未设置时将其置为1，避免推理服务与宿主 CPU 线程竞争，在多 DCU 混布时是一个值得留意的细节。
6. 加速卡指定与监控
官方文档给出两条针对 Hygon 平台的运维提示：
- 监控：在 Hygon 平台可以通过
hy-smi命令查看加速卡的占用、显存与温度使用情况，启动服务前先确认目标卡空闲，避免多服务互相争抢。 - 指定可见卡：DCU 指定可用加速卡的方式与 AMD GPU（ROCm）类似，即通过 GPU isolation 环境变量（ROCm 体系中的
HSA_VISIBLE_DEVICES类机制）限定进程可见的设备集合。建议在容器启动或运行 MinerU 命令前，结合hy-smi输出的空闲卡 ID 设置该环境变量，从而把 MinerU 固定在指定 DCU 上运行。
由于 DCU 驱动栈与 AMD ROCm 同源，社区在 ROCm 隔离文档中介绍的可见设备控制思路在此同样适用（具体变量名以你所用 DTK/驱动版本官方文档为准）。
7. 小结与适用前提
- 本文方案完全基于仓库 docker/china/dcu.Dockerfile 与 docs/zh/usage/acceleration_cards/Hygon.md，覆盖从镜像构建、容器设备直通、后端选型到多服务形态部署的全流程；
- 适用前提为 Ubuntu 系宿主机 + amd64 CPU + Hygon DCU（文档验证平台为 BW200 + DTK 25.04.2 + vLLM 0.9.2），镜像内的模型版本与 MinerU 版本以构建时的
mineru[gradio]>=3.4.0与预置模型为准； - 支持矩阵、
🟢/🟡/🔴结论均以官方文档当前版本为准，不同驱动/DTK 版本下如有差异，请以hy-smi实测与文档后续更新为准； - 如需扩展功能（如 LaTeX 分隔符、LLM 辅助标题分级、自定义本地模型目录），可在容器内用户目录维护
mineru.json，配置模板参见 mineru.template.json。
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
