Viggle Remake 的 ComfyUI 集成与 int8/GGUF 量化部署实战
Viggle Remake 的 ComfyUI 集成与 int8/GGUF 量化部署实战
本篇技术指南围绕 COMFYUI.md 展开,讲清楚 Viggle Remake 如何在原生 ComfyUI 的 MiniMax-H3 支持上补齐四个专用节点,并通过 int8/GGUF 单文件权重把 80 GB 的 bf16 方案压缩到 12–48 GB 显卡可跑的规模。读完后你应当能完成节点包与权重安装、跑通 swap/edit 两个示例工作流、按显存选到合适的权重格式,并理解 LoraLoaderBypassModelOnly、Viggle Remake Noise 这些设计与参考采样器 inference/sample.py 的对应关系。
一、为什么需要一个小节点包
ComfyUI 本身已经能原生跑 MiniMax-H3 的 transformer、两个 VAE 和 Qwen3-VL 条件编码器。Viggle Remake 只需要补充那些“股票节点做不对、而 sample.py 必须这样做”的部分,因此节点包 comfyui/ComfyUI-Viggle-Remake 只提供四个节点。其模块文档字符串把职责划分写得很明确:
- RemakeConditioning:把源视频表示为
<Video 1>、把每张参考图表示为<Picture N>,并在给出pins时同时把它们作为真实输出帧号上的关键帧;文本侧采用纯文本呈现方式;源音轨作为干净的目标音频贯穿整个去噪过程。 - RemakeKeyframeUntil:当 sigma 降到
keyframe_until以下(0.9 即六次前向中的后两次)时丢弃关键帧。 - RemakeNoise:按参考脚本的抽样顺序生成起始噪声,使同一个 seed 得到同一段视频。
- RemakePrefix:用于“跳接”,让上一段渲染的若干帧以干净状态开启本次渲染。
除此之外的一切都是 ComfyUI 原生节点。文档标注的验证环境是 ComfyUI 0.42.0。
对应的 Python 包入口很简单,只做节点注册:comfyui/ComfyUI-Viggle-Remake/init.py 从 nodes.py 导入 NODE_CLASS_MAPPINGS 与 NODE_DISPLAY_NAME_MAPPINGS。四个节点在 ComfyUI 界面中的显示名分别是 Viggle Remake Conditioning、Viggle Remake Keyframe Until、Viggle Remake Noise、Viggle Remake Prefix,分类均为 Viggle Remake。
二、安装 ComfyUI 侧依赖
2.1 下载基础模型、LoRA、节点包与示例输入
在 ComfyUI 根目录下执行:
cd ComfyUI
pip install -U "huggingface_hub>=1.0" # the hf CLI; older versions keep only the last --include
# the base model, as Comfy-Org's single-file repack (about 124 GB)
hf download Comfy-Org/MiniMax-H3 \
diffusion_models/minimax_h3_fl2va_bf16.safetensors \
text_encoders/qwen3vl_32b_minimax_h3_bf16.safetensors \
vae/minimax_h3_video_vae_fp16.safetensors \
vae/minimax_h3_audio_vae_fp32.safetensors \
--local-dir models
# the LoRAs, the nodes, the workflows and the example inputs from this repository
hf download Viggle/Viggle-Remake --include "comfyui/*" --include "examples/inputs/*" --local-dir ./Viggle-Remake
cp -r Viggle-Remake/comfyui/ComfyUI-Viggle-Remake custom_nodes/
cp Viggle-Remake/comfyui/viggle_remake_*_comfyui.safetensors models/loras/
这里有一个容易踩的坑:hf CLI 必须升到 1.0 以上。旧版本的多个 --include 只会保留最后一个,导致下载内容缺项。
2.2 文件、目录与节点的对应关系
| 文件 | 目录 | 使用的节点 |
|---|---|---|
minimax_h3_fl2va_bf16.safetensors |
models/diffusion_models |
Load Diffusion Model |
qwen3vl_32b_minimax_h3_bf16.safetensors |
models/text_encoders |
Load CLIP,type 选 minimax |
minimax_h3_video_vae_fp16.safetensors、minimax_h3_audio_vae_fp32.safetensors |
models/vae |
Load VAE,各加载一个 |
viggle_remake_swap_comfyui.safetensors、viggle_remake_edit_comfyui.safetensors |
models/loras |
LoraLoaderBypassModelOnly |
必须使用 fl2va 扩散模型,而不是 ref2va。 原因是 LoRA 作用在基础 transformer 上,与 sample.py 加载的是同一份权重。两个 ComfyUI 版 LoRA 文件与 lora/swap、lora/edit 的权重完全相同,只是被 comfyui/to_comfyui.py 重新打包成了 ComfyUI 的层命名。
2.3 转换脚本做了什么
comfyui/to_comfyui.py 的转换逻辑可以从源码直接读出,它解决的是“同一份 delta、不同打包方式”的问题:
put("video_patch_proj", w["proj_in.lora_A.weight"], w["proj_in.lora_B.weight"], r)
put("final_layer.video_out", w["proj_out.lora_A.weight"], w["proj_out.lora_B.weight"], r)
for i in range(BLOCKS):
p, q = f"transformer_blocks.{i}", f"blocks.{i}"
A = torch.cat([w[f"{p}.attn.to_{x}.lora_A.weight"] for x in "qkv"])
...
value, gate = w[f"{p}.ff.net.0.proj.lora_B.weight"].chunk(2)
put(f"{q}.mlp.fc1", w[f"{p}.ff.net.0.proj.lora_A.weight"], torch.cat([gate, value]), r)
具体做了三件事:
- 重命名:
transformer_blocks.N→blocks.N,并加上diffusion_model.前缀。 - 融合 QKV:把
attn.to_q、attn.to_k、attn.to_v的 LoRA A 沿输出维拼接,B 用分块对角方式放进3 * 7168行的零矩阵里,并把 alpha 设为3 * r。 - 调整 SwiGLU 两半顺序:
ff.net.0.proj的 B 被chunk(2)拆成value, gate后按[gate, value]重新拼接,因为 ComfyUI 的mlp.fc1对两半的排列顺序不同。
脚本中 BLOCKS, QKV = 50, 7168,最后断言张量数量为 3 * (2 + 4 * BLOCKS)(每个线性层产出 A、B、alpha 三个张量),张量保持原 dtype。这意味着转换是无损的重新排布,不会引入精度损失——这也解释了为什么不建议换成 LoraLoaderModelOnly,问题不出在文件上。
三、跑通示例工作流
3.1 按工作流期望的文件名准备输入
cp Viggle-Remake/examples/inputs/swap-pineapple-mascot/source.mp4 input/remake_swap_source.mp4
cp Viggle-Remake/examples/inputs/swap-pineapple-mascot/ref1.png input/remake_swap_ref1.png
cp Viggle-Remake/examples/inputs/swap-pineapple-mascot/ref2.png input/remake_swap_ref2.png
cp Viggle-Remake/examples/inputs/edit-remove-turbines/source.mp4 input/remake_edit_source.mp4
cp Viggle-Remake/examples/inputs/edit-remove-turbines/ref1.png input/remake_edit_ref1.png
cp Viggle-Remake/examples/inputs/edit-remove-turbines/ref2.png input/remake_edit_ref2.png
3.2 加载并排队
把 comfyui/workflows/remake_swap_ui.json 或 comfyui/workflows/remake_edit_ui.json 拖到画布上并排队执行。*_api.json 是同一张图的 /prompt API 版本,适合脚本化调用。
每个工作流都与 examples/demo.sh(见 examples/demo.sh)的渲染结果对应,seed 为 0:226 帧、832×480、两张参考图按关键帧固定、examples/prompts/ 中的提示词已填好。成片落在 output/viggle_remake/。
从 API 版本可以看到节点编号与依赖连线,例如 edit 工作流的前几个节点:
| 节点 | class_type | 关键参数 |
|---|---|---|
| 1 | UNETLoader |
minimax_h3_fl2va_bf16.safetensors, weight_dtype: default |
| 2 | LoraLoaderBypassModelOnly |
viggle_remake_edit_comfyui.safetensors, strength_model: 1.0 |
| 3 | RemakeKeyframeUntil |
keyframe_until: 0.9 |
| 4 | CLIPLoader |
qwen3vl_32b_minimax_h3_bf16.safetensors, type: minimax |
| 7–10 | LoadVideo / GetVideoComponents / LoadImage ×2 |
remake_edit_source.mp4、remake_edit_ref1.png、remake_edit_ref2.png |
| 11 | RemakeConditioning |
接 CLIP、两个 VAE、source、audio、两张图与 prompt |
| 12 | RemakeNoise |
seed: 0 |
| 13–16 | BasicGuider / KSamplerSelect / ManualSigmas / SamplerCustomAdvanced |
euler + 六步 sigma 网格 |
| 17–20 | VAEDecode / VAEDecodeAudio / CreateVideo / SaveVideo |
24 fps、h264、viggle_remake/edit |
3.3 图结构
Load Diffusion Model → LoraLoaderBypassModelOnly → Viggle Remake Keyframe Until (0.9) → BasicGuider
Load Video → Get Video Components ─┐
Load Image ×2 ─────────────────────┼→ Viggle Remake Conditioning → BasicGuider, Viggle Remake Noise
Load CLIP, Load VAE ×2 ────────────┘
KSamplerSelect (euler) + ManualSigmas → SamplerCustomAdvanced → VAE Decode + VAE Decode Audio → Create Video (24 fps) → Save Video
注意 RemakeConditioning 同时向 BasicGuider 提供 positive conditioning、向采样器提供初始 latent(其第二个输出名为 latent),而 RemakeNoise 也需要读这份 conditioning 来计算噪声形状。
3.4 两种模式只改两处
| swap | edit | |
|---|---|---|
| LoRA | viggle_remake_swap_comfyui.safetensors |
viggle_remake_edit_comfyui.safetensors |
| ManualSigmas | 1.0, 0.990476, 0.965243, 0.923077, 0.8, 0.631579, 0.0 |
1.0, 0.983607, 0.96, 0.923077, 0.857143, 0.705882, 0.0 |
这两组 sigma 与 inference/sample.py 中的 SIGMAS 字典逐位一致,是六步采样在视频流 sigma 空间的取值。sample.py 还会对音频调度器做一次 shift 变换(sh(u, s) = s*u / (1 + (s-1)*u),视频 12.0、音频 3.0),ComfyUI 侧则由节点内部处理,因此工作流里只需要填视频这组数字。
四、用自己的片段:Viggle Remake Conditioning 的输入
Viggle Remake Conditioning 的输入与 sample.py 的命令行参数一一对应。下表结合 nodes.py 的 INPUT_TYPES 补充了类型、默认值与源码行为:
| 输入 | 类型 | 默认值 | 说明 |
|---|---|---|---|
clip |
CLIP | 必填 | 文本编码器,type 用 minimax |
vae |
VAE | 必填 | 视频 VAE |
audio_vae |
VAE | 必填 | 音频 VAE(minimax_h3_audio_vae_fp32) |
source |
IMAGE | 必填 | 源片段帧,按原样使用,需先转 24 fps |
prompt |
STRING(多行) | 必填 | 六段式提示词,逐字使用 |
ref_1 |
IMAGE | 必填 | <Picture 1> |
pins |
STRING | "" |
每张参考图一个输出帧号,如 12, 190;留空则只作参考 |
frames |
INT | 124(90–345,步长 17) |
输出长度,17n+5 |
short_edge |
INT | 480(480–736,步长 32) |
480 对应 832×480,736 对应 1280×736 |
audio |
AUDIO | 可选 | 输出保留的音轨,通常来自 Get Video Components;不接则为静音 |
ref_2 … ref_4 |
IMAGE | 可选 | <Picture 2> … <Picture 4> |
关于 source:节点里的判断是,若短边不等于 short_edge、或宽高不是 32 的倍数,就按 16:9 类画布做 cover 裁剪。源码用 long = se * 16 // 9 // 32 * 32 得到长边(480 → 832,736 → 1280),再用 comfy.utils.common_upscale(..., "bicubic", "center") 缩放。sample.py 的做法等价,只是直接调用 ffmpeg(ffmpeg -i in.mp4 -r 24 source.mp4 是文档给的手工预转换命令)。
pins 的解析是 [int(p) for p in pins.replace(",", " ").split()],逗号和空格都能用。节点有三条断言,违反会直接报错:
assert (nf - 5) % 17 == 0, f"frames must be 17n+5, got {nf}"
assert len(pins) in (0, len(refs)), f"give one pin per reference image or none: ..."
assert all(0 <= p < nf for p in pins), f"pins must be in [0, {nf})"
还有一条针对源帧数的检查:source = source[:nf] 之后断言帧数足够,不足时会提示实际帧数与所需帧数。
五、四个节点的源码级行为
理解这四个节点,就能理解 ComfyUI 版本与 sample.py 的差异边界。
5.1 纯文本呈现与 2 fps 时间戳标签
sample.py 的提示词构造方式是:先给源视频打上按 2 fps 分块的标签,再给每张参考图一个 <Picture N>,最后拼上提示词,每一段单独 tokenize 后拼接。节点复刻了这一路径:
segments = ["<Video 1>: ", *["<%.1f seconds>" % s for s in stamps(nf)],
*["<Picture %d>: " % (i + 1) for i in range(len(refs))], prompt]
tokens = {"qwen3vl_32b": [[t for s in segments for t in clip.tokenize(s)["qwen3vl_32b"][0]]]}
positive = clip.encode_from_tokens_scheduled(tokens)
其中 stamps(nf) 按 FPS, AUDIO_SR, AUDIO_LATENT_FPS = 24, 32000, 40 计算:每 12 帧取一个索引,两个一对合并,标签取这对的均值时间,格式为 "%.1f"。源码注释还专门说明 %.1f 采用银行家舍入(round half to even),所以第一个块是 <0.2 seconds> 而不是 <0.1 seconds>。这就是“文本侧呈现”与股票节点不同的地方:参考图与源视频都只以文本标签形式进入条件编码,不额外构造视觉 token。
5.2 参考图与关键帧的两次编码
节点先把源帧送入 VAE 得到 latent,构造 minimax_refs 块列表;然后对每张参考图按各自短边(取整到 32,不设面积上限)编码为 image 块。
关键帧则分配到输出画布上:
for i, (r, p) in enumerate(zip(refs, pins)):
if (r.shape[1], r.shape[2]) != (h, w):
r = lanczos(r, w, h) if i == 0 else cover(r, w, h)
keyframes.append({"resolved_frame_index": p, "latent": vae.encode(r)})
即第一张拉伸、其余 cover 裁剪。这与 sample.py 里 pipe.image_processor.resize 加手工 LANCZOS 计算 (src - dst) // 2 居中的做法保持同一语义,文档也特意指出这不是 VaeImageProcessor 的 "crop" 算法(某些宽高比上会差一个像素)。
5.3 Keyframe Until 是怎么“丢帧”的
RemakeKeyframeUntil 并不重算图,而是在 DIFFUSION_MODEL 包装层里做条件收缩:
m.add_wrapper_with_key(comfy.patcher_extension.WrappersMP.DIFFUSION_MODEL, "viggle_remake_keyframe_until", release)
release 里判断 float(timestep.flatten()[0]) / 1000 < keyframe_until,成立时把 minimax_payload 的 keyframes 与 layout 置空,并把 refs 里的 latent 转成 cond_video_latents / cond_audio_latents。也就是说,关键帧只在 sigma 尚高的前若干次前向中参与,之后退化为纯参考条件。默认 0.9 正好覆盖六步中的前四步,与 sample.py 的 --keyframe-until 0.9(判据为 1 - t >= keyframe_until)对应。
5.4 Noise:为什么同 seed 能得到同一段视频
RemakeNoise 的关键在于抽样顺序。sample.py 用同一个 torch.Generator 先生成参考图与关键帧的噪声,再生成目标噪声;ComfyUI 若直接用默认噪声节点,顺序与形状都不同,同 seed 也不会得到同一结果。节点把这件事显式化了:
c = positive[0][1]
skip = [b["latent"].shape for b in c.get("minimax_refs", []) + c.get("minimax_keyframes", []) if "latent" in b]
return (Noise(seed, skip),)
Noise.generate_noise 用一个 CPU generator,先按 skip 里的每个形状空抽一次 torch.randn,再对目标 latent 的每个分量生成噪声并组成 NestedTensor。这样 seed 的语义就与参考脚本对齐。
5.5 Prefix:跳接上一段的帧
RemakePrefix 用于把上一段渲染的帧作为本次渲染的开头“干净”帧。它的做法是把这些帧 VAE 编码后写入 latent 前部,并把对应的 noise_mask 置 0:
n = k // 17 * 5
assert k % 17 == 0 and n < video.shape[2], ...
clean = vae.encode(torch.cat([px, px[-1:].repeat(5, 1, 1, 1)]))[:, :, :n]
video, vmask = video.clone(), vmask.clone()
video[:, :, :n] = clean.to(video)
vmask[:, :, :n] = 0
注释解释了补 5 帧再切前 5m 的原因:VAE 以 17 帧为单位编码并丢掉最后 3 个 latent,因此需要 pad 到 17m + 5。prefix_at = -1 表示取上一段的最后 prefix_frames 帧。MCP 的 ComfyUI worker 正是这样调用它的:mcp/comfy_worker/remake_worker.py。
5.6 音轨:为什么不用股票音频编码
这是文档里最容易忽略但影响很大的细节。Viggle Remake Conditioning 自己编码音轨:
n = round((nf + 1) / FPS * AUDIO_SR)
wav = torch.zeros(2, n)
...
wav = torch.nn.functional.pad(wav, (0, -n % 800))
za = audio_vae.encode(wav[None].movedim(1, -1))[..., :round(nf / FPS * AUDIO_LATENT_FPS)]
要点有三:
- 目标长度是
nf/24秒,实际 pad 到(nf+1)/24秒,再裁到目标长度; - 单声道会
repeat(2, 1)成双声道,非 32 kHz 会经comfy.audio.resample重采样; - 末尾零填充到整 800 采样点后再编码。
第三条是核心:ComfyUI 股票音频编码会把音轨裁剪到整 800 采样块,且从两端各裁一点,最多造成 400 采样点的偏移,相当于把 latent 移动了“换一条音轨”那么多。节点改为只在末尾补零,与 sample.py 一致。
最后构造的目标是一个 NestedTensor:视频 latent 为 torch.zeros(1, 24, (nf - 5) // 17 * 5 + 2, h // 16, w // 16),音频 latent 为刚才编码的结果;noise_mask 中视频全 1、音频全 0——音频因此在整个去噪过程中保持干净,只做“携带”。
六、速度与显存(bf16 + LoRA)
以下数据来自文档在单张 B200、832×480、226 帧、两张固定关键帧下的实测:
| ComfyUI | sample.py |
|
|---|---|---|
| 单次渲染(模型已加载) | 约 95 s(6 步,每步约 13.5 s,另加编解码) | 约 58 s |
| 首次渲染(含加载) | 约 2.5–3 min | 约 2 min |
| GPU 显存 | 80 GB 内可满速运行 | 87.2 GiB allocated,91.0 GiB reserved(832×480,226 帧) |
| 系统内存 | 约 130 GB |
ComfyUI 按需把权重搬上 GPU、其余留在系统内存,所以它能在比 sample.py 更小的卡上运行。文档还给了封顶实验:把 ComfyUI 限制到 92 GiB 与 76 GiB(183 GB 卡上用 --reserve-vram),峰值分别为 92.8 与 76.8 GiB,且每一步耗时与不封顶时相同。卡更大时它会保留更多常驻权重(B200 上 120–135 GB)。
七、与 sample.py 的四处差异
这一节是文档最技术性的部分,也是决定画质与可复现性的关键。
7.1 必须用 LoraLoaderBypassModelOnly
普通 LoraLoaderModelOnly 会把 LoRA 合并进 bf16 权重,而在 bf16 精度下大部分更新会被舍入掉:文档给出的数字是注意力与 MLP 层中平均只有 37–73% 的更新存活。在 swap 示例上,合并后渲染锐度低 7%,与 sample.py 的差距也更大(21.2 dB 对 24.7 dB)。bypass 加载器把 LoRA 保留为独立分支,代价是每次渲染多 2–3% 的时间。
这也解释了为什么二进制的 int8/GGUF 单文件反而没有这个问题:它们是在 fp32 下做一次合并、再直接量化,中间不产生 bf16 副本。
7.2 同 seed 同视频,但不是同像素
Viggle Remake Noise 让同 seed 抽到与 sample.py 相同的起始噪声,所以两者“结果相同”。但不是逐位相同,因为注意力 kernel 与算子顺序不同。示例上的距离是:ComfyUI 的帧相对 sample.py 为 41.6 dB(edit) 与 24.7 dB(swap)。文档明确提醒 swap 是敏感项:仅在 ComfyUI 内部,让文本嵌入发生与 bf16 舍入同量级的变化,就能让 swap 移动约 27 dB。锐度在 sample.py 的 3% 以内,固定关键帧的复现误差在 0.2 dB 以内。
7.3 注意力后端:慢的原因与一个可选优化
ComfyUI 会先尝试 flash attention,而 sample.py 用的是 cuDNN attention。在 B200 上,把 comfy/ops.py 里 SDPA_BACKEND_PRIORITY 中的 cuDNN 提到最前,可把单步时间从 13.5 s 降到 6.8 s,且渲染与 sample.py 的接近程度相当(25.4 与 41.7 dB)。文档强调这仅在 B200 上测过,属于可选调优而非常规配置。
7.4 音频的补零差异
见 5.6 节:节点在末尾补零,股票编码从两端裁剪,最多偏移 400 采样点。
八、小显存:int8 与 GGUF 单文件
对于 80 GB 以下的卡,每种模式都额外提供单文件 transformer。每个文件都是基础 transformer 先合并该模式的 LoRA、再量化的产物,同时替代基础扩散模型和 LoRA 加载器,因此不要在其上再叠一个 Remake LoRA。
合并是在 fp32 下做一次,然后直接量化,中间没有 bf16 副本,所以这些文件不会像 LoraLoaderModelOnly 那样丢掉部分 LoRA。
8.1 文件清单
| 文件 | 大小 | ComfyUI 节点 |
|---|---|---|
| int8/viggle_remake_swap_pruned_int8_convrot.safetensors | 21.0 GB | Load Diffusion Model(核心) |
| int8/viggle_remake_edit_pruned_int8_convrot.safetensors | 21.0 GB | Load Diffusion Model(核心) |
| gguf/viggle_remake_swap-Q8_0.gguf、gguf/viggle_remake_edit-Q8_0.gguf | 各 22.3 GB | Unet Loader (GGUF),来自 ComfyUI-GGUF |
| gguf/viggle_remake_swap-Q6_K.gguf、gguf/viggle_remake_edit-Q6_K.gguf | 各 17.6 GB | Unet Loader (GGUF) |
| gguf/viggle_remake_swap-Q4_K_M.gguf、gguf/viggle_remake_edit-Q4_K_M.gguf | 各 14.3 GB | Unet Loader (GGUF) |
8.2 量化布局
int8 使用 ComfyUI 原生 int8 格式,布局与 Comfy-Org 的 minimax_h3_fl2va_pruned_int8_convrot 相同:
- 50 个 block 中,每个 block 的四个注意力/MLP 线性层为 int8,按输出行一个 scale(
int8_tensorwise、convrot、group 256); - 其余张量保持基础文件的精度;
- adaLN 保持 Comfy-Org 的紧凑
pruned形式不变,因为 LoRA 不触及 adaLN。
GGUF 量化同样这四个线性层:
- Q8_0、Q6_K 对四层都用该类型;
- Q4_K_M 混用:qkv 投影用 Q5_K,第二层 MLP 用 Q6_K,其余两层用 Q4_K,与 llama.cpp 对同类层的处理一致;
- patch embedding、输出层、adaLN、norm、token refiner、condition projection 保持未量化。
GGUF 文件带的是 wan 架构标签。 ComfyUI-GGUF 只检查该标签是否在它接受的名字列表里,而 ComfyUI 本身是从张量名识别出 MiniMax-H3 的,所以这个标签不影响加载。
8.3 安装
cd ComfyUI
# int8: no extra node needed
hf download Viggle/Viggle-Remake --include "int8/*" --local-dir ./Viggle-Remake
mv Viggle-Remake/int8/*.safetensors models/diffusion_models/
# or GGUF, for example Q6_K
git clone https://github.com/city96/ComfyUI-GGUF custom_nodes/ComfyUI-GGUF
pip install -r custom_nodes/ComfyUI-GGUF/requirements.txt
hf download Viggle/Viggle-Remake --include "gguf/*Q6_K*" --local-dir ./Viggle-Remake
mv Viggle-Remake/gguf/*.gguf models/diffusion_models/
文本编码器、两个 VAE、节点包与示例输入都与前面的 ComfyUI 章节相同。
8.4 只改两个节点
- 删除
Load Diffusion Model与LoraLoaderBypassModelOnly; - 添加
Load Diffusion Model加载 int8 文件,或添加Unet Loader (GGUF)加载.gguf; - 把它的
MODEL输出接到Viggle Remake Keyframe Until。
其余全部保持不变。swap 文件配 swap 的 sigma,edit 文件配 edit 的 sigma。
九、按显存选文件
文档的测量都在 B200 上进行,并用第二个进程占住卡上其余显存,使 ComfyUI 只看到标称的空闲量。测试对象是 edit 示例、226 帧、两张固定参考、bf16 文本编码器;除非标注了参数,否则使用默认设置。
| 卡 | 832×480 | 1280×736 |
|---|---|---|
| 12 GB | Q4_K_M 或 Q8_0 配 --reserve-vram 8;int8 仅 124 帧 |
未测试 |
| 16 GB | int8;Q4_K_M 或 Q6_K 配 --reserve-vram 6 |
Q4_K_M 配 --reserve-vram 10:124 帧;226 帧即使 --reserve-vram 12 也中止 |
| 24 GB | int8 或 Q4_K_M;Q6_K 或 Q8_0 配 --reserve-vram 6 |
Q4_K_M 或 Q8_0 配 --reserve-vram 20;int8 仅 124 帧 |
| 32 GB | int8 或 Q8_0 | Q8_0 配 --reserve-vram 20;int8 最多 175 帧 |
| 48 GB | 任意 | Q8_0;int8 在 226 帧时显存不足 |
| 80 GB | bf16 + LoRA,即前面 ComfyUI 章节的做法 | bf16 + LoRA;int8 在 226 帧时显存不足 |
几条选择原则:
- 832×480、16 GB 及以上优先 int8。 在这些示例上它与 Q8_0 得分相同,且不需要任何参数。ComfyUI 用动态 VRAM 加载它:需要时把每个权重搬上卡,其余留在系统内存。
- 12 GB,或 1280×736 且不足 80 GB,用 GGUF 配
--reserve-vram。 这样 ComfyUI 会把权重留在系统内存、每步流式送入。代价不大:832×480 时每步 15.9 s,权重常驻约 14 s;1280×736 时每步 67–72 s,对比 64 s。 - 为什么 GGUF 需要这个参数:ComfyUI-GGUF 会按 ComfyUI 的显存估算尽量把模型放上卡,而对 MiniMax-H3 这个估算漏掉了参考图与关键帧的 token。当权重放得下、激活放不下时,ComfyUI 会以
CUDA error: invalid argument中止,而不是回退到 offload。--reserve-vram N保留 N GB 给激活;若仍中止就调大 N。 - 为什么 int8 在 1280×736 × 226 帧止步:没有 CUDA 13 版 PyTorch 时,comfy-kitchen 回退到普通 int8 matmul,它整层保留 32 位累加和并分块组装输出,单层瞬时显存可达输出的数倍。在 1280×736 × 226 帧下即使 80 GB 空闲也不够,而 bf16 + LoRA 能在 80 GB 内跑、Q8_0 配
--reserve-vram 20能在 24 GB 内跑。 - 32 GB 卡 + CUDA 13:在 RTX 5090 上用 torch 2.9.1+cu130,int8 可渲 1280×736 至 345 帧(约 260 s 每步),走的是 MCP 的 ComfyUI worker mcp/comfy_worker,它还会把每个 block 的前馈按行分块,并以
--vram-headroom 4启动 ComfyUI。 - Q4_K_M 是最小的文件,但它与参考的差距肉眼可见(见下一节)。
关于最后一点,源码可以互相印证:mcp/comfy_worker/remake_worker.py 把 H3.MLP.forward 换成按 FF_ROWS = 16384 行分块的版本,注释写明“345 帧、736 画布下单个 fc1 的 bf16 输出就有 11 GiB”,并说明 int8 会逐行量化激活、输出等价。同时该文件在启动参数里默认注入 --vram-headroom 4。
十、质量对比
每个文件都用 seed 0、832×480、226 帧渲染两个示例,并与 sample.py 的 bf16 + LoRA 结果对比。第一组比较在同一 diffusers 管线内进行,因此只有权重不同。PSNR 覆盖所有帧;锐度用拉普拉斯方差,以参考的百分比表示。
| 权重 | swap(固定关键帧) | swap(仅参考) | edit(固定关键帧) | edit(仅参考) | 锐度 |
|---|---|---|---|---|---|
| bf16 + LoRA(参考) | — | — | — | — | 100% |
| int8 | 27.2 dB | 34.0 dB | 46.8 dB | 49.7 dB | 100–104% |
| Q8_0 | 26.9 dB | 36.6 dB | 49.8 dB | 52.0 dB | 99–102% |
| Q6_K | 24.6 dB | 30.5 dB | 44.6 dB | 46.0 dB | 99–102% |
| Q4_K_M | 20.6 dB | 23.8 dB | 38.3 dB | 40.7 dB | 97–109% |
| 同 bf16 权重、不同舍入(量级参考) | 29.6 dB | 50.4 dB | 101% |
解读要点:
- “固定关键帧”是示例的运行方式;“仅参考”去掉了关键帧固定,此时全靠 LoRA 承担编辑,是对量化文件更严苛的测试。
- 每个文件都能完成编辑:涡轮机被移除、披萨师傅被替换;锐度在参考的 −3% 到 +9% 之间。
- swap 片段很敏感:最后一行是同一模型把 bf16 权重换一种略有差异的舍入,仅此一项就把 swap 推到 29.6 dB。因此 swap 上几 dB 的差异应当当作噪声看,edit 列才更能区分格式。
- 在 ComfyUI 内,以
LoraLoaderBypassModelOnly应用 LoRA、同一张图比较:int8 为 24.0 dB(swap)/ 46.5 dB(edit);Q8_0 为 23.8 / 48.9;Q6_K 为 20.0 / 43.6;Q4_K_M 为 20.0 / 38.5。作为对照,在 bf16 下合并 LoRA 的LoraLoaderModelOnly为 22.0 / 46.1。所有渲染的联络表(contact sheet)肉眼看都与参考一致。 - 1280×736(edit、226 帧、ComfyUI 内对比 bypass-LoRA bf16):Q8_0 为 42.8 dB,Q4_K_M 为 31.6 dB;锐度分别为参考的 101% 与 98%。
- 卡的大小与 offload 不改变输出:同一文件、同一 seed,在 12 GB 预算下与整卡空闲时得到相同帧。
十一、文本编码器的三个版本
MiniMax-H3 使用 Qwen3-VL 32B 的前 50 层,Comfy-Org 的文本编码器文件也只包含这些层。它们有三种:
qwen3vl_32b_minimax_h3_bf16(51.5 GB);_int8_convrot(27.1 GB);_nvfp4_awq(15.7 GB)。
ComfyUI 在采样前只跑一次编码器,并以流式方式通过显卡,所以它不决定你需要多大的卡。卡表里除 12 GB 的 int8 跑用 int8 编码器外,其余结果都用 bf16 编码器。
更小的编码器省磁盘与加载时间:16 GB 卡上,用 nvfp4 首次渲染 144 s,bf16 为 192 s。
用每个编码器配 int8 transformer 渲染两个示例,并与 bypass-LoRA 渲染对比:
| 编码器 | edit | swap |
|---|---|---|
| bf16 | 46.5 dB | 24.0 dB |
| int8 | 47.0 dB | 25.0 dB |
| nvfp4 | 46.7 dB | 23.1 dB |
两个更小的编码器都没有带来可测量的损失。社区存在 GGUF 版编码器,但文档说明未做测试。
十二、速度与内存(量化路径)
所有时间来自单张 B200。
- 832×480、226 帧
- 整个文件在卡上时,每个文件每步约 14 s,六步约 85 s;
- 权重从内存流式送入时,每步 15.9–17.4 s;
- 首次渲染(含从本地 NVMe 加载 bf16 文本编码器)从排队到成片 170–210 s。
- 1280×736、226 帧:每个文件与 bf16 + LoRA 都是每步 64–72 s,单次渲染 510–585 s。
- 未对消费级显卡计时,预期更慢。
- 系统内存(ComfyUI 进程的峰值常驻内存,内存映射的权重文件也计入):
- 832×480:47–55 GB,与编码器无关;
- 1280×736 + int8 或 GGUF:55–80 GB;
- 1280×736 + bf16 与 LoRA:127 GB。
- int8 跑在 comfy-kitchen 的回退路径上:它运行在使用 CUDA 12.8 编译的 PyTorch 上,此时优化过的 int8 kernel 被禁用,ComfyUI 会打印 “You need pytorch with cu130 or higher”。回退路径输出正确,但优化 kernel 未做测量。
十三、注意事项与验证清单
文档列出的前提与限制:
- 测试环境:ComfyUI 0.42.0、ComfyUI-GGUF 提交
6ea2651、PyTorch 2.9.1+cu128、comfy-kitchen 0.2.40,且仅在 B200 上验证。 - 质量数据只来自两个示例片段;卡表只来自 edit 示例。
- 小显存是模拟出来的:ComfyUI 仍把 B200 的 183 GB 报为总显存,因此运行在普通 VRAM 模式。在真实的 12–24 GB 卡上,ComfyUI 可能自行选择低显存默认值,上述参数可能需要调整。
- GGUF 运行会打印一条无害警告:
Mismatch dtype between input and weight … Cannot dispatch to fused implementation,来自保持 F32 的 norm 权重。
结合源码,还可以整理出一份自查清单:
- 扩散模型是否为
fl2va、CLIP 的 type 是否为minimax、是否分别加载了视频 VAE 与音频 VAE; - LoRA 是否用
LoraLoaderBypassModelOnly,强度是否为 1.0;若换成 int8/GGUF 单文件,是否已删除 LoRA 加载器; frames是否满足17n+5且在 90–345 内(节点与sample.py都会断言);pins是否与参考图数量一致(要么 0 个,要么每图一个),且都落在[0, frames);- sigma 是否与模式匹配(swap 与 edit 的最后一档分别是 0.631579 与 0.705882);
- 源片段是否已 24 fps;若不是画布尺寸,节点会 cover 裁剪,因此构图会变化;
- 若提示词里的时间戳对不上,检查
frames是否被改动——示例提示词是按 226 帧写的; - 12 GB 或 1280×736 出现
CUDA error: invalid argument,先调大--reserve-vram。
十四、相关文件索引
- 节点实现:comfyui/ComfyUI-Viggle-Remake/nodes.py
- 节点注册:comfyui/ComfyUI-Viggle-Remake/init.py
- LoRA 重打包:comfyui/to_comfyui.py
- 图形界面工作流:comfyui/workflows/remake_swap_ui.json、comfyui/workflows/remake_edit_ui.json
- API 工作流:comfyui/workflows/remake_swap_api.json、comfyui/workflows/remake_edit_api.json
- 参考采样器:inference/sample.py
- 示例脚本、提示词与输入:examples/demo.sh、examples/prompts、examples/inputs
- 量化权重:int8、gguf
- 32 GB 卡的 ComfyUI worker:mcp/comfy_worker
- 项目总览与命令行快速开始:README.md
- 涂帧、关键帧与提示词写法:PROMPTING.md
以上内容均以仓库中的文档、工作流 JSON 与节点源码为依据;具体数值(PSNR、耗时、显存)来自 COMFYUI.md 记录的 B200 实测,换到其他硬件时应视为参考量级而非保证值。