# MiniMax-H3 ComfyUI 部署与使用教程（AI 操作手册）

MiniMax-H3 ComfyUI 部署与使用教程AI 操作手册文档定位本文档供 AI 助手阅读并直接执行记录 MiniMax-H3 视频生成模型在远程 GPU 服务器上的完整部署、运维与使用流程。所有命令、路径、凭据均为可执行的真实值。最后更新2026-08-25部署状态已完成服务可用http://SERVER_IP:8188目录环境信息SSH 远程操作方法部署流程已完成供重装参考服务管理启动/停止/日志/验证OOM 修复方案torch 2.8 lowvram工作流使用指南Prompt 写法官方三段式常见问题与避坑快速命令速查1. 环境信息项目值服务器地址SERVER_IPSSH 用户userSSH 密码njtWcah0LcSSH 端口22GPU8 × RTX 4090 24GB内存503GB显卡驱动535CUDA 12.2部署目录/home/YOUR_USER/MiniMax-H3ComfyUI 目录/home/YOUR_USER/MiniMax-H3/ComfyUIvenv/home/YOUR_USER/MiniMax-H3/venvPython 3.12.9miniforge3 创建conda/home/YOUR_USER/miniforge3清华镜像源已配服务端口8188已放行访问地址http://SERVER_IP:8188磁盘状况/分区 3.6T可用空间紧张约 30-39GB安装大文件前务必检查df -h /NAS 挂载/home/YOUR_USER/synology容量按实际情况填写可作为大文件中转网络/防火墙关键UFW 已激活默认 deny incomingiptables INPUT policy DROP新服务端口必须手动放行sudo ufw allow port/tcp8188 端口已于 2026-08-21 放行2. SSH 远程操作方法本机Windows无sshpass使用 Node.jsssh2库执行远程命令。脚本位于项目.workbuddy/目录。2.1 执行远程命令# 用法node ssh-run.js 远程命令cdC:\Users\YOUR_USER\WorkBuddy\2026-08-21-11-15-25\.workbuddyNODE_PATHC:\Users\YOUR_USER\.workbuddy\binaries\node\workspace\node_modulesnodessh-run.jsdf -h /脚本硬编码了服务器地址、用户、密码直接传入命令字符串即可。2.2 上传文件并执行# 用法node upload-run.js 本地文件 远程路径 [远程命令]nodeupload-run.js ./start_comfyui.sh /home/YOUR_USER/MiniMax-H3/start_comfyui.shbash /home/YOUR_USER/MiniMax-H3/start_comfyui.sh上传后自动chmod x并执行可选命令。2.3 注意事项SSH 后台进程陷阱nohup ... 通过 SSH 通道启动时通道关闭可能杀掉进程。长任务需用前台run_in_background方式保持连接或将启动逻辑写入脚本后用bash xxx.sh执行。引号转义复杂命令含引号时易出错改用cat temp.js写临时 JS 脚本或先上传 shell 脚本再执行。Node 运行时使用 managed 版本C:\Users\YOUR_USER\.workbuddy\binaries\node\versions\22.22.2\node.exeNODE_PATH指向 workspace 的 node_modules。3. 部署流程已完成供重装参考当前环境已部署完成。以下流程供重装或迁移时参考。3.1 目录规划/home/YOUR_USER/MiniMax-H3/ ├── ComfyUI/ # ComfyUI 0.33.0 (git clone master) ├── venv/ # Python 3.12.9 虚拟环境 ├── models/ # INT8 量化模型~42GB │ ├── diffusion_models/ │ ├── text_encoders/ │ ├── vae/ │ └── loras/ ├── logs/ # 日志目录 │ ├── comfyui.log │ └── comfyui.pid ├── downloads/ # wheel/模型临时下载 └── start_comfyui.sh # 启动脚本ComfyUI 内的models/{diffusion_models,text_encoders,vae,loras}通过软链接指向/home/YOUR_USER/MiniMax-H3/models/*。3.2 创建 venv# 使用 miniforge3 的 python不用 conda create国内 repodata 易卡/home/YOUR_USER/miniforge3/bin/python-mvenv /home/YOUR_USER/MiniMax-H3/venv坑venv/bin/python是软链接 → 实际解析到/home/YOUR_USER/miniforge3/bin/python3.12但sys.prefix仍是 venvsite-packages 用 venv 自己的。这是正常的不要被误导。3.3 克隆 ComfyUIcd/home/YOUR_USER/MiniMax-H3gitclone--depth1https://github.com/comfyanonymous/ComfyUI.git3.4 安装 torch最终版本2.8.0cu126重要初始部署装的是 torch 2.7.1cu126后因 OOM 问题升级到 2.8.0cu126启用 DynamicVRAM。详见 第 5 节。# 清华源只有 CPU 版 torchcu126 必须从 PyTorch 官方源下载# 大文件用 aria2c 多线程下载最稳清华源 100MB 易断流aria2c-c-x16-s16-k1M-d/home/YOUR_USER/MiniMax-H3/downloads\-otorch-2.8.0-cp312-cp312-manylinux_2_28_x86_64.whl\https://download.pytorch.org/whl/cu126/torch-2.8.0%2Bcu126-cp312-cp312-manylinux_2_28_x86_64.whl# 配套依赖精确版本# torchvision0.23.0, torchaudio2.8.0# nvidia 依赖: cudnn9.10.2.21, cusparselt0.7.1, nccl2.27.3, triton3.4.0(cp312)# 用 --no-deps 本地 wheel 秒装避免 pip 联网下载卡死/home/YOUR_USER/MiniMax-H3/venv/bin/pipinstall--no-deps --no-cache-dir\/home/YOUR_USER/MiniMax-H3/downloads/torch-2.8.0-*.whl\/home/YOUR_USER/MiniMax-H3/downloads/torchvision-0.23.0-*.whl\/home/YOUR_USER/MiniMax-H3/downloads/torchaudio-2.8.0-*.whl\/home/YOUR_USER/MiniMax-H3/downloads/nvidia_*.whl验证 CUDA 可用/home/YOUR_USER/MiniMax-H3/venv/bin/python-c import torch print(torch, torch.__version__, torch.version.cuda) print(cuda_ok, torch.cuda.is_available()) x torch.randn(512,512,devicecuda) print(matmul_ok, (xx).sum().item()) 兼容性cu126/cu128 torch 在 535 驱动上能跑 CUDACUDA 12.x minor-version 兼容性。ComfyUI 0.33 会警告 “need pytorch cu130”驱动 535 最高只支持 cu126此警告可忽略。3.5 安装 ComfyUI 依赖cd/home/YOUR_USER/MiniMax-H3TShttps://pypi.tuna.tsinghua.edu.cn/simplevenv/bin/pipinstall--no-cache-dir-i$TS-rComfyUI/requirements.txt3.6 下载 INT8 量化模型~42GBcd/home/YOUR_USER/MiniMax-H3mkdir-pmodels/{diffusion_models,text_encoders,vae,loras}# 从 ModelScope 下载国内源需 modelscope 或 git lfs# diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors (19.5GB)# text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors (14.6GB)# vae/minimax_h3_video_vae_fp16.safetensors (4.85GB)# vae/minimax_h3_audio_vae_fp32.safetensors (0.58GB)# loras/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors (1.8GB, Turbo加速8步)可选 Ref2VA 模型参考视频生成约 20GBminimax_h3_ref2va_pruned_int8_convrot.safetensors磁盘空间足够时可下载。T2V/I2V 不需要它。3.7 配置模型软链接cd/home/YOUR_USER/MiniMax-H3/ComfyUI/modelsln-sf/home/YOUR_USER/MiniMax-H3/models/diffusion_models diffusion_modelsln-sf/home/YOUR_USER/MiniMax-H3/models/text_encoders text_encodersln-sf/home/YOUR_USER/MiniMax-H3/models/vae vaeln-sf/home/YOUR_USER/MiniMax-H3/models/loras loras3.8 安装工作流模板# 最新版需从官方 PyPI 装清华镜像滞后venv/bin/pipinstall--no-cache-dir comfyui-workflow-templates# 已装版本0.11.444. 服务管理启动/停止/日志/验证4.1 启动服务# 远程执行启动脚本GPU3, port 8188, --lowvrambash/home/YOUR_USER/MiniMax-H3/start_comfyui.sh启动脚本内容/home/YOUR_USER/MiniMax-H3/start_comfyui.sh#!/bin/bashcd/home/YOUR_USER/MiniMax-H3/ComfyUIexportCUDA_VISIBLE_DEVICES3PY/home/YOUR_USER/MiniMax-H3/venv/bin/pythonnohup$PYmain.py--listen0.0.0.0--port8188\--disable-auto-launch--lowvram\/home/YOUR_USER/MiniMax-H3/logs/comfyui.log21echo$!/home/YOUR_USER/MiniMax-H3/logs/comfyui.pidechoComfyUI started on GPU3, PID$(cat/home/YOUR_USER/MiniMax-H3/logs/comfyui.pid)关键参数说明CUDA_VISIBLE_DEVICES3只用 GPU3单卡 24GB--lowvram激进卸载模型防 OOM24GB 必须加--listen 0.0.0.0允许外网访问4.2 停止服务# 方法1用 PID 文件kill$(cat/home/YOUR_USER/MiniMax-H3/logs/comfyui.pid)# 方法2PID 文件可能过时用 ps 查找psaux|grepmain.py --listen|grep-vgrepkillPID# 确认端口释放ss-tlnp|grep81884.3 查看日志# 实时日志tail-f/home/YOUR_USER/MiniMax-H3/logs/comfyui.log# 查看启动是否成功关键标志行grep-EDynamicVRAM|LOW_VRAM|RTX 4090|To see target/home/YOUR_USER/MiniMax-H3/logs/comfyui.log启动成功的标志日志中应出现DynamicVRAM support detected and enabled Set vram state to: LOW_VRAM Device: cuda:0 RTX 4090: cudaMallocAsync To see the GUI go to: http://0.0.0.0:81884.4 验证服务# 本机验证需在服务器上或通过 SSHcurl-shttp://localhost:8188/system_stats|headcurl-shttp://localhost:8188/object_info|python-cimport sys,json; djson.load(sys.stdin); print(nodes:, len(d))# 从外部验证本机 Windowscurl--noproxy*-m5http://SERVER_IP:8188/system_stats如果外部访问超时但 SSH 通检查防火墙sudo ufw status必要时sudo ufw allow 8188/tcp。5. OOM 修复方案torch 2.8 lowvram5.1 问题现象24GB 单卡生成视频时 OOM日志显示GPU reserved 23712/24564 MiB → 卸载全部模型5.2 根因三叠加torch 2.7.1 太旧ComfyUI 0.33 的 DynamicVRAM需 torch 2.8未启用显存估算/卸载不准启动脚本无显存模式参数默认 NORMAL_VRAM 全塞 GPU分辨率/帧数偏高激活显存过大5.3 修复方案ABC方案操作效果Atorch 升级到 2.8.0cu126启用 DynamicVRAM显存管理精准B启动脚本加--lowvram强制激进卸载防 OOMC降低分辨率 Turbo LoRA640×360 / 8-16帧 / 8步5.4 torch 升级关键步骤# 1. 下载 torch 2.8.0cu126 配套依赖aria2c 多线程# 从 https://download.pytorch.org/whl/cu126/ 下载# torch-2.8.0cu126, torchvision-0.23.0, torchaudio-2.8.0# nvidia-cudnn-cu129.10.2.21, nvidia-cusparselt-cu120.7.1# nvidia-nccl-cu122.27.3, triton3.4.0(cp312)# 2. 清理旧 torch 残留pip 中断会留 ~orch 临时目录venv/bin/pip uninstall-ytorch torchvision torchaudiorm-rfvenv/lib/python3.12/site-packages/~orch# 3. --no-deps 本地安装秒装不联网venv/bin/pipinstall--no-deps --no-cache-dir所有 wheel# 4. 验证venv/bin/python-cimport torch; print(torch.__version__)# 应输出 2.8.0cu1265.5 修复后验证重启 ComfyUI日志应出现pytorch version: 2.8.0cu126 DynamicVRAM support detected and enabled Set vram state to: LOW_VRAM Device: cuda:0 RTX 4090: cudaMallocAsync6. 工作流使用指南6.1 基本工作流结构用户使用官方 MiniMax-H3 文生视频模板核心节点链路CheckpointLoader(FL2VA INT8) → MiniMaxH3ImageToVideo主生成节点 → VAE Decode → 视频输出辅助节点EmptyMiniMaxH3LatentAV创建空 latent纯文生视频MiniMaxH3AddGuide添加引导MiniMaxH3ReferenceToVideo参考视频生成需 Ref2VA 模型MiniMaxH3SigmaShiftsigma 偏移6.2 时长调整时长控制链路PrimitiveFloat秒数→ ComfyMathExpression×24 换算帧数→ MiniMaxH3ImageToVideo.length修改PrimitiveFloat节点的值即可改时长单位秒5 秒 124 帧10 秒 240 帧24fpsComfyMathExpression 自动换算无需手动改 length如果找不到 PrimitiveFloat 节点可直接断开 length 连线手动填帧数值6.3 图生视频I2V / FL2VA模式输入说明是否需要额外模型T2V文生视频仅文本从零生成否当前已支持I2V首帧生视频1张首帧图从图片向后发展否MiniMaxH3ImageToVideo 原生支持FL2VA首尾帧生视频首帧尾帧图描述中间过渡否同上R2V参考视频生成参考视频/图风格/角色参考是需下载 Ref2VA ~20GBI2V 操作LoadImage → MiniMaxH3ImageToVideo.first_frameprompt 开头加对齐句式见第 7 节。6.4 分辨率建议24GB 显存分辨率帧数步数是否安全640×360120-2408(Turbo)推荐480×272120-2408(Turbo)安全512×2881208安全1280×7201208可能 OOM始终配合--lowvram Turbo LoRA8步。如果 640×360 还 OOM降到 512×288 或关闭 audio。6.5 Turbo LoRA 参数turbo_steps: 8 # Turbo 加速步数 turbo_mode: false # 当前 LoRA 标准用法 turbo_model_overhead: 1.007. Prompt 写法官方三段式来源HuggingFace MiniMaxAI/MiniMax-H3 模型卡 docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md7.1 三段式结构官方推荐 prompt 分为三个字段合并为一个文本框输入integrated_multimodal_description: [视觉 动作 对白时间线] overall_soundscape: [1-4句环境音 动作音效不重复对白/音乐] non_diegetic_music: [1-3句配器/节奏/力度不写情绪词]7.2 分镜规则首镜头[Shot 1]不带时间戳后续镜头以[Shot 2] At 00:02.500, the camera cuts to...开头切镜时间严格递增且必须落在视频时长内普通切换用语the camera cuts to/the shot cuts to/the shot transitions to仅在用户明确要求时使用 cross-dissolve、fade、wipe7.3 节拍上限短于 6 秒最多 2 个节拍镜头6-10 秒可 3-4 个镜头切镜应引入新信息主体/空间/状态/视点/时间否则用运镜而非切换7.4 运镜三要素运镜写成自然英语句包含运动类型 幅度可选 速度可选运动类型说明Zoom In / Zoom Out焦距变化机身不动Push In / Pull Out相机前/后移动Pan Left / Right机身不动镜头水平转Truck Left / Right相机水平平移Tilt Up / Down镜头垂直转Arc Shot围绕主体弧形移动Tracking Shot跟随移动主体Static Shot静止Shake Slightly / Strongly轻微/强烈抖动POV主体视角示例The camera pushes in with small amplitude at slow speed toward the subject.7.5 每镜内容顺序景别medium wide shot / close-up 等 → 运镜类型 幅度 速度 → 主体外观外貌、服装、位置 → 场景/环境光线、色调、背景 → 动作与反应7.6 对白与说话者说话者用稳定 ID(S1)、(S2)跨镜头保持对白格式d[语言] 原文/d逐字保留不翻译画外音says in an off-screen voiceover: d[English] .../d while his lips remain completely closed7.7 图生视频对齐句式I2V首帧For the target video, at 0.00 seconds into the target video, Picture 1 (from [Shot 1]) is fully referenced.FL2VA首尾帧How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot N) aligns with the S.SS-second mark of the target video.7.8 完整示例T2V10秒integrated_multimodal_description: [Shot 1] Cinematic, medium wide shot, pushing in slowly. In the cavernous, dimly lit bridge of a starship, sleek metallic consoles with glowing amber displays flank a massive, curved observation window. A female captain, in her late 40s with an athletic build and short silver-streaked black hair, stands in the center midground. She wears a structured, high-collared dark navy military tunic with silver chest insignias. Her back is to the camera, silhouetted against the cool, ambient starlight pouring through the thick glass. She stands perfectly still with her hands clasped tightly behind her back. Outside the window, a massive armada of jagged, dark grey dreadnoughts hovers in tight formation against a deep purple space nebula. The fleets massive rear thrusters begin to glow with an intense, escalating bright blue light. [Shot 2] At 00:04.500, the camera cuts to a close-up of the captains face and shakes strongly. The brilliant blue-white light from the fleets gathering energy reflects vividly in her dark eyes. Suddenly, a blinding white flash floods through the window, completely washing out the background as the fleet jumps to hyperspace. The sheer spatial force violently jolts the bridge, causing the captain from Shot 1 to stagger slightly forward, her shoulders tensing as she visibly braces herself against the physical tremors. As the intense white light fades abruptly, leaving only the dim, empty expanse of the purple nebula reflected on her starkly lit skin, her jaw clenches, and she slowly closes her eyes in the newly emptied space. overall_soundscape: A low, resonant hum of the ships ambient life support systems serves as the baseline, soon drowned out by an audible, escalating, high-pitched electronic whine as the fleet outside charges its hyperdrives. A massive, deafening, bass-heavy boom and sharp crackle erupts during the blinding flash, accompanied by the loud metallic creaking, rattling, and deep thuds of the bridges bulkheads vibrating under immense physical stress. The intense roaring impact then cuts abruptly back to a hollow, echoing room tone, leaving only the faint, steady hum of the isolated bridge. non_diegetic_music: Cinematic space-opera orchestral score, slow tempo, featuring a solitary, mournful French horn melody over deep, sustained string dissonances that build rapidly in volume and intensity, swelling to a massive orchestral peak before snapping immediately into silence right after the jump.8. 常见问题与避坑8.1 外部访问 8188 超时SSH 通但 HTTP 不通根因UFW 防火墙未放行端口。修复sudo ufw allow 8188/tcp排查curl --noproxy * -m 5 http://SERVER_IP:8188/system_stats超时则查防火墙。8.2 生成视频 OOM根因torch 2.8 / 无 --lowvram / 分辨率过高。修复见 第 5 节。降分辨率到 640×360确认 --lowvram 已加。8.3 pip 安装大文件卡死根因清华源 100MB 文件易断流。修复用aria2c -c -x 16 -s 16 -k 1M多线程下载再pip install --no-deps本地 wheel。8.4 torch 显示未安装但进程在跑根因pip 中断安装残留~orch临时目录进程靠内存活着重启必崩。修复rm -rf venv/lib/python3.12/site-packages/~orch重新pip install --no-deps本地 wheel。8.5 vLLM 无法加载 INT8 权重事实vLLM 无法加载 ComfyUI 的 INT8 单文件权重只能用官方 diffusers 完整仓库FL2VA ~144GB BF16。磁盘不够时只能用 ComfyUI INT8。8.6 SSH 后台进程被杀根因SSH 通道关闭时 nohup 进程可能被杀。修复长任务用前台run_in_background保持连接或上传 shell 脚本后bash xxx.sh执行。8.7 conda create 卡 repodata根因国内 conda repodata 下载慢/卡。修复用venv miniforge python代替conda create。8.8 comfyui-workflow-templates 版本滞后根因清华镜像源滞后。修复从官方 PyPI 安装pip install comfyui-workflow-templates不加 -i 清华源。9. 快速命令速查从本机Windows通过 SSH 执行# 变量WBC:\Users\YOUR_USER\WorkBuddy\2026-08-21-11-15-25\.workbuddyNODEC:\Users\YOUR_USER\.workbuddy\binaries\node\versions\22.22.2\node.exeNPM_PATHC:\Users\YOUR_USER\.workbuddy\binaries\node\workspace\node_modules# 启动服务cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jsbash /home/YOUR_USER/MiniMax-H3/start_comfyui.sh# 停止服务cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jskill \$(cat/home/YOUR_USER/MiniMax-H3/logs/comfyui.pid)2/dev/null; ps aux | grep main.py --listen | grep -v grep# 查看日志cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jstail -30 /home/YOUR_USER/MiniMax-H3/logs/comfyui.log# 验证服务cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jscurl -s -m 5 http://localhost:8188/system_stats# 检查 GPU 状态cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jsnvidia-smi --query-gpuindex,name,memory.used,memory.total --formatcsv# 检查磁盘cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jsdf -h / /home/YOUR_USER/synology# 检查进程cd$WBNODE_PATH$NPM_PATH$NODEssh-run.jsps aux | grep -E main.py|comfyui | grep -v grep服务器上直接执行# 启动bash/home/YOUR_USER/MiniMax-H3/start_comfyui.sh# 停止kill$(cat/home/YOUR_USER/MiniMax-H3/logs/comfyui.pid)# 日志tail-f/home/YOUR_USER/MiniMax-H3/logs/comfyui.log# 验证curl-shttp://localhost:8188/system_stats# 放行端口sudoufw allow8188/tcp# 检查 torch 版本/home/YOUR_USER/MiniMax-H3/venv/bin/python-cimport torch; print(torch.__version__)附录模型文件清单文件路径大小用途FL2VA INT8models/diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors19.5GB主扩散模型Qwen3VLmodels/text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors14.6GB文本编码器Video VAEmodels/vae/minimax_h3_video_vae_fp16.safetensors4.85GB视频解码Audio VAEmodels/vae/minimax_h3_audio_vae_fp32.safetensors0.58GB音频解码Turbo LoRAmodels/loras/minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors1.8GB8步加速Ref2VA可选models/diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors~20GB参考视频生成总计不含 Ref2VA~42GB