MinerU 燧原 Enflame GCU 加速卡部署实战指南从镜像构建到设备识别的完整链路【免费下载链接】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 仓库中的官方加速卡适配文档与配套源码完整讲解 MinerU 在燧原 Enflame GCU 加速卡以 S60 为例上的部署方法包括测试平台信息、GCU 专用 Docker 镜像的构建与容器启动、各入口CLI / FastAPI / Gradio / OpenAI Server的支持情况矩阵以及 MinerU 底层如何识别 GCU 设备、管理显存与调度 vLLM 推理的源码级原理。读完本文你可以直接在 Enflame 平台上复现 MinerU 的部署并理解TOPS_VISIBLE_DEVICES、efsmi等关键操作背后的实现机制。1. 测试平台与硬件环境官方适配指南给出的测试平台信息如下可作为环境基线参考来源docs/zh/usage/acceleration_cards/Enflame.mdos: Ubuntu 22.04.4 LTS cpu: Intel x86-64 gcu: Enflame S60 driver: 1.7.0.9 docker: 28.0.1几点适用前提需要说明该环境组合是官方验证过的参考配置。其他驱动版本TopsRider或 CUDA 兼容模式下镜像内预装的 PyTorch/vLLM 版本可能与驱动不完全匹配建议以官方基础镜像版本为锚点CPU 平台限定为 amd64x86-64。这一点在 Dockerfile 中有明确注释Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU Enflame GCU即非 x86-64 平台不适用该镜像驱动版本 1.7.0.9 与镜像内 TopsRider 运行时共同决定torch.gcu是否可用后文会结合源码说明 MinerU 是如何做这一探测的。2. 使用 Dockerfile 构建 GCU 专用镜像官方提供两条路径构建镜像。其一通过 wget 从仓库拉取 Dockerfile 后本地构建官方指南命令wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/gcu.Dockerfile docker build --networkhost -t mineru:gcu-vllm-latest -f gcu.Dockerfile .其二直接使用仓库内维护的 docker/china/gcu.Dockerfile 构建。下面逐段解析该 Dockerfile它同时揭示了镜像的技术栈构成基础镜像# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU Enflame GCU. FROM crpi-vofi3w62lkohhxsp.cn-shanghai.personal.cr.aliyuncs.com/opendatalab-mineru/gcu:docker_images_topsrider_i3x_3.6.20260106_vllm0.11_pytorch2.8.0从镜像 tag 可以读出完整的软件栈版本信息TopsRider i3x 3.6燧原 GCU 运行时 vLLM 0.11 PyTorch 2.8.0。这意味着 vlm/hybrid 后端的 vLLM 推理能力是在这个基础镜像中预置的构建过程不需要也不适合自行改装 vLLM 的 GCU 适配层。中文字体安装镜像通过阿里云源安装了fonts-noto-core、fonts-noto-cjk与fontconfig并执行fc-cache -fv。这是因为 MinerU 的可视化输出与 PDF 渲染依赖系统字体缺失 CJK 字体会导致中文乱码或缺字。安装 MinerURUN python3 -m pip install mineru[core]3.4.0 \ numpy1.26.4 \ opencv-python4.11.0.86 \ -i https://mirrors.aliyun.com/pypi/simple \ python3 -m pip cache purge安装mineru[core]extra 版本并锁定了 numpy 与 opencv 版本与基础镜像中 TopsRider/PyTorch 编译依赖保持兼容构建时使用国内 PyPI 镜像加速。模型预下载与入口RUN /bin/bash -c mineru-models-download -s modelscope -m all ENTRYPOINT [/bin/bash, -c, export MINERU_MODEL_SOURCElocal exec \$\, --]镜像构建时即通过mineru-models-download -s modelscope -m all下载了全部模型权重而 ENTRYPOINT 自动导出MINERU_MODEL_SOURCElocal使容器默认走本地模型目录而非在线下载——这与后文容器启动命令中-e MINERU_MODEL_SOURCElocal是双重保险确保离线环境也能直接推理。3. 启动 Docker 容器进入容器交互式终端的命令如下docker run -u root --name mineru_docker \ --networkhost \ --ipchost \ --privileged \ -e MINERU_MODEL_SOURCElocal \ -it mineru:gcu-vllm-latest \ /bin/bash各参数作用说明参数作用-u root以 root 身份运行便于容器内管理权限与设备访问--networkhost共享宿主机网络栈vLLM 等服务端口直接暴露于宿主机--ipchost共享宿主机 IPC 命名空间PyTorch 多进程/多卡数据共享需要较大的共享内存该参数可规避默认 IPC 限制--privileged放开设备权限GCU 加速卡的设备节点访问通常依赖该方式直通-e MINERU_MODEL_SOURCElocal明确告知 MinerU 使用本地已下载的模型目录执行命令后即可在容器内直接运行 MinerU 相关命令。如果需要以常驻服务方式启动而非交互式终端官方指南建议直接替换末尾的/bin/bash为服务启动命令如mineru-api、mineru-gradio等入口各入口的具体命令与参数可参考 通过命令启动服务 一节。4. 使用场景支持矩阵不同入口与后端的组合下MinerU 对 Enflame GCU 的支持情况如下容器环境均为 vllm 镜像使用场景后端模式支持状态命令行工具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 基本一致 支持但较不稳定某些场景可能出现异常或精度差异 不支持无法运行或精度差异较大。当前 Enflame GCU 在 vllm 容器环境下全场景 。结合 README 中对国产芯片适配列表Ascend · Cambricon · Enflame · MetaX · Moore Threads · Kunlunxin · Iluvatar · Hygon · Biren · T-Head的说明以及 changelog 中“Added support for the Hygon, Enflame, and Moore Threads domestic computing platforms”的记录可以确认 GCU 适配是 MinerU 官方持续维护的一等公民路径而非实验性支持。5. 源码解析MinerU 如何识别并适配 GCU 设备GCU 支持并非靠外部包装脚本而是内建于 MinerU 的设备抽象层。以下从源码结构看关键实现链路均位于 mineru/utils/config_reader.py 与 mineru/utils/model_utils.py。5.1 设备发现get_device 的探测顺序get_device() 首先读取环境变量MINERU_DEVICE_MODE若显式设置则直接返回否则按以下顺序探测硬件torch.cuda.is_available()→ 返回cudatorch.backends.mps.is_available()→ 返回mpstorch_npu.npu.is_available()→ 返回nputorch.gcu.is_available()→ 返回gcu依次尝试torch.musa、torch.mlu、torch.sdaa全部不可用则回退cpu。这说明在 GCU 机器上只要 TopsRider 提供的 PyTorch 补丁使torch.gcu可用且优先级位于 CUDA/NPU 之后MinerU 无需任何额外配置即可自动落到 GCU 后端同时任何阶段都可用MINERU_DEVICE_MODEgcu强制指定便于排障或资源隔离场景。5.2 显存管理clean_memory 与 get_vram 对 gcu 分支的支持get_vram() 与 clean_memory() 对gcu前缀设备有专门分支elif str(device).startswith(gcu): if torch.gcu.is_available(): total_memory round(torch.gcu.get_device_properties(device).total_memory / (1024 ** 3)) # 转为 GBelif str(device).startswith(gcu): if torch.gcu.is_available(): torch.gcu.empty_cache()get_vram通过torch.gcu.get_device_properties(device).total_memory读取加速卡显存总量GB该值驱动 MinerU 的clean_vram逻辑——当显存小于阈值默认 8GB时自动触发垃圾回收。若自动探测不可靠还可用环境变量MINERU_VIRTUAL_VRAM_SIZE覆盖见 get_vram 实现clean_memory调用torch.gcu.empty_cache()释放缓存块行为与 CUDA 路径对称保证 pipeline 逐页推理时显存可回收。5.3 vLLM 推理路径GCU 按 Compute Capability 8.0 处理MinerU 的 vlm/hybrid 后端在 vLLM 推理时需要判断是否启用 custom logits processors。enable_custom_logits_processors() 中的设备分支如下elif hasattr(torch, gcu) and torch.gcu.is_available(): compute_capability 8.0即源码结构上GCU 与 NPU/MUSA/MLU/SDAA 一样被统一按 Compute Capability 8.0 对待在 vLLM ≥ 0.10.1 且VLLM_USE_V1不为 0 时启用自定义 logits 处理器。这与第 2 节基础镜像中预置的 vLLM 0.11 版本是配套的——版本条件与设备条件同时满足时vlm/hybrid-engine 场景才能稳定达到与 Nvidia GPU 一致的精度表现。6. 指定可用加速卡与查看卡状态多卡机器上为 MinerU 指定可见加速卡的方式与 NVIDIA GPU 的CUDA_VISIBLE_DEVICES机制类似官方指南给出的做法是将环境变量CUDA_VISIBLE_DEVICES替换为TOPS_VISIBLE_DEVICES即可例如在容器启动时追加-e TOPS_VISIBLE_DEVICES0。CUDA_VISIBLE_DEVICES的基本用法与多卡指定细节可参考 高级 CLI 参数 中对应章节。另外在 Enflame 平台上可通过efsmi命令查看加速卡的实时使用情况显存占用、利用率等据此选择空闲卡 ID 再指定给 MinerU 容器避免与同机其他任务产生资源冲突。7. 小结与部署核对清单在 Enflame GCU 上部署 MinerU 的关键路径可以归纳为硬件/驱动x86-64 Enflame GCU如 S60 官方验证过的驱动参考 1.7.0.9Docker ≥ 28.x镜像使用 docker/china/gcu.Dockerfile 构建mineru:gcu-vllm-latest镜像内已含 TopsRider vLLM 0.11 PyTorch 2.8.0 mineru[core] ≥ 3.4.0 全量模型容器--privileged--ipchost--networkhostMINERU_MODEL_SOURCElocal交互式使用或替换为mineru-api/mineru-gradio/mineru-openai-server服务命令排障确认torch.gcu可用MinerU 的 get_device() 依赖它自动识别设备必要时用MINERU_DEVICE_MODEgcu强制指定、TOPS_VISIBLE_DEVICES绑定卡、efsmi检查卡状态后端选择pipeline 与 vlm/hybrid 的 engine、http-client 模式在 vllm 容器下均已获 支持可按精度/延迟需求自由选择。以上流程全部基于当前仓库文档与源码可验证的行为适用前提是使用仓库官方提供的 GCU 基础镜像若自行更换 vLLM 或 PyTorch 版本需重新核对 enable_custom_logits_processors() 中的版本分支条件。【免费下载链接】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），仅供参考 MinerU 燧原 Enflame GCU 加速卡部署实战指南：从镜像构建到设备识别的完整链路
MinerU 燧原 Enflame GCU 加速卡部署实战指南从镜像构建到设备识别的完整链路【免费下载链接】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 仓库中的官方加速卡适配文档与配套源码完整讲解 MinerU 在燧原 Enflame GCU 加速卡以 S60 为例上的部署方法包括测试平台信息、GCU 专用 Docker 镜像的构建与容器启动、各入口CLI / FastAPI / Gradio / OpenAI Server的支持情况矩阵以及 MinerU 底层如何识别 GCU 设备、管理显存与调度 vLLM 推理的源码级原理。读完本文你可以直接在 Enflame 平台上复现 MinerU 的部署并理解TOPS_VISIBLE_DEVICES、efsmi等关键操作背后的实现机制。1. 测试平台与硬件环境官方适配指南给出的测试平台信息如下可作为环境基线参考来源docs/zh/usage/acceleration_cards/Enflame.mdos: Ubuntu 22.04.4 LTS cpu: Intel x86-64 gcu: Enflame S60 driver: 1.7.0.9 docker: 28.0.1几点适用前提需要说明该环境组合是官方验证过的参考配置。其他驱动版本TopsRider或 CUDA 兼容模式下镜像内预装的 PyTorch/vLLM 版本可能与驱动不完全匹配建议以官方基础镜像版本为锚点CPU 平台限定为 amd64x86-64。这一点在 Dockerfile 中有明确注释Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU Enflame GCU即非 x86-64 平台不适用该镜像驱动版本 1.7.0.9 与镜像内 TopsRider 运行时共同决定torch.gcu是否可用后文会结合源码说明 MinerU 是如何做这一探测的。2. 使用 Dockerfile 构建 GCU 专用镜像官方提供两条路径构建镜像。其一通过 wget 从仓库拉取 Dockerfile 后本地构建官方指南命令wget https://gcore.jsdelivr.net/gh/opendatalab/MinerUmaster/docker/china/gcu.Dockerfile docker build --networkhost -t mineru:gcu-vllm-latest -f gcu.Dockerfile .其二直接使用仓库内维护的 docker/china/gcu.Dockerfile 构建。下面逐段解析该 Dockerfile它同时揭示了镜像的技术栈构成基础镜像# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU Enflame GCU. FROM crpi-vofi3w62lkohhxsp.cn-shanghai.personal.cr.aliyuncs.com/opendatalab-mineru/gcu:docker_images_topsrider_i3x_3.6.20260106_vllm0.11_pytorch2.8.0从镜像 tag 可以读出完整的软件栈版本信息TopsRider i3x 3.6燧原 GCU 运行时 vLLM 0.11 PyTorch 2.8.0。这意味着 vlm/hybrid 后端的 vLLM 推理能力是在这个基础镜像中预置的构建过程不需要也不适合自行改装 vLLM 的 GCU 适配层。中文字体安装镜像通过阿里云源安装了fonts-noto-core、fonts-noto-cjk与fontconfig并执行fc-cache -fv。这是因为 MinerU 的可视化输出与 PDF 渲染依赖系统字体缺失 CJK 字体会导致中文乱码或缺字。安装 MinerURUN python3 -m pip install mineru[core]3.4.0 \ numpy1.26.4 \ opencv-python4.11.0.86 \ -i https://mirrors.aliyun.com/pypi/simple \ python3 -m pip cache purge安装mineru[core]extra 版本并锁定了 numpy 与 opencv 版本与基础镜像中 TopsRider/PyTorch 编译依赖保持兼容构建时使用国内 PyPI 镜像加速。模型预下载与入口RUN /bin/bash -c mineru-models-download -s modelscope -m all ENTRYPOINT [/bin/bash, -c, export MINERU_MODEL_SOURCElocal exec \$\, --]镜像构建时即通过mineru-models-download -s modelscope -m all下载了全部模型权重而 ENTRYPOINT 自动导出MINERU_MODEL_SOURCElocal使容器默认走本地模型目录而非在线下载——这与后文容器启动命令中-e MINERU_MODEL_SOURCElocal是双重保险确保离线环境也能直接推理。3. 启动 Docker 容器进入容器交互式终端的命令如下docker run -u root --name mineru_docker \ --networkhost \ --ipchost \ --privileged \ -e MINERU_MODEL_SOURCElocal \ -it mineru:gcu-vllm-latest \ /bin/bash各参数作用说明参数作用-u root以 root 身份运行便于容器内管理权限与设备访问--networkhost共享宿主机网络栈vLLM 等服务端口直接暴露于宿主机--ipchost共享宿主机 IPC 命名空间PyTorch 多进程/多卡数据共享需要较大的共享内存该参数可规避默认 IPC 限制--privileged放开设备权限GCU 加速卡的设备节点访问通常依赖该方式直通-e MINERU_MODEL_SOURCElocal明确告知 MinerU 使用本地已下载的模型目录执行命令后即可在容器内直接运行 MinerU 相关命令。如果需要以常驻服务方式启动而非交互式终端官方指南建议直接替换末尾的/bin/bash为服务启动命令如mineru-api、mineru-gradio等入口各入口的具体命令与参数可参考 通过命令启动服务 一节。4. 使用场景支持矩阵不同入口与后端的组合下MinerU 对 Enflame GCU 的支持情况如下容器环境均为 vllm 镜像使用场景后端模式支持状态命令行工具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 基本一致 支持但较不稳定某些场景可能出现异常或精度差异 不支持无法运行或精度差异较大。当前 Enflame GCU 在 vllm 容器环境下全场景 。结合 README 中对国产芯片适配列表Ascend · Cambricon · Enflame · MetaX · Moore Threads · Kunlunxin · Iluvatar · Hygon · Biren · T-Head的说明以及 changelog 中“Added support for the Hygon, Enflame, and Moore Threads domestic computing platforms”的记录可以确认 GCU 适配是 MinerU 官方持续维护的一等公民路径而非实验性支持。5. 源码解析MinerU 如何识别并适配 GCU 设备GCU 支持并非靠外部包装脚本而是内建于 MinerU 的设备抽象层。以下从源码结构看关键实现链路均位于 mineru/utils/config_reader.py 与 mineru/utils/model_utils.py。5.1 设备发现get_device 的探测顺序get_device() 首先读取环境变量MINERU_DEVICE_MODE若显式设置则直接返回否则按以下顺序探测硬件torch.cuda.is_available()→ 返回cudatorch.backends.mps.is_available()→ 返回mpstorch_npu.npu.is_available()→ 返回nputorch.gcu.is_available()→ 返回gcu依次尝试torch.musa、torch.mlu、torch.sdaa全部不可用则回退cpu。这说明在 GCU 机器上只要 TopsRider 提供的 PyTorch 补丁使torch.gcu可用且优先级位于 CUDA/NPU 之后MinerU 无需任何额外配置即可自动落到 GCU 后端同时任何阶段都可用MINERU_DEVICE_MODEgcu强制指定便于排障或资源隔离场景。5.2 显存管理clean_memory 与 get_vram 对 gcu 分支的支持get_vram() 与 clean_memory() 对gcu前缀设备有专门分支elif str(device).startswith(gcu): if torch.gcu.is_available(): total_memory round(torch.gcu.get_device_properties(device).total_memory / (1024 ** 3)) # 转为 GBelif str(device).startswith(gcu): if torch.gcu.is_available(): torch.gcu.empty_cache()get_vram通过torch.gcu.get_device_properties(device).total_memory读取加速卡显存总量GB该值驱动 MinerU 的clean_vram逻辑——当显存小于阈值默认 8GB时自动触发垃圾回收。若自动探测不可靠还可用环境变量MINERU_VIRTUAL_VRAM_SIZE覆盖见 get_vram 实现clean_memory调用torch.gcu.empty_cache()释放缓存块行为与 CUDA 路径对称保证 pipeline 逐页推理时显存可回收。5.3 vLLM 推理路径GCU 按 Compute Capability 8.0 处理MinerU 的 vlm/hybrid 后端在 vLLM 推理时需要判断是否启用 custom logits processors。enable_custom_logits_processors() 中的设备分支如下elif hasattr(torch, gcu) and torch.gcu.is_available(): compute_capability 8.0即源码结构上GCU 与 NPU/MUSA/MLU/SDAA 一样被统一按 Compute Capability 8.0 对待在 vLLM ≥ 0.10.1 且VLLM_USE_V1不为 0 时启用自定义 logits 处理器。这与第 2 节基础镜像中预置的 vLLM 0.11 版本是配套的——版本条件与设备条件同时满足时vlm/hybrid-engine 场景才能稳定达到与 Nvidia GPU 一致的精度表现。6. 指定可用加速卡与查看卡状态多卡机器上为 MinerU 指定可见加速卡的方式与 NVIDIA GPU 的CUDA_VISIBLE_DEVICES机制类似官方指南给出的做法是将环境变量CUDA_VISIBLE_DEVICES替换为TOPS_VISIBLE_DEVICES即可例如在容器启动时追加-e TOPS_VISIBLE_DEVICES0。CUDA_VISIBLE_DEVICES的基本用法与多卡指定细节可参考 高级 CLI 参数 中对应章节。另外在 Enflame 平台上可通过efsmi命令查看加速卡的实时使用情况显存占用、利用率等据此选择空闲卡 ID 再指定给 MinerU 容器避免与同机其他任务产生资源冲突。7. 小结与部署核对清单在 Enflame GCU 上部署 MinerU 的关键路径可以归纳为硬件/驱动x86-64 Enflame GCU如 S60 官方验证过的驱动参考 1.7.0.9Docker ≥ 28.x镜像使用 docker/china/gcu.Dockerfile 构建mineru:gcu-vllm-latest镜像内已含 TopsRider vLLM 0.11 PyTorch 2.8.0 mineru[core] ≥ 3.4.0 全量模型容器--privileged--ipchost--networkhostMINERU_MODEL_SOURCElocal交互式使用或替换为mineru-api/mineru-gradio/mineru-openai-server服务命令排障确认torch.gcu可用MinerU 的 get_device() 依赖它自动识别设备必要时用MINERU_DEVICE_MODEgcu强制指定、TOPS_VISIBLE_DEVICES绑定卡、efsmi检查卡状态后端选择pipeline 与 vlm/hybrid 的 engine、http-client 模式在 vllm 容器下均已获 支持可按精度/延迟需求自由选择。以上流程全部基于当前仓库文档与源码可验证的行为适用前提是使用仓库官方提供的 GCU 基础镜像若自行更换 vLLM 或 PyTorch 版本需重新核对 enable_custom_logits_processors() 中的版本分支条件。【免费下载链接】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），仅供参考