企业官网建设流程全解析

MinerU 在沐曦（METAX）MACA 加速卡上的部署实战：vllm/lmdeploy 双引擎镜像构建与容器启动

【免费下载链接】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 仓库中面向沐曦（METAX）加速卡的官方部署文档为核心，系统讲解如何在 MACA 平台上构建 MinerU 推理镜像、启动 Docker 容器并指定加速卡设备，并结合仓库源码剖析 MinerU 识别maca设备的底层机制（引擎自动选择、lmdeploy 后端强制为 pytorch、cudnn 禁用等），帮助你在国产算力上稳定运行 pipeline、vlm/hybrid 与 openai-server 全场景。

1. 测试平台与适用前提

官方文档给出的验证环境如下，搭建前请先确认你的物理机满足同样的前提（amd64/x86-64 CPU + METAX GPU + 宿主机已安装 MACA 驱动）：

os: Ubuntu 22.04 cpu: INTEL x86_64 gpu: C500 driver: 2.1.2.13 docker: 28.1.1

说明：MinerU 对 MACA 加速卡的支持自 docs/reference/changelog.md 中记录起，与昇腾（npu）、平头哥（ppu）同属“国产算力平台适配”能力，覆盖pipeline与vlm两类后端，并支持vllm/lmdeploy引擎加速 VLM 推理。

2. 准备基础推理镜像

MACA 加速卡支持使用vllm或lmdeploy进行 VLM 模型推理加速，请根据实际需求选择安装和使用其中一个。两个引擎对应的官方基础镜像均可在 METAX 官方镜像仓库（SoftNova 镜像站）中获取：选择AI分类、软件包类型选择vllm、操作系统选择ubuntu，找到对应 amd64 镜像后复制拉取命令在本地终端执行。

两个引擎对应的基础镜像 tag 与 docker/china/maca.Dockerfile 中的 FROM 行严格一致：

可以对照仓库 Dockerfile 的注释确认二者地位：docker/china/maca.Dockerfile 第 3 行是 vllm 基础镜像的FROM，第 5-6 行是被注释掉的 lmdeploy 基础镜像与ARG BACKEND=lmdeploy。

3. 构建 MinerU 镜像

仓库中已内置 docker/china/maca.Dockerfile，直接从仓库获取该文件（克隆仓库或从仓库下载均可）后即可构建。

3.1 构建 vllm 版镜像

docker build --network=host -t mineru:maca-vllm-latest -f maca.Dockerfile .

3.2 构建 lmdeploy 版镜像

# 将基础镜像从 vllm 切换为 lmdeploy sed -i '3s/^/# /' maca.Dockerfile && sed -i '5,6s/^# //' maca.Dockerfile docker build --network=host -t mineru:maca-lmdeploy-latest -f maca.Dockerfile .

两条sed命令的作用与 Dockerfile 结构一一对应：把第 3 行的 vllmFROM注释掉，同时取消第 5-6 行 lmdeployFROM与BACKEND参数的注释，等价于手动编辑 Dockerfile 切换基础镜像。

3.3 Dockerfile 内部做了什么

结合 docker/china/maca.Dockerfile 源码，构建过程实际完成了 5 件事：

1. 系统依赖（第 8-17 行）：安装fonts-noto-core、fonts-noto-cjk、fontconfig、libgl1并执行fc-cache，前者为 OpenCV 提供 libgl 支持，Noto 中文字体保证 PDF 渲染与 bbox 可视化时中文不丢失；
2. torchvision 版本修正（第 19-21 行）：把基础镜像里torchvision-0.15.1+metax3.1.0.4的 dist-info METADATA 版本号改写为0.21.0+metax3.1.0.4，以与 metax 版 torch 2.6 的版本约束兼容——这是 MACA 平台特有的适配步骤；
3. 安装 MinerU（第 23-32 行）：pip install 'mineru[core]>=3.4.0' numpy==1.26.4 opencv-python==4.11.0.86；当BACKEND=lmdeploy时额外安装qwen-vl-utils>=0.0.14,<1（lmdeploy 的 VL 推理需要）；
4. 预下载全部模型（第 35 行）：mineru-models-download -s modelscope -m all，从 ModelScope 下载 pipeline + vlm 全量模型，运行时不再依赖 HuggingFace 网络；
5. 入口点（第 38 行）：ENTRYPOINT自动导出MINERU_MODEL_SOURCE=local后再执行容器内命令，因此容器默认走本地模型，无需再手动设置模型源。

4. 启动 Docker 容器

docker run --ipc host \ --cap-add SYS_PTRACE \ --privileged=true \ --device=/dev/mem \ --device=/dev/dri \ --device=/dev/mxcd \ --device=/dev/infiniband \ --group-add video \ --network=host \ --shm-size '100gb' \ --ulimit memlock=-1 \ --security-opt seccomp=unconfined \ --security-opt apparmor=unconfined \ --name mineru_docker \ -v /datapool:/datapool \ -e MINERU_MODEL_SOURCE=local \ -e MINERU_LMDEPLOY_DEVICE=maca \ -it mineru:maca-vllm-latest \ /bin/bash

关键参数说明：

镜像选择：请根据实际情况选择使用 vllm 或 lmdeploy 版本的镜像；如需使用 lmdeploy，把命令中的mineru:maca-vllm-latest替换为mineru:maca-lmdeploy-latest即可。

执行该命令后将进入 Docker 容器的交互式终端，可直接运行mineru等命令进行解析。也可以把末尾的/bin/bash替换为服务启动命令直接拉起 MinerU 服务，例如mineru-api --host 0.0.0.0 --port 8000、mineru-gradio --server-name 0.0.0.0 --server-port 7860或mineru-openai-server --port 30000，完整说明见 通过命令启动服务。

5. 源码级原理：MinerU 如何识别 maca 设备

MINERU_LMDEPLOY_DEVICE=maca并非摆设，仓库源码中有三处直接消费该变量/设备类型的逻辑：

1. lmdeploy 后端强制为 pytorch。mineru/backend/vlm/utils.py 中set_lmdeploy_backend()明确将ascend、maca、camb三类国产设备统一映射到pytorch后端（turbomind 仅用于 CUDA 场景）：

   def set_lmdeploy_backend(device_type: str) -> str: if device_type.lower() in ["ascend", "maca", "camb"]: lmdeploy_backend = "pytorch"

2. 设备类型白名单校验与参数拼装。mineru/model/vlm/lmdeploy_server.py（mineru-openai-server的 lmdeploy 入口）从环境变量读取设备类型，非法值直接抛ValueError，最终把--device maca --backend pytorch拼进lmdeploy serve api_server启动参数；mineru/backend/vlm/vlm_analyze.py 中lmdeploy-engine的进程内引擎路径执行同样的白名单校验（cuda/ascend/maca/camb）与后端选择。

3. 禁用 cudnn。mineru/cli/common.py 在 CLI 入口处对 MACA 环境做了 torch 级别的兜底：

   if os.getenv("MINERU_LMDEPLOY_DEVICE", "") == "maca": import torch torch.backends.cudnn.enabled = False

   这是 MACA 平台上的专属处理，可避免部分算子在 MACA 版 torch 2.6 上走 cudnn 路径产生异常。

此外，引擎的自动选择由 mineru/utils/engine_utils.py 完成：Linux 环境下优先尝试import vllm（成功则用vllm/vllm-async），否则回退lmdeploy，最后回退transformers。因此 vllm 版镜像中-b vlm-engine会走 vLLM 路径，lmdeploy 版镜像则自动落到 lmdeploy 路径，无需手工指定引擎；mineru-openai-server的 openai_server 入口 也采用相同的auto探测逻辑。

6. 支持情况矩阵

不同环境下 MinerU 对 MACA 加速卡的支持情况（引自官方文档，均为 🟢 支持）：

图例：🟢 支持，运行较稳定，精度与 NVIDIA GPU 基本一致；🟡 支持但较不稳定，某些场景可能出现异常或精度存在一定差异；🟴 不支持，无法运行或精度存在较大差异。

7. 指定加速卡与运行监控

• 指定可用加速卡：MACA 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似，在命令前加CUDA_VISIBLE_DEVICES环境变量即可，例如CUDA_VISIBLE_DEVICES=1 mineru -p <input_path> -o <output_path>；更多用法（含mineru-openai-server多卡分端口、mineru-router聚合多卡）见 命令行进阶参数 的 “CUDA_VISIBLE_DEVICES” 章节；
• 监控与排障：在 METAX 平台通过mx-smi命令查看加速卡使用情况（显存、占用率），并据此指定空闲的加速卡 ID，避免多容器/多进程资源冲突。

8. 小结

在沐曦 MACA 平台上使用 MinerU 的完整路径是：从 METAX 官方镜像仓库获取 vllm 或 lmdeploy 基础镜像 → 用仓库内的 docker/china/maca.Dockerfile 构建mineru:maca-vllm-latest或mineru:maca-lmdeploy-latest（lmdeploy 版仅需两条sed命令切换基础镜像）→ 以挂载/dev/mxcd等设备节点、设置MINERU_MODEL_SOURCE=local与MINERU_LMDEPLOY_DEVICE=maca的参数启动容器 → 通过CUDA_VISIBLE_DEVICES与mx-smi管理设备。源码层面，MinerU 通过 lmdeploy 后端映射、设备白名单校验和 cudnn 禁用三处 MACA 专属逻辑（见第 5 节所列文件）保证了两个推理引擎在 MACA 卡上的开箱可用。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU