minimax-h3-fp16-exact-star7

MiniMax H3 FP16 Exact Fix - Star7

中文说明 · English · 示例工作流

新版示例基于 0919 工作流，顺序为一采 → 可选二采 → 可选人脸修复 → Star7 分块解码；二采与修脸默认关闭。请先选择本机模型文件，需要参考素材时载入自己的图片或视频并取消绕过。修脸需分块项目 2.16.2 或更新版本。

Native FP16 model loading and scoped numerical protection for ComfyUI MiniMax H3 on pre-BF16 architectures. On SM80+, the loader explicitly corrects H3 to native BF16 even when the launcher globally requests FP16. Quantized checkpoints retain eligible INT8/ConvRot kernels instead of being expanded into dense FP16 weights.

The overflow-protection method is derived from the MIT-licensed Amduraznak/minimax-h3-fp16-fix. This package provides a native MiniMax H3 loader, quantization-aware dispatch, architecture checks, scoped ModelPatcher integration, diagnostics, and ComfyUI workflow support.

中文说明

本项目为 MiniMax H3 提供原生 FP16 模型载入和数值保护，主要面向 RTX 20 系（Turing）及其他缺少原生 BF16 Tensor Core 加速的显卡；SM80+ 会自动纠正为原生 BF16。

推荐使用 MiniMax H3 Native FP16 Loader - Star7 载入扩散模型。它在模型创建阶段确定 FP16 计算类型，同时保留原生 MixedPrecisionOps 的 INT8/ConvRot 权重布局，并在推理前安装 MiniMax H3 的 FP16 溢出保护。

对于量化模型，保留 INT8/ConvRot 路径可避免符合条件的线性层被展开为常驻稠密 FP16 权重。实际显存占用仍由模型规模、LoRA、ComfyUI 动态卸载、参考条件和其他节点共同决定。

主要功能

功能	说明
原生 FP16 载入	在 MiniMax H3 模型创建阶段配置 FP16 计算，无需 --fp16-unet
FP16 数值保护	对残差、SwiGLU、attention out_proj 和 MLP fc2 设置对应的 FP32 计算区与溢出保护
量化路径保留	对原生 MixedPrecisionOps 模型保持 force_cast_weights=false，保留可用的 INT8/ConvRot 内核
模型格式识别	支持原生 H3 权重、model.diffusion_model. 外层前缀及文件级 _quantization_metadata
架构检测	SM80+ 始终显式纠正为 BF16；SM61 因 FP16 吞吐较低而跳过修复
生命周期安全	修复仅安装在克隆后的 ModelPatcher 上，模型方法使用弱绑定，避免旧模型被补丁闭包长期持有
运行诊断	报告载入模式、量化格式、强制权重转换状态、权重补丁数量和 DiT block 数量

工作原理

MiniMax H3 在 FP16 下需要保护若干数值敏感位置：

• condition_proj 接收 FP32 输入；
• 50 个 DiT block 的残差流保持 FP32；
• attention 和 MLP 分支的归一化输出以 FP16 进入对应计算路径；
• SwiGLU 点运算使用 FP32；
• attention out_proj 输入先按 64 缩放，投影后以 FP32 恢复；
• MLP fc2 输入先按 256 缩放，投影后以 FP32 恢复；
• H3 原有的 FP32 输出区保持不变。

Exact 指以 2 的整数次幂进行溢出保护；这类缩放不会额外引入普通比例换算的舍入形式。它不表示 FP16、BF16、INT8、ConvRot 与 FP32 会产生逐位一致的输出。

该修复只处理模型计算精度和溢出边界，不修改采样器、sigma、latent、VAE、帧数、分辨率或注意力后端。CK、SLA、Sol 等注意力中的 INT8 QK/PV 计算不会被转换为 FP16。

包含的节点

节点	用途
MiniMax H3 Native FP16 Loader - Star7	推荐节点；从 diffusion_models 载入原生 MiniMax H3，并在模型创建阶段应用 FP16 策略和数值保护
MiniMax H3 FP16 Exact Fix (Legacy) - Star7	已加载 MODEL 的兼容入口；仅用于仍包含该 class ID 的工作流

在 Ampere、Ada、Blackwell 等 SM80+ 架构上，本节点与增强载入节点保持相同策略：显式以 BF16 创建 H3，即使启动器全局开启 --fp16-unet 也只对 H3 自动纠正，不安装 FP16 block 包装。

推荐连接方式

MiniMax H3 Native FP16 Loader - Star7
  -> LoRA Loader（可选）
  -> Attention Patch（可选）
  -> MiniMax H3 Activation Chunk - Star7（可选）
  -> Guider / Scheduler / Sampler

FP16 Loader 与 MiniMax H3 Activation Chunk - Star7 可以分别独立使用：前者负责 FP16 载入与数值保护，后者负责 QKV/RoPE/MLP 激活分块和注意力选择。

仓库提供适用于不同 NVIDIA 架构的通用示例工作流：中文版 · English。新版示例包含多合一条件载入、分块、实时预览、独立 H3 分块解码和默认关闭的可选二采，导入后可直接作为普通工作流使用。载入节点会在 SM75 使用受保护 FP16，并在 SM80+ 自动采用安全 BF16，因此无需再按 RTX 20 系拆分案例。示例工作流还使用以下项目：

• MiniMax H3 Activation Chunk - Star7
• MiniMax H3 Audio Conditioning T8
• ComfyUI-VideoHelperSuite

这些项目是示例工作流的配套节点，不是 FP16 Loader 本身的 Python 依赖。

INT8 / ConvRot 兼容

ComfyUI 原生量化线性层通过 MixedPrecisionOps 保存量化权重及调度信息。本载入器使用 FP16 activation compute，同时对量化模型保持 force_cast_weights=false，因此不会主动把受支持的 INT8/ConvRot 权重转换为稠密 FP16。

模型或载入路径	支持情况
原生 MiniMax H3 稠密 BF16 / FP32 safetensors	支持；以 FP16 operations 创建模型并安装数值保护
原生 int8_tensorwise + ConvRot MiniMax H3	支持；保留量化权重与原生调度
带 model.diffusion_model. 前缀的原生 H3 权重	支持；移除外层前缀后按模型结构识别
使用文件级 _quantization_metadata 的原生 H3 权重	支持；恢复对应 MixedPrecisionOps 配置
`