项目
内容
文档版本
v1.0（2026-09-19）
适用机器
Supermicro X10DAi双路Xeon工作站，Tesla V100-PCIE-32GB + Quadro P400
已验证状态
端到端跑通：文本生成视频并带原生音频（T2AV），480p / 720p / 1080p均已出片
部署根目录
/home/lzy/AI-soft/h3-comfyui/
数据来源
本机实际环境核对 + 2026-09-06至09-11的实测日志与运行记录

目录
1 这篇教程要解决什么问题
2 硬件与系统前提
3 三个版本门槛（整套方案的核心）
4 安装步骤（从零开始）
5 启动与验收
6 本次部署到底改了什么
7 工作流拓扑与节点参数
8 参数铁律：帧率、帧数网格、Turbo步数
9 显存天花板：一条片子最长能拍多久
10 实测性能基准
11 踩坑清单（按症状索引）
12 日常操作流程
13 已知限制与未验证方向
14 附录

1 这篇教程要解决什么问题
目的很具体：在一张算力卡为Tesla V100-PCIE-32GB的机器上，让ComfyUI直接加载MiniMax官方的H3权重，生成带原生音频的视频，并稳定复现。
为什么值得单独写一份教程：按照网上通用的安装方法（pip装最新torch、git clone最新ComfyUI、直接放Comfy-Org的safetensors），在这台机器上必然失败。失败点不在配置写错，而在三个硬性版本条件同时不满足。本教程把这些条件、它们背后的原因、以及本次实际做的全部改动逐条写清楚。
1.1 最终能跑出什么
下表是已经在本机跑通并交付过成片的能力边界，不是理论值。
表1-1 本机已验证的生成能力
项目
结果
生成类型
文生视频（T2V）、图生视频（首尾帧）、参考图/参考视频/参考音频驱动（ref2va）、带原生音频（对白/音效/环境声）
分辨率
480×272、720×1280（竖版9:16）、1072×1920（1080p竖版，宽度会被对齐到16的倍数）
单条时长
实测可跑5.17秒（124帧）至12.25秒（294帧）；15.08秒（362帧）显存溢出
音频
与视频同一次前向生成，独立保存为flac，再由脚本自动混流进mp4
速度
720p 5.17秒约32分钟；1080p 5.17秒约66分钟（Turbo 8步）

1.2 为什么默认装法跑不通
三条门槛，缺任何一条都表现为「模型能加载、推理出不了图」，或者直接没有可用内核。
表1-2 三条硬门槛
门槛
默认做法为什么失败
正确做法
PyTorch版本线
PyPI上torch的默认轮子是cu130，从Volta（计算能力7.0）起支持列表里删掉了sm_70，装上去一跑就是no kernel image is available
锁定cu128版本线，装torch==2.10.0（本机实测可用档）
ComfyUI版本
H3的原生节点与补丁是针对特定版本写的；补丁v0.1.4只保证在ComfyUI v0.34.5上工作
checkout精确tag v0.34.5，不要用latest main
精度内核
官方H3去噪器是为sm90/Blackwell准备的低比特格式，V100没有对应算子
装社区补丁minimax-h3-v100-patch v0.1.4，用FP16分支 + FP32安全岛绕开

1.3 三个必须同时对上的版本
这是整套方案的地基，先记住这一张表，后面全部步骤都是为了落地它。
表1-3 版本清单（本机实际安装值，2026-09-19核对）
组件
版本
说明
ComfyUI
v0.34.5（提交7fd919f0，2026-09-05）
来自Comfy-Org/ComfyUI，精确tag，工作区无本地改动
PyTorch
2.10.0+cu128（cp312）
必须是cu128线，支持列表含sm_70
comfy-kitchen
0.2.33
负责优化算子的后端库，V100上需要这一档
comfy-aimdo
0.5.2
动态显存卸载器，让32GB装下32B编码器加21GB去噪器
V100补丁
minimax-h3-v100-patch v0.1.4
混合精度补丁，自定义节点形式加载
Python
3.12.3
独立虚拟环境，不复用旧的cu118环境

2 硬件与系统前提
2.1 双卡机器：P400负责显示，V100负责计算
这台机器插了两张卡。Quadro P400负责显示输出，Tesla V100纯算力卡，物理上没有视频输出接口、不能当首显设备。两件事必须分清：
• nvidia-smi里的物理序号是0=P400、1=V100；
• 程序里的CUDA设备顺序在FASTEST_FIRST模式下相反：应把CUDA_VISIBLE_DEVICES设为0才拿到V100。
本部署的启动脚本已经写死CUDA_VISIBLE_DEVICES=0，并且启动日志会打印实际拿到的卡，验收时看一眼即可：
==> CUDA_VISIBLE_DEVICES=0 (V100 32GB)
[INFO] Device: cuda:0 Tesla V100-PCIE-32GB : cudaMallocAsync
[INFO] aimdo: ... inited for GPU: Tesla V100-PCIE-32GB (VRAM: 32494 MB)

2.2 驱动版本要求
本机驱动为580.178.04，可支持CUDA 13运行时。这一点很关键：早期部署失败的直接原因之一，是驱动535系列只支持到CUDA 12.2，而comfy_kitchen的CUDA扩展是按更高版本编译的，一进算子就报驱动版本不足。驱动升级到580之后该问题消失。
2.3 32GB显存不等于32GB可用
实测结论：torch能真正支配的只有约25至26GB。约6GB被CUDA上下文与分配器碎片吃掉。规划帧数时必须按这个数字算，不能按32768MB算。这一点在第9节的显存天花板里会反复用到。
3 三个版本门槛（整套方案的核心）
3.1 PyTorch必须走cu128这条线
这是最容易踩、也最难从报错里看出来的一个坑。PyPI上torch的默认轮子目前是cu130，即使指定torch==2.11.0也会解析成2.11.0+cu130。cu130与cu132已经完全放弃Volta，编译出来的内核列表从7.5（Turing）开始，V100的计算能力是7.0，于是任何前向都会抛：
RuntimeError: CUDA error: no kernel image is available for execution on the device

正确做法是安装cu128版本线。cu128从torch 2.7.0一直覆盖到2.11.0，其中2.10.0是本机验证过的cp312档。本机确认方式与结果：
>>> import torch
>>> torch.__version__
'2.10.0+cu128'
>>> torch.cuda.get_arch_list()
['sm_70', 'sm_75', 'sm_80', 'sm_86', 'sm_90', 'sm_100', 'sm_120']

只要列表里没有sm_70，就不要继续往下做，先把torch换掉。另外两点需要澄清：
• 系统里装的CUDA工具链版本（例如12.9）与这条无关。cu128轮子自带CUDA 12.8运行时，只有当你要在本机用nvcc重新编译扩展时，工具链版本才有影响。
• cu129版本线虽然存在，但对V100相比cu128没有任何收益，且ComfyUI的H3依赖声明会挑剔版本，没有必要绕这一圈。
3.2 ComfyUI要checkout精确tag
补丁v0.1.4的兼容性声明明确写着针对ComfyUI v0.34.5（其自带测试夹具也是这个版本）。补丁的工作方式是在运行时改写模型类的方法，一旦ComfyUI上游改了函数签名，补丁就会失效或抛参数个数错误。本部署的源码来源与状态：
origin https://github.com/Comfy-Org/ComfyUI.git
git describe --tags -> v0.34.5
git status --porcelain -> （空，即工作区无本地改动）

ComfyUI源码一行没改，这是刻意保持的：所有修改都以自定义节点和启动脚本的形式外挂，将来升级只需换tag和补丁目录。
3.3 V100补丁：为什么必须有它
MiniMax官方发布的H3权重是给新架构准备的。去噪器文件minimax_h3_fl2va_pruned_int8_convrot.safetensors名字里的int8_convrot指一种旋转后的int8量化格式，它在V100上没有可用内核；文本编码器文件名的nvfp4_awq看起来像NVIDIA的fp4格式、理论上要求Blackwell，但实测它是标准AWQ打包（U8组权重加每组缩放），打的是ComfyUI自己的量化标签，因此能正常加载。
补丁解决的就是前者，做法是把主干的attention与MLP走FP16分支，把对数值敏感的部分留成FP32安全岛。具体机制见第6.1节。
4 安装步骤（从零开始）
以下命令按顺序执行即可复现。路径统一用 /home/lzy/AI-soft/h3-comfyui作为部署根目录。
4.1 建立独立虚拟环境
必须独立，不要复用旧的ComfyUI环境（那套是cu118，comfy-kitchen被钉在0.2.25，两者会互相污染）。本机用uv建环境，Python 3.12.3：
cd /home/lzy/AI-soft
mkdir -p h3-comfyui && cd h3-comfyui
uv venv --python 3.12 .venv
# 本环境不带 pip（uv 默认可建无 pip 环境），后续都用 uv pip 装包
# uv 版本：0.11.23

4.2 克隆ComfyUI并切到精确tag
cd /home/lzy/AI-soft/h3-comfyui
git clone https://github.com/Comfy-Org/ComfyUI.git app
cd app && git checkout v0.34.5
git describe --tags # 必须输出 v0.34.5

4.3 安装PyTorch（锁定cu128）
download.pytorch.org在国内经常超时，改用清华镜像即可。PyPI上保留了旧版本轮子，而清华镜像是PyPI的完整镜像，因此能拉到cu128档：
cd /home/lzy/AI-soft/h3-comfyui
uv pip install --python .venv/bin/python \
--default-index https://pypi.tuna.tsinghua.edu.cn/simple \
'torch==2.10.0' 'torchvision==0.25.0' 'torchaudio==2.10.0'
# 装完立刻验证，不要跳过
.venv/bin/python -c "import torch;print(torch.__version__, torch.cuda.get_arch_list())"
# 期望：2.10.0+cu128 且列表里有 sm_70

4.4 安装ComfyUI自身依赖
cd /home/lzy/AI-soft/h3-comfyui/app
uv pip install --python ../.venv/bin/python \
--default-index https://pypi.tuna.tsinghua.edu.cn/simple \
-r requirements.txt

app/requirements.txt里已包含前端包、工作流模板与嵌入文档三件套，以及transformers、tokenizers、safetensors、einops、scipy等运行依赖，不需要额外手工补。
4.5 安装动态卸载器与算子后端
这两个包是H3能在32GB卡上跑起来的关键，普通文生图任务可以不装，H3必须装：
uv pip install --python .venv/bin/python \
--default-index https://pypi.tuna.tsinghua.edu.cn/simple \
'comfy-kitchen==0.2.33' 'comfy-aimdo==0.5.2' modelscope

comfy-aimdo是动态显存卸载器，负责在CPU与GPU之间换入换出权重，让15.69GB的文本编码器与20.97GB的去噪器共存于一张32GB卡上；启动日志里形如19995MB Staged的行就是它在工作。comfy-kitchen提供优化算子后端。
4.6 安装V100补丁
补丁来自GitHub社区项目Icbears/minimax-h3-v100-patch的v0.1.4版本。按它的说明，安装方式是解压到custom_nodes目录下，不需要在界面里连任何节点。
cd /home/lzy/AI-soft/h3-comfyui/app/custom_nodes
# 解压后得到 custom_nodes/minimax-h3-v100-patch/{__init__.py, runtime_patch.py, ...}
ls minimax-h3-v100-patch/
# __init__.py runtime_patch.py MANIFEST.json README.md legacy_patcher tests tools

两个必须知道的细节：
• 目录名与包内MANIFEST.json记录的install_folder字段（minimax-h3-v100-l3-clean）不一致。因为入口文件用的是相对导入，改名不影响运行，但升级时要按说明先删掉整个旧目录再解压，不要直接覆盖，否则可能同时存在两套补丁。
• 补丁对当前目录树状态敏感：它的有效性校验里有一步是检查源码中是否已存在同名补丁标记，如果检测到已打过，会直接跳过并返回。因此「停止ComfyUI再替换目录」这条要照做。
4.7 下载模型权重
模型来自Comfy-Org/MiniMax-H3，共五个文件。下载走ModelScope而不是HuggingFace镜像，原因是hf-mirror的resolve链接会302跳到被墙的xet存储节点，即使手动指定IP也会在TLS阶段失败。ModelScope上同一份文件字节完全一致，速度约12MB/s且支持断点续传。
cd /home/lzy/AI-soft/h3-comfyui
.venv/bin/ms download --model Comfy-Org/MiniMax-H3 --local-dir app/models \
diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors \
diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors \
text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors \
vae/minimax_h3_video_vae_fp16.safetensors \
vae/minimax_h3_audio_vae_fp32.safetensors

参数里的相对子路径会被保留，文件直接落到ComfyUI的models目录结构下，不需要再搬。另需下载Turbo LoRA（见第8.3节），来源是lightx2v/Minimax-h3-Turbo，单独放进app/models/loras/。
4.8 下载完整性校验（这一步不能省）
大文件下载最容易出的事故是文件被截断或头部被污染，而症状要到推理时才暴露。HF镜像或curl的302跳转页面有1090字节左右，如果下载器把跳转页当成内容写进文件、随后又从1090字节处续传，整个文件就错位了，表现为safetensors报header too large。校验方式与目标值：
# 1) 字节数必须与下表完全一致
stat -c '%s %n' app/models/diffusion_models/*.safetensors \
app/models/text_encoders/qwen3vl*.safetensors app/models/vae/minimax_h3*.safetensors
# 2) 用 safe_open 只读头部，不要用 load_file（会把 21GB 张量全读进内存）
.venv/bin/python - <<'py' from safetensors import safe_open p="app/models/diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors" with safe_open(p, framework="pt" ) as f: print(len(f.keys()), "tensors, header ok") py 表4-1 五个权重文件的精确字节数（本机实测，与ModelScope一致）
文件
字节数
约合
diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors
20970379616
20.97GB
diffusion_models/minimax_h3_ref2va_pruned_int8_convrot.safetensors
20970379616
20.97GB
text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors
15687142551
15.69GB
vae/minimax_h3_video_vae_fp16.safetensors
5207808496
5.21GB
vae/minimax_h3_audio_vae_fp32.safetensors
605254808
0.61GB
loras/minimax_h3_fl2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors
1956193000
1.96GB

一条经验：如果怀疑某个文件曾被中断的下载污染过，直接删掉从零重下，不要尝试续传修补——错位的文件续传之后仍然是错的。
5 启动与验收
5.1 启动脚本
部署根目录下的start.sh就是启动入口，全文很短，两条规矩值得单独记：一是不要加 --fp16-unet或 --force-fp16，精度由补丁自行接管；二是显存参数通过 $@ 透传，长帧数任务需要时可以追加。
#!/usr/bin/env bash
# MiniMax-H3 ComfyUI (V100) 启动脚本
set -euo pipefail
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$PROJECT_DIR/.venv/bin/activate"
cd "$PROJECT_DIR/app"
# V100 是 CUDA device 0(FASTEST_FIRST);P400 是 1。多卡时只暴露计算卡
export CUDA_VISIBLE_DEVICES="${COMPUTE_GPU:-0}"
echo "==> CUDA_VISIBLE_DEVICES=$CUDA_VISIBLE_DEVICES (V100 32GB)"
# 不要加 --fp16-unet / --force-fp16,V100 patch 自行接管精度
# 额外参数透传: 如 ./start.sh --vram-headroom 5 (长帧数防OOM)
exec python main.py --listen 0.0.0.0 --port "${COMFYUI_PORT:-8188}" "$@"

启动方式与服务地址：
cd /home/lzy/AI-soft/h3-comfyui
./start.sh # 监听 0.0.0.0:8188
# 或指定端口： COMFYUI_PORT=8189 ./start.sh

注意虚拟环境在部署根目录下的 .venv，不在app/.venv，找错目录会得到No such file or directory。
5.2 判定启动成功的三行日志
只看端口通不通是不够的，下面这三类行出现才说明整套链路（补丁、卸载器、精度）都就位了：
==> CUDA_VISIBLE_DEVICES=0 (V100 32GB)
[INFO] Device: cuda:0 Tesla V100-PCIE-32GB : cudaMallocAsync
[INFO] aimdo: ...INFO:comfy-aimdo inited for GPU: Tesla V100-PCIE-32GB (VRAM: 32494 MB)
[MiniMax H3 V100] v0.1.4 runtime profile installed: v0.1.4: native FP16
storage/branches + FP32 safety islands

第三条是补丁自己的声明，缺它说明补丁没加载（目录放错、或多套补丁冲突、或版本不匹配）。在真正加载模型时还会再打一行；装了LoRA的任务里，LoRA是否挂上也是靠这一行确认的：
[INFO] Model MiniMaxH3 prepared for dynamic VRAM loading. 19995MB Staged.
208 patches attached. Force pre-loaded 210 weights: 1175 KB.
# 208 patches attached = LoRA 已挂载（不挂 LoRA 时这里是 0 patches attached）

5.3 冒烟测试
第一次跑不要直接上720p长片，用480×272、20帧、10步的短任务验证通路。本机首次成功的记录是66.7秒出一个480×272的20帧片段，采样速度1.66秒每步。判定是否为真实画面，可以看帧亮度标准差是否大于15。
6 本次部署到底改了什么
这一节回答「做了哪些修改」。结论先给：ComfyUI本体零改动，全部修改集中在三处——一个外挂补丁、一个启动脚本、一个调用脚本。
6.1 补丁0.1.4改了什么（核心改动）
补丁以自定义节点形式加载，入口 __init__.py只做一件事：在导入时调用install_patch()，把MiniMax H3模型类的方法替换成V100可执行的版本。它替换的对象包括：
表6-1 补丁接管的方法（对应app/custom_nodes/minimax-h3-v100-patch/runtime_patch.py）
被替换的原始方法
补丁内的实现
作用
Attention.forward
_patched_attention_forward
FP16计算注意力，输出缩放拆成 /64 → FP16投影 → FP32乘回64
MLP.forward
_patched_mlp_forward
fc1走FP16，SwiGLU走FP32，fc2走FP16再乘回缩放
DiTBlock.forward
_patched_block_forward
按块调度FP16分支与FP32残差
FinalLayer.forward
_patched_final_forward
最终输出头保持FP32
Model.forward / Model.__init__
_patched_model_forward / _patched_model_init
入口接线、精度标记与形状校验
Layout.__init__
_patched_layout_init
记录分段范围，供视频段与音频段分别处理
条件投影层forward
_wrap_condition_projection
条件输入强制FP32

精度策略可以概括成一句话：能算快的地方用FP16，怕误差的地方留FP32。具体分工：
• FP16：主干的attention与MLP分支，权重也以FP16存储、预取、换出。
• FP32安全岛：残差、归一化与调制、条件输入、Token Refiner、最终输出头，以及目标音频与参考音频的注意力重算。
补丁还带两道自检：一是设备限制，检测到计算能力不等于7.0会直接拒绝生效并给出原因；二是运行形状校验与重复安装检查，避免两套补丁叠加。
6.2 启动脚本做了什么
• 把CUDA_VISIBLE_DEVICES固定为0（FASTEST_FIRST下即V100），避免误用显示卡。
• 显式声明不要传 --fp16-unet与 --force-fp16，因为这两者会与补丁的精度接管冲突。
• 支持传出额外命令行参数（例如 --vram-headroom），并把端口做成可配置。
6.3 调用脚本gen_h3.py的四处修改
gen_h3.py是提交任务、轮询状态、自动混流的封装脚本（134行，位于部署根目录）。它有四处改动值得记录，前三处是修bug，第四处是补功能：
表6-2 gen_h3.py的修改清单
修改
修改前的问题
现在的行为
默认帧率16 → 24
H3是原生24fps模型，用16fps编码会把90个原生帧放成1.5倍慢动作，而音频隐变量仍是原生时长，结果是音画不同步加台词含糊
默认24，命令行help里写明勿用16
轮询改用GET
ComfyUI的 /history/{id} 只接受GET，用POST会返回405，而轮询循环里的except会把异常吞掉，脚本一路空转到超时误报失败，其实产物早已生成
轮询单独走GET，提交与查询分开实现
新增 --timeout
原来硬编码7200秒，1080p长任务会让客户端提前退出，丢掉自动混流这一步（ComfyUI仍在渲染，产物留在app/output）
可配置，1080p建议给25200秒以上
新增 --lora
没有挂载LoRA的入口，Turbo加速用不上
在UNETLoader与SigmaShift之间插入LoraLoaderModelOnly，强度1.0，配合 -s 8使用

6.4 没有改动的地方（刻意保持）
• ComfyUI源码：git工作区完全干净，一行未改。升级时只需换tag。
• 模型权重：使用官方原始文件，没有做任何重打包或格式转换。
• 旧的ComfyUI环境（~/AI-soft/ComfyUI，cu118）保持原样不动，两套环境互不干扰。
7 工作流拓扑与节点参数
7.1 完整节点链
下面是从提交脚本实际发出的图结构，音频与视频由同一次采样产生，只是解码器不同。
1 UNETLoader(unet_name=minimax_h3_fl2va_pruned_int8_convrot.safetensors,
weight_dtype=default)
1a LoraLoaderModelOnly(model=1, lora_name=minimax_h3_fl2v_turbo_8step_v1.0_768p_...,
strength_model=1.0) # 仅 Turbo 任务需要
2 CLIPLoader(clip_name=qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors, type=minimax)
3 VAELoader(vae_name=minimax_h3_video_vae_fp16.safetensors)
4 MiniMaxH3ImageToVideo(clip=2, vae=3, prompt=<文本>,
width, height, length) -> [0] CONDITIONING [1] LATENT
# 不给首帧/尾帧参数即为纯文生视频
5 MiniMaxH3SigmaShift(model=1a 或 1, shift_video=12.0, shift_audio=3.0) -> MODEL
6 KSampler(model=5, positive=4[0], negative=4[0], # flow matching，正负同一个条件
seed, steps, cfg=1.0, sampler=euler, scheduler=simple,
latent_image=4[1], denoise=1.0)
7 VAEDecode(samples=6[0], vae=3) -> IMAGE
8 CreateVideo(images=7[0], fps=24) -> VIDEO
9 SaveVideo(video=8[0], filename_prefix=..., format=auto, codec=auto)
# 音频分支（与视频并行，共用同一个采样结果）
3b VAELoader(vae_name=minimax_h3_audio_vae_fp32.safetensors)
10 LTXVAudioVAEDecode(samples=6[0], audio_vae=3b) -> AUDIO
11 SaveAudio(audio=10[0], filename_prefix=...)

7.2 参数要点
• 负向提示词不单独编码。H3是flow matching模型，cfg固定1.0，正负条件传同一个，没有独立的负向编码节点。
• SigmaShift的shift_video=12.0、shift_audio=3.0是视频与音频两路各自的噪声调度平移量，不要只改一路，否则两条时间轴会不一致。
• 视频与音频在0.34.5里没有合并节点，会分别保存为mp4与flac，混流由gen_h3.py用ffmpeg完成。
• 分辨率会被对齐：节点会把宽度向下取到16的倍数，所以请求1080×1920实际得到1072×1920，需要严格1080宽的话要后期补边。
8 参数铁律：帧率、帧数网格、Turbo步数
8.1 帧率必须24
H3是原生24fps模型。节点里的length参数接受5到3600帧，但真实时长不看这个数字，而是看对齐后的帧数除以24。用16fps编码的后果是视频被拉慢1.5倍，而音频隐变量按40fps的原生节奏生成，两者错位。所以命令行永远写 --fps 24。
8.2 帧数必须落在17k+5的网格上
节点的对齐函数会把请求帧数向上吸附到17k+5这一序列：73、90、107、124、141、158……真实时长等于对齐后的帧数除以24。请求一个不在网格上的数字不会报错，但会静默变成下一个网格点，于是实际时长比你预期长，成本也更高。几个常用点：
表8-1 常用帧数网格点与真实时长
请求帧数
对齐后
真实时长
隐变量帧数
124
124
5.17秒
37
141
141
5.88秒
42
158
158
6.58秒
47
192
192
8.00秒
57
243
243
10.13秒
72
294
294
12.25秒
87
362
362
15.08秒
107

节点的提示文字写明训练范围约124至362帧。低于这个范围音频会退化成噪声底，高于这个范围动作开始重复、人物身份漂移。所以「一条片子最长多少秒」的诚实答案是约15秒，而不是节点参数上限暗示的150秒。
8.3 Turbo LoRA用8步
lightx2v/Minimax-h3-Turbo提供了适配ComfyUI的8步LoRA（1.96GB，624个diffusion_model.blocks相关键）。用法是标准LoraLoaderModelOnly，强度1.0，插在UNETLoader与SigmaShift之间，采样步数从20降到8。实测收益：
表8-2 Turbo LoRA实测加速
任务
20步
8步Turbo
倍数
480×272×49帧
约225秒
约39秒（3.44秒每步，采样27秒）
约5.8倍
720×1280×80帧
约61分钟
约23分钟（71.2秒每步）
约2.7倍
1080×1920×141帧
约10.6小时（受热降频影响）
按124帧Turbo折约66分钟至2小时级
数倍

步骤降到8步会略微牺牲保真度，长任务之前先用短任务让眼睛过一遍。同一仓库还有4步的v1.1与v1.2变体，本机未测试。
9 显存天花板：一条片子最长能拍多久
这是H3在32GB卡上最硬的约束，且它的限制来自隐变量帧数而不是像素总量，直觉容易判断错。
9.1 两个上限，先撞上的是显存
• 训练上限：124至362帧，即5.17至15.08秒。
• 显存上限：720p下294帧（12.25秒）实测可以跑完，362帧直接显存溢出。溢出报错长这样，且发生在第一次前向的三个到五分钟内：
torch.OutOfMemoryError: CUDA out of memory. Tried to allocate 5.33 GiB
allocated 25.41 GiB + requested 5.33 GiB > 31.73 GiB device limit, free 23.88 MiB

关键推论：时长比分辨率更贵。294帧720p（80.7分钟）反而比124帧1080p（66分钟）更慢，因为成本由隐变量帧数驱动，而不是像素数量。估成本要看 (帧数-5)//17*5+2这个隐变量帧数，不要看百万像素数。
9.2 显存调节参数是无效的
实测结论：把启动参数改成 --vram-headroom 5之后，溢出时的分配数字一个字节都没变（依然是25.41加5.33）。这个参数管的是权重常驻策略，而峰值出现在前向过程的激活上。所以遇到溢出不要反复试这个旋钮，直接降到下一个网格点。
9.3 超过12秒就分段拼接
要15秒以上的成片，把多个124帧片段分别生成再拼接。这样做的三个好处：每段都能独立重roll；人物身份在长镜头里更稳；剪辑点正好落在镜头切换处。代价是每段约32分钟，三段接近一小时半。
10 实测性能基准
下表全部为本机V100的实测墙钟时间，任务参数与结果一一对应。
10.1 各尺寸实测
表10-1 实测基准（8步Turbo除注明外）
任务
耗时
说明
480×272×20帧，10步
66.7秒
首次通路验证，采样1.66秒每步
480×272×49帧，20步
225秒
含真实语音内容，音频均值 −20dB
480×272×49帧，8步
约39秒
Turbo验证，采样27秒
720×1280×80帧，20步
约61分钟
含模型初始化与双VAE解码
720×1280×80帧，8步
约23分钟
71.2秒每步
720×1280×294帧，8步
4844秒（80.7分钟）
首步1193秒，稳态577至596秒每步，显存钉在31.5/32.0GB
720×1280×362帧
溢出
直接失败，不留半成品
1080×1920×124帧，8步
约66分钟
首步484秒，稳态460秒每步，全程232W、100% 利用率、1380MHz，无热降频
1080×1920×80帧，20步
约4.2小时
受热降频影响，570至770秒每步
1080×1920×141帧，20步
约10.6小时
被动散热热降频，时钟被压到292至570MHz，1830秒每步

10.2 热降频是最大的不确定因素
同一档1080p任务出现过66分钟与10.6小时两个结果，差别不在参数而在卡的状态。这张V100是被动散热（无风扇），显存温度一旦顶到85摄氏度就会软件降频，时钟从1380MHz掉到300至500MHz，速度差三倍以上。判断方法是在任务开头看几秒钟时钟：
nvidia-smi --query-gpu=clocks.current.sm,temperature.gpu,power.draw,utilization.gpu \
--format=csv -l 5
# 1300MHz 以上 = 一小时量级；几百MHz = 数小时量级，先改善风道再说

同一个124帧1080p任务在卡温正常时的实测值是：核心59摄氏度、显存73摄氏度、功耗232W、利用率100%，全程无降频。所以承诺时长之前先确认时钟。
10.3 两个容易被当成故障的正常现象
• 启动后约15分钟看不到进度是正常的：这是32B文本编码器与20GB去噪器的上台时间，日志里表现为Model Initializing。
• 日志里充满回车刷新的进度条，直接tail会看到错乱的内容。正确读法是把回车转成换行：
tr '\r' '\n' < comfyui_run_*.log | grep 's/it'

11 踩坑清单（按症状索引）
下表把本次部署与后续调试中实际踩到的坑按症状整理，便于对号入座。
表11-1 踩坑与解法
症状
根因
解法
no kernel image is available for execution on the device
torch装到了cu130版本线，没有sm_70内核
改装cu128线（torch 2.10.0），用torch.cuda.get_arch_list() 确认含sm_70
TypeError: _patched_final_forward() takes 5 positional arguments but 8 were given
补丁版本与ComfyUI版本不匹配
ComfyUI固定v0.34.5，补丁用v0.1.4
模型加载完成但推理报错或直接没有输出
补丁未生效（目录放错或多套补丁冲突）
看启动日志有没有v0.1.4 runtime profile installed；按说明先删旧目录再解压
启动即报libicuuc之类的库找不到
进程继承了外部的LD_LIBRARY_PATH，混入了gromacs、Amber、其他CUDA版本的库
用干净环境启动（env -i只保留必要的PATH与LD_LIBRARY_PATH）
safetensors：header too large
下载被curl 302跳转页污染，文件头部错位后又被续传
删除文件从零重下；用safe_open校验头部，用stat校验字节数
CUDA out of memory，分配数字带25.41 GiB
隐变量帧数超限，激活峰值撞墙
降到下一个网格点；不要试 --vram-headroom，实测无效
音画不同步、台词含糊拖沓
用了16fps编码原生24fps的帧
加 --fps 24；用ffprobe复核时长等于帧数除以24
音频文件存在但是噪声
帧数太少，模型来不及生成语音内容
帧数至少49帧并写明有对白；用ffmpeg volumedetect看均值，−50dB左右就是噪声底
提交脚本报超时但服务端日志说执行完成
/history/{id} 只能GET，POST返回405被轮询循环吞掉
轮询改GET；并检查app/output下是否已有产物
1080p任务到时间没出片
客户端默认超时7200秒，先于任务结束就退出了
加 --timeout 25200以上；即使超时，产物仍在app/output，可手工混流
画面被烧进字幕
提示词里写了具体台词，模型把台词同时做成语音和画面文字
实测否定句（如注明画面不出现任何文字）无效；只能不写具体台词文本，字幕后期加
画风从2D动漫跑成3D写实
提示词里写了雷电、水幕、环绕镜头这类写实影视语汇
削减特效描述本身；实测在提示词里补2D风格锁定词无效
打斗片尾变成两人贴脸
提示词以面部特写收尾，最后几帧被读成拥抱
改成结束在广角背对镜头定格，并写成分镜式的动作序列
pkill之后自己的shell也被杀掉
pkill -f的模式匹配到了执行命令的包装进程本身
改用显式PID，或用方括号技巧（如pkill -f 'prod50[0].tpr'）

12 日常操作流程
12.1 标准三件事
# 1) 起服务（前台，或按需后台）
cd /home/lzy/AI-soft/h3-comfyui && ./start.sh
# 2) 提交任务（示例：720p 竖版 5.17 秒，Turbo 8 步，带音频）
.venv/bin/python gen_h3.py \
-p "雨夜，两名侠客在水洼中对峙，拔刀交锋，动作凌厉" \
-W 720 -H 1280 --frames 124 --fps 24 -s 8 \
--lora minimax_h3_fl2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors \
-o wuxia_720 --timeout 7200
# 3) 取产物
ls -lh h3_out/ # 已混流的成品 mp4
ls -lh app/output/ # ComfyUI 原始产物（mp4 与 flac）

脚本会自动完成三件事：提交、轮询、以及把flac混流进mp4并输出ffprobe信息。
12.2 长任务的后台运行
半小时以上的任务建议后台运行并让它在结束时通知你。需要注意一个陷阱：杀掉前台的提交脚本并不会取消ComfyUI里的任务，渲染会继续、产物照样落到app/output，但自动混流这一步会丢失，需要手工执行：
ffmpeg -v error -y -i app/output/<前缀>.mp4 -i app/output/<前缀>.flac \
-c:v libx264 -pix_fmt yuv420p -c:a aac -shortest h3_out/<前缀 class="imgbox">.mp4

另注意本机跑H3前要停掉llama-server：V100不能同时服务这两个负载，ComfyUI加载H3之后常驻显存约5GB起步，加上采样峰值，两者并存必然溢出。
12.3 验收一条成片的三个指标
• 画面：抽帧看内容是否真实（首帧即开打这类要求可以在提示词里直接写开场动作来实现，不需要空镜铺垫）。
• 时长：ffprobe的输出应等于帧数除以24，例如124帧对应5.17秒。
• 音频：ffmpeg volumedetect的均值在 −20dB以内说明有真实内容；接近 −50dB就是噪声底，需要增加帧数重新生成。
13 已知限制与未验证方向
以下内容写清楚边界，避免把未经验证的东西当成结论。
• 字幕污染：提示词里写具体台词会被烧成画面字幕，已实测否定式描述无效。不写具体台词而只写「两人用中文对白喊话」这个方向可以避开字幕，但对话内容不可控，该实验当时被中断、尚无结论，要试请先用5秒档探路。
• 画风漂移：加入写实影视语汇会让2D动漫风变成3D写实CG，在提示词里加风格锁定词的修正方式实测无效，但削减特效描述这一方向尚未系统验证。
• 超长片：超过12.25秒需要分段拼接，单条15.08秒在720p下已确认溢出。1080p下294帧以上的可行性未测。
• 4步Turbo变体：仓库中存在v1.1与v1.2的4步LoRA，本机未测试。
• 参考图驱动：ref2va节点（MiniMaxH3ReferenceToVideo）已具备模型文件与本地节点，可用于跨镜头角色一致性，但当前调用脚本走的是fl2va路径，要产出多镜头同角色需要另写ref2va工作流。
14 附录
14.1 关键路径一览
表14-1 路径清单
用途
路径
部署根目录
/home/lzy/AI-soft/h3-comfyui/
虚拟环境（注意不在app下）
/home/lzy/AI-soft/h3-comfyui/.venv/
ComfyUI本体
/home/lzy/AI-soft/h3-comfyui/app/
启动脚本
/home/lzy/AI-soft/h3-comfyui/start.sh
提交与混流脚本
/home/lzy/AI-soft/h3-comfyui/gen_h3.py
V100补丁
/home/lzy/AI-soft/h3-comfyui/app/custom_nodes/minimax-h3-v100-patch/
模型权重
/home/lzy/AI-soft/h3-comfyui/app/models/{diffusion_models,text_encoders,vae,loras}/
成品输出
/home/lzy/AI-soft/h3-comfyui/h3_out/
ComfyUI原始产物
/home/lzy/AI-soft/h3-comfyui/app/output/

14.2 版本清单（复核用）
表14-2 运行环境版本
包
版本
ComfyUI
v0.34.5
torch
2.10.0+cu128
torchvision
0.25.0
torchaudio
2.10.0
comfy-kitchen
0.2.33
comfy-aimdo
0.5.2
transformers
5.16.1
tokenizers
0.23.2
safetensors
0.8.0
numpy
2.5.2
einops
0.8.2
av
18.1.0
scipy
1.18.1
modelscope
1.39.1
Python
3.12.3
uv
0.11.23

14.3 快速命令卡
# 起服务
cd /home/lzy/AI-soft/h3-comfyui && ./start.sh
# 环境自检（三行都要有正确输出）
.venv/bin/python -c "import torch;print(torch.__version__, torch.cuda.get_arch_list())"
ls app/custom_nodes/minimax-h3-v100-patch/runtime_patch.py
stat -c '%s' app/models/diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors # 20970379616
# 5 秒探路档（约 32 分钟）
.venv/bin/python gen_h3.py -p "..." -W 720 -H 1280 --frames 124 --fps 24 -s 8 \
--lora minimax_h3_fl2v_turbo_8step_v1.0_768p_comfyui_bf16.safetensors -o test
# 看 GPU 状态与时钟（判断会不会降频）
nvidia-smi --query-gpu=utilization.gpu,memory.used,clocks.current.sm,temperature.gpu,power.draw \
--format=csv,noheader

14.4 上游来源
• ComfyUI本体：Comfy-Org/ComfyUI，tag v0.34.5。
• V100混合精度补丁：Icbears/minimax-h3-v100-patch，v0.1.4（与Amduraznak/minimax-h3-fp16-fix同源思路）。
• 模型权重：ModelScope上的Comfy-Org/MiniMax-H3（与HuggingFace版本字节一致）。
• Turbo LoRA：ModelScope上的lightx2v/Minimax-h3-Turbo。

本文档中所有版本号、文件字节数、耗时与显存数据均取自本机实际环境核对与实测日志。环境变更后请以第14.3节的自检命令重新确认。