ComfyUI-MiniMaxH3-SafeSageAttention

MiniMax H3 Sage Safe

一个与 ComfyUI-KJNodes 共存的轻量伴生节点，用于修复 RTX 4090（SM89）运行 MiniMax H3 长序列 SageAttention 时可能出现的无报错画面损坏。

它不会修改 KJNodes 文件，也不会覆盖 KJ 的原节点。只有接入本节点的工作流使用安全调度；其他工作流仍然使用原来的 KJNodes 节点。

解决什么问题

在本次独立节点的 1080P 实测中，融合 QKV 投影生成的 V 是一个大跨度视图：

shape:  (1, 230957, 56, 128)
stride: (4966499328, 21504, 128, 1)

SageAttention 2.2.0 的 FP8 CUDA 转置/量化内核使用 32 位地址偏移。该视图的最大相对偏移为 4,966,484,991，超过 UINT32_MAX = 4,294,967,295，地址会回绕并读取错误的 V 行。任务不会抛出异常，但视频尾部可能变灰或出现噪声。

本节点会在进入该内核前检查完整的 shape/stride：

• 地址安全时保持 KJNodes 原有的零拷贝高速路径；
• 只有可能溢出时，才在 Q/K 量化并释放后将 V 物化为连续张量；
• 如果连 SageAttention 补齐到 64 后的输出都无法由 32 位地址表示，则明确报错，不生成静默损坏的视频。

运行要求

• NVIDIA RTX 4090 或其他计算能力为 SM89 的 GPU；
• 支持 MiniMax H3 的 ComfyUI；
• 已安装并能正常加载 ComfyUI-KJNodes；
• KJNodes 中存在 MiniMaxH3MemoryEfficientSageAttentionPatch 及其新版长序列 Q/K 内核；
• 已安装并能被 KJNodes 加载的 SageAttention 与 Triton。

最终 GPU 验证环境：

GPU:            NVIDIA GeForce RTX 4090 / SM89 / 48 GiB
Driver:         580.95.05
ComfyUI:        0.33.0
Python:         3.12.11
PyTorch:        2.13.0+cu130
SageAttention:  2.2.0
KJNodes HEAD:   3f20054214fec9f9234fd3841ae6f1e4287948f6
Video:          1088x1952 / 362 frames

本节点会在执行时检查 KJNodes 私有运行符号和 GPU 架构；不兼容时会直接给出说明，不会静默退回到不安全路径。

安装

进入 ComfyUI 的 custom_nodes 目录：

git clone https://github.com/liaowu-boos/ComfyUI-MiniMaxH3-SafeSageAttention.git

然后完整重启 ComfyUI。这个包没有额外的 pip 依赖，也不会替你安装或修改 PyTorch、SageAttention、Triton、KJNodes。

手动安装并与 KJNodes 共存

目标机的 custom_nodes 下应同时保留两个并列目录：

custom_nodes/ComfyUI-KJNodes/
custom_nodes/ComfyUI-MiniMaxH3-SafeSageAttention/

不要覆盖、删除或直接改写已有的 KJNodes 安装；本包不是 KJNodes 的替代品。复制或 clone 本包后必须完整停止并重启 ComfyUI，仅刷新网页不够。本轮验证使用 KJNodes 3f200542；其他版本会在运行时检查所需私有符号，不兼容时明确报错。

手动安装和运行本节点不需要 Comfy Registry Key。Registry Key 只用于发布者上传节点，请将它保存为 GitHub Actions Secret，不要写进工作流、源码或提交到仓库。

工作流接法

只把 1080P 放大工作流里的 KJ H3 Patch 节点替换为：

PathchSageAttentionKJ
        ↓
MiniMax H3 Safe SageAttention Patch
        ↓
EasyCache

永久节点类型 ID：

LiaowuMiniMaxH3SafeSageAttentionPatch

不要在同一条 MODEL 链路中同时串联下面两个节点：

• KJ 原版 MiniMax H3 Mem Eff Sage Attention Patch
• 本包 MiniMax H3 Safe SageAttention Patch

工作流保存的是节点类型 ID。只有包含 LiaowuMiniMaxH3SafeSageAttentionPatch 的工作流使用本包；仍引用 MiniMaxH3MemoryEfficientSageAttentionPatch 的工作流继续走 KJ 原实现。1080P 链只替换 KJ 的 MiniMax H3 Mem Eff Sage Attention Patch，前面的 PathchSageAttentionKJ 保留；不要把 KJ H3 Patch 和本安全节点串在同一条 MODEL 链上。

720P 或其他原本稳定的工作流可以继续使用 KJ 原节点。本包不会改变 KJNodes 的全局函数、节点映射或其他工作流。

可直接导入的最小接线示例位于 examples/minimax_h3_1080_safe_workflow.json。它只展示从 UNETLoader 到 EasyCache 的 MODEL 链，不包含视频、提示词、latent 包或保存节点，也不会携带本次测试素材。将这段 MODEL 链接入你自己的 MiniMax H3 工作流即可；示例中的 KJNodes 节点仍要求预先安装 KJNodes。

显存与 GPU 验证

正常地址安全任务不会复制 V。本轮 1080P 的危险 V 视图会增加约 3.08 GiB 临时 FP16 存储；复制发生在 Q/K 量化并释放之后。

最终验证结果：

• 720P / 1.5 倍冷启动完整生成通过，耗时 16:25；
• 在未修改、工作区干净的 KJNodes 3f200542 上，1080P / 2.25 倍零缓存冷启动完整生成通过，耗时 49:39；
• 1080P 输出为 1088×1952 / 362 帧 / 24 fps / 15.08 秒，全部帧可解码；
• 原损坏输出从第 318 帧开始有 44 个灰色尾帧；最终输出对应的最后 44 帧没有灰帧，最低灰度标准差为 63.29；
• 撤回先前的 KJ 本地修复前后，两次独立节点 1080P 输出逐帧 SSIM = 1.000000；
• 720P sampled latent 为 34.55 MiB，1080P 为 81.33 MiB，大小约为 2.35×，与 latent 空间网格从 44×80 增至 68×122 的元素比例 2.3568× 一致。这是分辨率增长的正常结果，不是 latent 保存损坏。

开发测试

python -m unittest discover -s tests -v
python -m py_compile __init__.py safe_sageattention.py

CPU 测试使用 PyTorch meta tensor 覆盖真实的巨大 shape/stride，不会分配对应显存或内存。发布包已在 RTX 4090 上完成 720P 与原始 KJNodes 基线下的 1080P 冷启动完整生成。

本包会调用 KJNodes 的内部 MiniMax/SageAttention 接口。为了避免接口变化后继续输出错误结果，缺少必要符号或 Triton 时会主动失败。每次升级 KJNodes 后，建议先运行一次 720P 和 1080P 回归；本 README 记录测试所用 KJ commit。

上游与许可证

调度逻辑改编自 ComfyUI-KJNodes，本项目遵循 GPL-3.0。底层问题和最小上游修复见 KJNodes PR #748。详细归属见 NOTICE。

---

English summary

This is an isolated, SM89-only companion node for KJNodes' MiniMax H3 memory-efficient SageAttention path. It guards SageAttention 2.2.0's fused FP8 V quantizer against 32-bit input-offset wrap on long, strided QKV views. Safe geometries retain the original zero-copy behavior; unsafe V is cloned into canonical contiguous storage only after Q/K quantization and release. KJNodes remains a required runtime dependency, and its global functions and node mappings are not modified. GPU validation passed a 720P cold run in 16:25 and a zero-cache 1080P (1088×1952, 362 frames) cold run in 49:39 on clean KJNodes commit 3f200542, with no gray frames in the affected final 44-frame interval.