Node packVerificadoExterno

minimax-h3-chunk-star7

VRAM-efficient MiniMax H3 for ComfyUI: QKV/RoPE/MLP activation chunking, automatic OOM chunk reduction, and CK/SLA/Sol/Hybrid attention for SM75 and SM80+ GPUs.

Fontegithub.com/star7code/minimax-h3-chunk-star7

Mantenedor@star7codeA · adoptionnota

Perfil do pacote

Status: Verificado
Publicador: @star7code
Fonte: GitHub
Estrelas: 97

README

MiniMax H3 Activation Chunk & Attention Acceleration - Star7

中文说明 · English · 实测记录 · 示例工作流

This ComfyUI project helps MiniMax H3 run high-quality, long-duration video generation on GPUs with limited VRAM. Its core node provides independent QKV, RoPE, and MLP activation chunking together with a selectable attention backend. It does not change the sampler, sigma schedule, latent layout, VAE, duration, frame count, or output resolution.

Attention choices include preserving an upstream backend, Comfy Kitchen INT8, architecture-specific SLA/Sol sparse attention, and step-level CK/Sparse/CK Hybrid modes. The package also includes compact reference-image, reference-video, and prompt-loading helpers.

This is an independent community project. MiniMax, ComfyUI, Comfy Kitchen, KJNodes, LightX2V, and NVIDIA are trademarks or projects of their respective owners.

中文说明

让高画质、长时长 MiniMax H3 视频在有限显存的显卡上高效运行。

快速看懂

核心节点同时提供 QKV / RoPE / MLP 激活分块和注意力选择。
QKV 投影、RoPE 与 MLP 扩展激活沿 token 维分块计算，使每次只需保留当前分块的中间张量，分别避免这三处临时工作集按完整长序列规模展开；显存不足时还可只降低发生 OOM 的分块大小。
分块降低的是推理临时激活峰值，不减少模型权重、帧数或 token，也不改变采样器、latent、VAE、时长和输出分辨率。
注意力可选择传入模型已有实现、Comfy Kitchen INT8、SLA、Sol，以及 CK/Sparse/CK Hybrid；SLA 仅计算路由选中的 K/V 块，Sol 以选中块精确计算和未选中块质心近似替代完整稠密计算，SM75 与 SM80+ 均提供对应路径。

主要功能

功能	说明
QKV / RoPE / MLP 独立分块	分别控制三处临时显存峰值，保留 MiniMax H3 原 block、权重、LoRA 和条件布局
智能显存降档	仅在可缩小的分块阶段 OOM 时，将对应分块值减半重试，其他参数保持不变
多种注意力后端	支持 `existing`、Comfy Kitchen INT8、SLA、Sol 和 CK/Sparse/CK Hybrid
H3 W4A8 模型支持	增强载入保留 `asym_w4a8_int8` 量化布局；SM75 提供原生码本 W4A8 线性层优化，可搭配 CK 分块与 VEDA
架构专用稀疏内核	SM75 使用随节点分发的原生 CUDA 内核；SM80+ 使用 Triton 或 NVIDIA 官方 Sol-Attn 路径
数值检查与定位	在完整 Transformer block 和 H3 视频/音频输出处检查 NaN/Inf，并提供 QKV、attention、`out_proj`、MLP 分段诊断
轻量辅助节点	附带参考图像、参考视频和提示词载入；支持将对应文件直接拖入节点，参考图像可按常用横竖比例自动进行最大保留裁切，且不影响核心模型补丁

工作原理

激活分块

MiniMax H3 长序列推理主要存在三个可独立控制的临时显存峰值：

QKV projection；
RMSNorm -> split-half RoPE (Q/K)；
fc1 -> SwiGLU -> fc2 MLP 扩展激活。

本节点沿 sequence/token 维切分这些行独立计算，并将结果写回原有输出布局。RoPE 原位写回 Q/K，MLP 输出继续交给上游 block；分块不改变公式、token 顺序或条件结构。

分块的作用是降低临时工作集，而不是减少计算量。如果任务原本可以完整驻留显存，分块不一定更快；当原任务会 OOM、进入共享显存或频繁换页时，分块才更可能改善实际吞吐。

SLA

SLA 按 LightX2V 契约使用 Q=128、K=64 动态 Top-K 块路由。目标视频查询通常只保留约 15% 的 K 块参与 QK/PV，online softmax 状态和最终累积保持 FP32。

SM75 原生内核对目标音频查询块执行完整注意力。SM80+ 在保留边界路由的同时，以量化前 Q/K/V 对参考音频和生成音频的查询范围执行完整注意力并覆盖稀疏结果；视频查询仍使用 SLA 稀疏计算。

SLA 建议配合 MiniMax H3 Turbo SLA LoRA 使用，以获得更适合该稀疏模式的长时序表现。

Sol

Sol 使用 Q64/K64、tau=1.0 的阈值路由。被选中的 K/V 块执行精确注意力；未命中块不是直接丢弃，而是通过 K/V 质心近似贡献，并与精确块合并到同一次 FP32 online softmax 中。

SM80+ 标准 Sol 模式优先使用 Comfy Kitchen 编译后端，不可用时调用内置 NVIDIA 官方 BF16 接口。SM75 与 SM80+ 的 Star7 All-INT8 路径保留“精确块 + 未命中块质心近似”的完整 Sol 语义，但采用不同的 Q/K/PV 量化和 CUDA/Triton 实现，因此不具备与官方 BF16 路径逐值一致性。

Windows SM75 Sol 使用融合前处理和按 PV 类型分配的共享内存，All-INT8 支持直接消费 QKV 视图。SM80+ 编译后端在布局满足要求时复用输入；标准 Sol 在实际分块且显存紧张时启用 producer，使用当前输入统计量并保留音频完整注意力。旧接口或不支持的投影继续使用直接 Sol 路线，无需新增参数。

SM80+ Sol 保留音频范围的 KV sink，并对参考音频和生成音频查询使用完整注意力结果覆盖；该保护同时适用于官方 BF16、All-INT8 和 Hybrid 中的 Sol 步。

Hybrid

Hybrid 在完整采样 step 之间切换注意力，而不是在一次 Attention 内混合两套内核。默认前后保护区使用 CK，中间采样阶段使用对应的 SLA、Sol 或 VSA。

以常见 4-step 工作流为例：第 1、4 步使用 CK，第 2、3 步使用所选稀疏模式。Hybrid 需要 ComfyUI 提供真实 sigma 调度上下文；无法可靠确定采样步时将终止任务并报告错误。

注意力模式

通用模式

`attention_backend`	作用	适用情况
`existing`	保留传入模型已有的注意力实现	已接 Sage、Low VRAM 或其他注意力补丁；也可保留当前环境默认后端
`comfy_kitchen_int8`	使用 ComfyUI / Comfy Kitchen INT8 注意力	默认选项，兼容性与速度较均衡；属于近似注意力

SM75 / RTX 20 系

`attention_backend`	计算路径	定位
`sla_sm75_qk_int8_pv_fp16`	QK INT8、PV FP16、FP32 softmax/累积	SLA 精度优先
`sla_sm75_all_int8`	QK/PV INT8、FP32 softmax/累积、完整音频查询保护	SLA 性能优先；建议按提示词验证画质与语音
`sol_sm75_all_int8`	Q64/K64，精确块 + 质心近似，PV INT8	SM75 Sol 标准可见模式
`vsa_sm75`	H3 VSA、10% 保留、0%–100% 全采样区间、SM75 专用路径	普通 H3 运行 fine-only；FastH3/VSA 额外使用学习型 coar