30分钟快速上手：MiniMax-H3-Comfy-NPU 昇腾 4 卡 NPU 环境搭建完整教程（Docker+CANN 版本匹配）

30分钟快速上手MiniMax-H3-Comfy-NPU 昇腾 4 卡 NPU 环境搭建完整教程DockerCANN 版本匹配【免费下载链接】MiniMax-H3-Comfy-NPU项目地址: https://ai.gitcode.com/Ascend-SACT/MiniMax-H3-Comfy-NPUMiniMax-H3-Comfy-NPU 是面向昇腾AscendNPU 的多卡推理适配补丁让 ComfyUI 在 4 张 A3 NPU 上稳定跑通 MiniMax-H3「视频 同步音频」联合生成。本文是一份 30 分钟完成环境搭建的完整教程从 Docker 容器创建、CANN 9.0.1 与 torch-npu 版本匹配、权重目录配置到首次出片一步步带新手部署成功。一、这个补丁是什么MiniMax-H3 昇腾 4 卡 NPU 加速能力速览MiniMax-H3 是「视频 同步音频」联合生成模型支持两大类任务权重任务输入FL2VA文生音视频首帧或首尾帧图生音视频0 图 / 1 图 / 2 图Ref2VA单图/多图、图片音频、单视频/多视频参考生成图 / 音频 / 视频补丁应用后相比 8 卡基线768P 15 秒视频 2400s资源消耗下降一半4 卡在相同场景约500 秒完成并支持三种降噪方案Euler 50 步最高质量res_multistep 21 步质量对照Turbo LoRA 4~8 步推荐日常基线最快上图为 FL2VA / Ref2VA 工作流的机甲风生成效果环境搭好后即可用它这类素材驱动出片。核心实现详见 README.md 1.2 节MultiNPUParallelConfig节点统一管理 1/2/4 卡下 DiT、文本编码器、视频 VAE、音频 VAE 的调度MiniMax-H3 DiT 采用 packed-token 序列并行Qwen3-VL 文本编码器走张量并行视频 VAE 多设备时间分块解码INT8 权重在 Ascend 走npu_quant_matmul避免回退 CPU二、Docker CANN 版本匹配清单一张表记住所有依赖NPU 环境搭建最大的坑就是版本不匹配——PyTorch、torch-npu 与 CANN 必须是同一套已验证组合不能混装。请记住下表组件已验证版本硬件Ascend A34×NPU单卡 64 GB HBMPython3.12.13CANN9.0.1PyTorch2.10.0cputorch-npu2.10.0.post2ComfyUI frontend1.48.7GCC / CMake11.4.0 / 3.22.1✅ 推荐容器镜像quay.io/ascend/vllm-omni:v0.26.0-a3。镜像内已预装上述全套验证版本「版本匹配」的关键就是选对这个基础镜像不要在离线安装时随意替换 torch / torch-npu / CANN 版本。机器可读的完整依赖记录见 source_deps_info.json。三、一键创建 NPU Docker 容器4 张卡挂载配置创建容器有三个要点--network host网络、挂载/dev/davinci0~3等设备、挂载宿主机驱动路径。官方示例按你的实际环境改路径即可docker run -itd -u root \ --name comfyui-npu \ --network host --ipc host \ --device /dev/davinci0 --device /dev/davinci1 \ --device /dev/davinci2 --device /dev/davinci3 \ --device /dev/davinci_manager --device /dev/devmm_svm \ --device /dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/sbin/npu-smi:/usr/local/bin/npu-smi:ro \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \ -v /etc/hccn.conf:/etc/hccn.conf:ro \ -v {宿主机规划路径}:/workspace \ -v {宿主机规划权重路径}:/weight \ quay.io/ascend/vllm-omni:v0.26.0-a3 /bin/bash进入容器后用一条命令验证硬件挂载是否成功npu-smi info能看到 4 张 NPU 列表说明容器创建正确可以进入下一步。四、代码与依赖安装补丁应用 3 步走第 1 步获取补丁源即本项目包含 NPU 补丁、安装脚本、归档自定义节点与工作流git clone https://gitcode.com/Ascend-SACT/MiniMax-H3-Comfy-NPU /workspace/patch第 2 步克隆 ComfyUI 并锁定已验证 commit仓库地址见 README.md 2.2 代码依赖表export COMFY_HOME/workspace/ComfyUI export PATCH_SOURCE/workspace/patch export PYTHON_BIN/usr/local/python3.12.13/bin/python3 git clone 官方ComfyUI仓库 ${COMFY_HOME} git -C ${COMFY_HOME} checkout --detach \ bd34f338ac505ea79e43968753968a464060e609第 3 步安装依赖 应用多卡 NPU 补丁${PYTHON_BIN} -m pip install -r ${COMFY_HOME}/requirements.txt COMFY_HOME${COMFY_HOME} bash ${PATCH_SOURCE}/install_deps_minimax_h3.sh cd ${COMFY_HOME} git apply --check ${PATCH_SOURCE}/comfy-ui-changes.patch git apply ${PATCH_SOURCE}/comfy-ui-changes.patch⚠️git apply --check预检必须通过不要忽略.rej文件或强行跳过某个文件。install_deps_minimax_h3.sh 脚本会自动完成 4 件事校验 torch / torch-npu / comfy-kitchen 版本与已验证值完全一致不一致直接报错拦截复制 Turbo 自定义节点来自 additional_files/custom_nodes/ComfyUI-MiniMax-H3-Turbo/到 ComfyUI 的custom_nodes/导入 6 套 MiniMax-H3 工作流到user/default/workflows/minimax-h3/复制运行时脚本到runtime/目录并加执行权限五、权重下载与 extra_model_paths.yaml 目录配置MiniMax-H3 官方权重下载清单见 README.md 4.1 节表格BF16 / INT8 两套可选低显存卡推荐 INT8 量化权重。共 7 个文件放入${COMFY_HOME}/models/对应分类目录${COMFY_HOME}/models/ ├── diffusion_models/ # FL2VA / Ref2VA DiT ├── text_encoders/ # Qwen3-VL 32B 文本编码器 ├── vae/ # 视频 VAE 音频 VAE ├── loras/ # Turbo LoRA └── model_patches/如果权重放在共享存储上可以在${COMFY_HOME}/extra_model_paths.yaml添加额外扫描路径。仓库已备好配置示例 additional_files/extra_model_paths.yaml把base_path改成容器内权重实际路径即可minimax_h3: base_path: /path/models diffusion_models: diffusion_models text_encoders: text_encoders vae: vae loras: lora修改后重启服务从启动日志确认出现Adding extra search path即配置生效。六、启动 ComfyUI 服务restart 脚本与健康检查运行时目录已内置一套安全的启停脚本start_comfyui-4npu.sh、stop_comfyui-4npu.sh、restart-v1.sh只需设置环境变量后一条命令启动export COMFY_HOME/workspace/ComfyUI export COMFYUI_RUNTIME_ROOT/workspace/runtime export PYTHON_BIN/usr/local/python3.12.13/bin/python3.12 export NPU_DEVICES0,1,2,3 export COMFYUI_PORT8189 bash ${COMFYUI_RUNTIME_ROOT}/restart-v1.shrestart-v1.sh内部自动完成安全停止同 PID 的旧服务 → 等待端口释放最多 30 次重试→ 拉起进程并轮询/system_stats健康检查。看到如下输出即启动成功ComfyUI is ready on NPU 0,1,2,3, port 8189浏览器访问http://服务器IP:8189/即可进入 ComfyUI 页面。⚠️ 如果服务只暴露 1 或 2 张卡打开工作流后必须把Multi-NPU Parallel Config节点的npu_count改为实际卡数可用值仅 1 / 2 / 4否则运行前校验会失败。七、页面操作6 套工作流与首次生成步骤6 套工作流位于 additional_files/workflows/minimax-h3/安装后从 Workflows 菜单直接打开工作流文件场景推荐权重组合fl2va_8steps_lora.jsonFL2VA 快速 8 步BF16 FL2VA BF16 TE EMA LoRAfl2va_21steps.jsonFL2VA 质量对照 21 步BF16fl2va_50steps.jsonFL2VA 最高质量 50 步BF16ref2va_8steps_lora.jsonRef2VA 低显存 8 步pruned INT8 INT8 TE EMA LoRAref2va_21steps.jsonRef2VA 质量对照 21 步BF16ref2va_50steps.jsonRef2VA 最高质量 50 步BF16页面操作顺序5 步出片从Workflows菜单打开对应 JSON在模型加载节点确认下拉权重名称与第五章清单一致确认Multi-NPU Parallel Config卡数为 44 卡服务保持默认在LoadImage节点选择图片素材填写 prompt、时长和分辨率点击Queue运行历史产物在 Queue/History 页面查看重启后记录仍保留工作流不打包输入图片首次运行前要在LoadImage节点重新选择素材。仓库自带的两张示例图additional_files/input/minimax-h3/可直接使用例如八、性能参考与常见问题排查核心场景耗时4 卡 / 768P / 固定 seed场景权重输出端到端FL2VA Turbo 8 步BF16768P / 5 秒212.33sFL2VA Turbo 8 步INT8768P / 5 秒113.51sRef2VA Turbo 8 步BF16768P / 15 秒495.79sRef2VA Turbo 8 步pruned INT8768P / 15 秒454.77sRef2VA Euler 50 步BF16768P / 15 秒2263.03s采样耗时近似随步数增长相同 BF16、768P、15 秒场景下8 步 / 21 步 / 50 步分别约 5.79 / 14.98 / 35.00 分钟。Turbo 8 步是推荐日常基线21 / 50 步仅用于质量对照。常见问题排查Q1首次任务为什么特别慢首次任务需从存储读取约 66 GB BF16 DiT 和 51.5 GB 文本编码器并建立各 rank 模型拓扑与 NPU 热缓存属预期现象后续任务可复用热缓存明显更快。Q24 卡显存为什么仍然高DiT 是序列并行而非参数分片每张卡都需要完整模型的可换入权重地址空间4 卡加速的是 token/attention 计算不会把单卡权重显存除以 4。Q3任务 OOM 失败后如何处理先读runtime/*.log中第一条异常不要直接重复提交同一任务确认队列为空后用 restart-v1.sh 清理进程级 allocator 状态再重试。Q4启动时的警告是不是错误xFormers not available、No module named skimage等提示在昇腾环境属于预期不影响 MiniMax-H3 运行判断标准是MultiNPUParallelConfig与 MiniMax Turbo 节点是否成功导入。Q5单卡可以跑吗可以作为低资源成功性方案推荐 INT8 量化权重Ref2VA 必须用 pruned INT8 DiT 并把分辨率降到 480P单卡 BF16、768P、15 秒不作为支持基线。【免费下载链接】MiniMax-H3-Comfy-NPU项目地址: https://ai.gitcode.com/Ascend-SACT/MiniMax-H3-Comfy-NPU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考