MinerU 在沐曦METAXMACA 加速卡上的部署实战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 行严格一致推理引擎基础镜像 tagvllmmaca.ai3.1.0.7-torch2.6-py310-ubuntu22.04-amd64来自 metax 官方仓库public-ai-release/maca/vllmlmdeploymaca.ai3.1.0.7-torch2.6-py310-ubuntu22.04-lmdeploy0.10.2-amd64来自 OpenDataLab 个人容器仓库可以对照仓库 Dockerfile 的注释确认二者地位docker/china/maca.Dockerfile 第 3 行是 vllm 基础镜像的FROM第 5-6 行是被注释掉的 lmdeploy 基础镜像与ARG BACKENDlmdeploy。3. 构建 MinerU 镜像仓库中已内置 docker/china/maca.Dockerfile直接从仓库获取该文件克隆仓库或从仓库下载均可后即可构建。3.1 构建 vllm 版镜像docker build --networkhost -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 --networkhost -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 件事系统依赖第 8-17 行安装fonts-noto-core、fonts-noto-cjk、fontconfig、libgl1并执行fc-cache前者为 OpenCV 提供 libgl 支持Noto 中文字体保证 PDF 渲染与 bbox 可视化时中文不丢失torchvision 版本修正第 19-21 行把基础镜像里torchvision-0.15.1metax3.1.0.4的 dist-info METADATA 版本号改写为0.21.0metax3.1.0.4以与 metax 版 torch 2.6 的版本约束兼容——这是 MACA 平台特有的适配步骤安装 MinerU第 23-32 行pip install mineru[core]3.4.0 numpy1.26.4 opencv-python4.11.0.86当BACKENDlmdeploy时额外安装qwen-vl-utils0.0.14,1lmdeploy 的 VL 推理需要预下载全部模型第 35 行mineru-models-download -s modelscope -m all从 ModelScope 下载 pipeline vlm 全量模型运行时不再依赖 HuggingFace 网络入口点第 38 行ENTRYPOINT自动导出MINERU_MODEL_SOURCElocal后再执行容器内命令因此容器默认走本地模型无需再手动设置模型源。4. 启动 Docker 容器docker run --ipc host \ --cap-add SYS_PTRACE \ --privilegedtrue \ --device/dev/mem \ --device/dev/dri \ --device/dev/mxcd \ --device/dev/infiniband \ --group-add video \ --networkhost \ --shm-size 100gb \ --ulimit memlock-1 \ --security-opt seccompunconfined \ --security-opt apparmorunconfined \ --name mineru_docker \ -v /datapool:/datapool \ -e MINERU_MODEL_SOURCElocal \ -e MINERU_LMDEPLOY_DEVICEmaca \ -it mineru:maca-vllm-latest \ /bin/bash关键参数说明参数作用--device/dev/mem、--device/dev/dri、--device/dev/mxcd、--device/dev/infiniband挂载 MACA 驱动所需的设备节点/dev/mxcd是沐曦卡的核心设备节点缺少任意一项容器内都探测不到加速卡--privilegedtrueSYS_PTRACEseccompunconfinedapparmorunconfinedMACA 运行时初始化需要的宽松安全配置--shm-size 100gb、--ipc host、--ulimit memlock-1大共享内存与无锁内存满足 VLM 推理时进程间通信与锁内存需求-v /datapool:/datapool挂载宿主机数据盘输入 PDF 与输出结果均落在该目录注意按实际路径替换-e MINERU_MODEL_SOURCElocal使用镜像构建期已下载的本地模型-e MINERU_LMDEPLOY_DEVICEmaca告知 MinerU 的 lmdeploy 栈当前运行在 MACA 设备上详见第 5 节镜像选择请根据实际情况选择使用 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_DEVICEmaca并非摆设仓库源码中有三处直接消费该变量/设备类型的逻辑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设备类型白名单校验与参数拼装。mineru/model/vlm/lmdeploy_server.pymineru-openai-server的 lmdeploy 入口从环境变量读取设备类型非法值直接抛ValueError最终把--device maca --backend pytorch拼进lmdeploy serve api_server启动参数mineru/backend/vlm/vlm_analyze.py 中lmdeploy-engine的进程内引擎路径执行同样的白名单校验cuda/ascend/maca/camb与后端选择。禁用 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 加速卡的支持情况引自官方文档均为 支持使用场景后端容器内 vllm容器内 lmdeploy命令行工具minerupipeline命令行工具mineruvlm/hybrid-engine命令行工具mineruvlm/hybrid-http-clientfastapi 服务mineru-apipipelinefastapi 服务mineru-apivlm/hybrid-enginefastapi 服务mineru-apivlm/hybrid-http-clientgradio 界面mineru-gradiopipelinegradio 界面mineru-gradiovlm/hybrid-enginegradio 界面mineru-gradiovlm/hybrid-http-clientopenai-server 服务mineru-openai-server—图例 支持运行较稳定精度与 NVIDIA GPU 基本一致 支持但较不稳定某些场景可能出现异常或精度存在一定差异 不支持无法运行或精度存在较大差异。7. 指定加速卡与运行监控指定可用加速卡MACA 加速卡指定可用加速卡的方式与 NVIDIA GPU 类似在命令前加CUDA_VISIBLE_DEVICES环境变量即可例如CUDA_VISIBLE_DEVICES1 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-latestlmdeploy 版仅需两条sed命令切换基础镜像→ 以挂载/dev/mxcd等设备节点、设置MINERU_MODEL_SOURCElocal与MINERU_LMDEPLOY_DEVICEmaca的参数启动容器 → 通过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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考