ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

MinerU 摩尔线程(MooreThreads)MUSA 加速卡部署指南:Docker 镜像构建、关键环境变量与 vLLM 引擎适配

MinerU 摩尔线程(MooreThreads)MUSA 加速卡部署指南:Docker 镜像构建、关键环境变量与 vLLM 引擎适配 MinerU 摩尔线程MooreThreadsMUSA 加速卡部署指南Docker 镜像构建、关键环境变量与 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 仓库中 docs/zh/usage/acceleration_cards/MooreThreads.md 整理并扩充面向希望在摩尔线程 MTT S4000MUSA加速卡上部署 MinerU 的读者。文章完整覆盖官方指南给出的镜像构建与容器启动流程并结合 docker/china/musa.Dockerfile 及mineru/utils、mineru/backend/vlm等源码深入讲解MINERU_VLLM_DEVICE、MINERU_MODEL_SOURCE等环境变量的作用机制、musa 设备的自动探测链路以及 vLLM v0/v1 引擎在摩尔线程平台上的兼容边界帮助读者完成从构建镜像到稳定运行 pipeline / VLM 全链路的部署。1. 适用环境与测试平台该指南以摩尔线程 MTT S4000 加速卡为验证平台官方指南中记录的测试环境如下部署前建议先核对自己机器的对应项os: Ubuntu 22.04.4 LTS cpu: Intel x86-64 dcu: MTT S4000 driver: 3.0.0-rc-KuaE2.0 docker: 24.0.7从源码结构看MinerU 将摩尔线程的运行时抽象为musa设备类型其前提是环境中安装了对应的 MUSA 工具链即 PyTorch 提供torch.musa后端。仓库中所有加速卡适配逻辑均围绕该设备名展开因此本文中的musa 设备指的就是通过torch.musa可探测到的摩尔线程加速卡。2. 基于 musa.Dockerfile 构建镜像MinerU 在 docker/china/musa.Dockerfile 中提供了针对摩尔线程平台的官方镜像定义文件。该文件要求 amd64x86-64CPU 加摩尔线程 GPU 的运行环境关键内容如下# Base image containing the vLLM inference environment, requiring amd64(x86-64) CPU MooreThreads GPU. FROM registry.mthreads.com/mcconline/vllm-musa-qy2-py310:v0.8.4-release基础镜像registry.mthreads.com/mcconline/vllm-musa-qy2-py310:v0.8.4-release这是一个基于 vLLM v0.8.4即 v0 引擎系列的 MUSA 推理环境镜像。这也正是官方指南注意事项中提到MinerU 现阶段采用 v0 引擎作为适配方案的镜像层依据。系统依赖安装fonts-noto-core、fonts-noto-cjk、fontconfig、libgl1等用于 OpenCV 的中文字体渲染与 PDF 版面元素输出。MinerU 安装通过 pip 安装mineru[gradio]3.4.0及配套依赖ftfy、shapely、pyclipper、omegaconf、固定版本numpy1.26.4与opencv-python4.11.0.86。模型预置RUN /bin/bash -c mineru-models-download -s modelscope -m all在构建阶段即通过 ModelScope 下载全部模型到镜像内避免容器启动后重复拉取。入口行为ENTRYPOINT [/bin/bash, -c, export MINERU_MODEL_SOURCElocal exec \$\, --]ENTRYPOINT 会默认导出MINERU_MODEL_SOURCElocal让 MinerU 使用镜像内已下载的本地模型而不是在线拉取。构建命令在包含 Dockerfile 的构建上下文目录中执行docker build --networkhost -t mineru:musa-vllm-latest -f musa.Dockerfile .其中--networkhost用于保证构建阶段可访问模型下载源镜像名mineru:musa-vllm-latest可按需替换。3. 启动 Docker 容器与关键环境变量官方指南给出的完整启动命令如下docker run -u root --name mineru_docker \ --networkhost \ --ipchost \ --shm-size80g \ --privileged \ -e MTHREADS_VISIBLE_DEVICESall \ -e MINERU_VLLM_DEVICEmusa \ -e MINERU_MODEL_SOURCElocal \ -it mineru:musa-vllm-latest \ /bin/bash执行该命令后会进入容器的交互式终端可直接在容器内运行 MinerU 相关命令也可以把结尾的/bin/bash替换为服务启动命令直接拉起 MinerU 服务API/WebUI/HTTP 客户端/Server 等启动方式可参考 docs/zh/usage/quick_usage.md 与 docs/zh/usage/cli_tools.md。各参数的作用说明参数 / 环境变量作用--networkhost容器与宿主机共享网络栈便于 MUSA 运行时与后续服务端口直接访问--ipchost、--shm-size80g扩大共享内存满足 vLLM 多进程如mpexecutor的通信需求--privileged授予容器对 MUSA 设备的完整访问权限MTHREADS_VISIBLE_DEVICESall控制容器可见的摩尔线程加速卡数量指定方式与 NVIDIA GPU 类似可参考摩尔线程官方文档的 GPU 枚举说明MINERU_VLLM_DEVICEmusa告知 MinerU 当前 vLLM 运行于摩尔线程设备驱动设备级 vLLM 参数适配逻辑详见第 5 节MINERU_MODEL_SOURCElocal使用镜像内预置的本地模型与 Dockerfile 的 ENTRYPOINT 行为一致双重保证离线可用3.1MINERU_VLLM_DEVICE在源码中的消费链路MINERU_VLLM_DEVICE并非普通提示性变量它会被mineru/backend/vlm/utils.py中的mod_kwargs_by_device_type()实际读取在 mineru/backend/vlm/utils.py 中mod_kwargs_by_device_type(kwargs_or_args, vllm_mode)从环境变量MINERU_VLLM_DEVICE取出设备类型再经_get_device_config()查询设备专属的 vLLM 配置如compilation_config、block_size等最后根据运行模式server/sync_engine/async_engine把配置注入到 vLLM 的启动参数或 kwargs 中。在 server 模式mineru-openai-server等下mineru/model/vlm/vllm_server.py 会调用mod_kwargs_by_device_type(args, vllm_modeserver)在引擎模式下mineru/backend/vlm/vlm_analyze.py 分别在sync_engine与async_engine两条路径上应用同样的适配。值得注意的是_get_device_config()的DEVICE_CONFIGS字典中musa的配置条目当前处于注释状态mineru/backend/vlm/utils.py即历史上曾试验过cudagraph_capture_sizes、simple_cuda_graph、block_size: 32等编译优化目前对 musa 不额外注入任何 vLLM 参数。因此对摩尔线程平台而言MINERU_VLLM_DEVICEmusa更多是设备识别与预留适配入口的作用实际生效的默认参数来自基础镜像的 vLLM v0.8.4。3.2MINERU_MODEL_SOURCE与 ENTRYPOINT 的关系Dockerfile 的 ENTRYPOINT 已经默认export MINERU_MODEL_SOURCElocal容器启动命令中再次显式声明属于双保险配置即使未来修改 ENTRYPOINT 或改用自定义入口脚本模型来源仍然锁定为本地镜像预置模型。4. MinerU 如何识别 musa 设备源码级探测链路MinerU 的设备识别、显存读取与显存回收三处均对 musa 做了原生支持部署排障时可对照以下链路设备类型探测mineru/utils/config_reader.py 中的get_device()先检查环境变量MINERU_DEVICE_MODE显式指定时优先级最高否则按cuda → mps → npu → gcu → musa → mlu → sdaa的顺序逐级探测最终兜底为cpu。其中 musa 分支通过torch.musa.is_available()判断返回字符串musa。显存容量读取mineru/utils/model_utils.py 的get_vram()对 musa 设备调用torch.musa.get_device_properties(device).total_memory换算为 GB该值会进一步影响 mineru/backend/vlm/utils.py 中 vLLM 的默认显存利用率set_default_gpu_memory_utilization与批量大小set_default_batch_size显存 ≥16GB 取 8≥8GB 取 4否则 1。此外还可用环境变量MINERU_VIRTUAL_VRAM_SIZE覆盖自动探测结果。显存回收mineru/utils/model_utils.py 的clean_memory()对 musa 设备调用torch.musa.empty_cache()配合clean_vram()在显存低于阈值默认 8GB时主动释放缓解长时批处理中的显存碎片问题。编译特性开关mineru/backend/vlm/utils.py 的enable_custom_logits_processors()将 musa 设备的 compute capability 视为8.0与 npu、gcu 等国产卡同一档处理用于决定 vLLM 的custom_logits_processors是否启用。5. vLLM 引擎适配说明为什么采用 v0 引擎官方指南注意事项中有一条关键兼容性说明由于摩尔线程目前对 vLLM v1 引擎的支持尚待完善MinerU 现阶段采用v0 引擎作为适配方案受此限制vLLM 的异步引擎Async Engine功能存在兼容性问题可能导致部分使用场景无法正常运行。这与镜像选型一致——基础镜像vllm-musa-qy2-py310:v0.8.4-release本身就是 v0.8.4v0 引擎系列。在源码层面相关约束体现在两处VLLM_USE_V1环境变量mineru/backend/vlm/utils.py 中enable_custom_logits_processors()会读取VLLM_USE_V1默认1当显式设为0时直接禁用 custom logits processors。在摩尔线程平台上若观察到 v1 引擎相关问题可通过该开关回退行为并观察日志。引擎模式的分支vlm_analyze.py中同步引擎sync_engine与异步引擎async_engine是两条独立路径异步引擎路径依赖 vLLM v1 的异步能力这正是兼容性表格中 fastapi / gradio 服务下vlm/hybrid-engine模式不可用的根源详见下节。6. 各使用场景的兼容性矩阵不同环境下MinerU 对摩尔线程加速卡的支持情况如下来自官方指南支持且运行较稳定、精度与 NVIDIA GPU 基本一致支持但较不稳定某些场景可能异常或精度存在差异不支持无法运行或精度差异较大使用场景后端模式容器环境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-servervllm从表格可以得出两条实操结论命令行mineru是最完整的入口pipeline、engine、http-client 三种后端均可用。服务化部署优先选择http-client模式在 fastapi 与 gradio 服务中进程内vlm/hybrid-engine因依赖 vLLM 异步引擎而被标记为不可用改为让服务进程通过http-client访问一个独立的 vLLM 推理端点例如mineru-openai-server或独立 vllm 服务即可绕开异步引擎限制这也是服务 外部推理节点的典型拓扑。7. 日常运维与设备管理提示指定可见加速卡摩尔线程加速卡枚举方式与 NVIDIA GPU 类似可在容器参数中通过MTHREADS_VISIBLE_DEVICES指定例如只暴露编号 0、1 的卡-e MTHREADS_VISIBLE_DEVICES0,1不指定时默认为all。查看加速卡占用在宿主机上执行mthreads-gmi命令可查看各加速卡的显存占用与使用状态部署前据此挑选空闲的加速卡 ID避免多容器/多任务间产生资源冲突。显存不足的应急覆盖若个别环境自动探测到的显存容量不符合预期可通过环境变量MINERU_VIRTUAL_VRAM_SIZE单位 GB覆盖get_vram()的自动探测结果见 mineru/utils/model_utils.py。强制指定设备若自动探测顺序导致设备识别不符合预期可设置MINERU_DEVICE_MODEmusa直接指定设备类型见 mineru/utils/config_reader.py。8. 小结在摩尔线程 MTT S4000 上部署 MinerU 的路径是清晰的使用 docker/china/musa.Dockerfile 构建基于 vLLM v0.8.4 MUSA 镜像的镜像构建期即完成模型预置通过MTHREADS_VISIBLE_DEVICES、MINERU_VLLM_DEVICEmusa、MINERU_MODEL_SOURCElocal三个环境变量打通设备可见性与模型来源再依据兼容性矩阵选择后端模式——命令行全模式可用服务化场景推荐vlm/hybrid-http-client配合独立推理端点。源码层面MinerU 已在设备探测torch.musa、显存读取与回收、compute capability 判档等环节原生支持 musa 设备为后续跟进摩尔线程 vLLM v1 引擎的进展预留了MINERU_VLLM_DEVICE适配入口可持续关注 mineru/backend/vlm/utils.py 中DEVICE_CONFIGS的变化。【免费下载链接】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),仅供参考
返回列表