# ComfyUI-RH-MiniMax-H3

[English documentation](README.md)

RunningHub 的 MiniMax-H3 ComfyUI 音视频扩散节点。DiT、Qwen3-VL 文本/多模态
编码器以及视频/音频 VAE 全部在 ComfyUI 进程内运行，不依赖 SGLang 服务，也不
调用 Diffusers Pipeline。

当前任务感知路径已覆盖 T2VA、FL2VA（首/尾帧生成视频与音频）和 Ref2VA（有序
图片/音频/视频参考）。三条路径均已完成本地合同、打包、采样器、媒体预处理、
节点静态检查和单元测试。Ref2VA 已用完整发布权重完成真实 CUDA 端到端验证。
FL2VA 与 T2VA 共用 FL2VA 分区及同一套编码/采样合同；上线前建议再做一次本地
CUDA smoke。

## 安装

```bash
cd ComfyUI/custom_nodes
git clone <repo-url> ComfyUI-RH-MiniMax-H3
pip install -r ComfyUI-RH-MiniMax-H3/requirements.txt
```

装好后需重启 ComfyUI：节点定义只在进程启动时读取一次。

## 节点清单

全部节点注册 ID 带 `RHMiniMaxH3` 前缀，归入 `RunningHub/MiniMax H3` 分类。
**节点 ID** 是工作流里保存的 `class_type` / `type`，**显示名**是画布上看到的标题。

**`RunningHub/MiniMax H3/loaders`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3DirectModelLoader` | RunningHub MiniMax H3 Model Loader (Direct) |
| `RHMiniMaxH3DirectTextEncoderLoader` | RunningHub MiniMax H3 Qwen3-VL Loader (Direct) |
| `RHMiniMaxH3DirectVAELoader` | RunningHub MiniMax H3 Dual VAE Loader (Direct) |
| `RHMiniMaxH3FL2VAModelLoader` | RunningHub MiniMax H3 FL2VA Model Loader (Direct) |
| `RHMiniMaxH3FL2VATextEncoderLoader` | RunningHub MiniMax H3 FL2VA Qwen3-VL Loader (Direct) |
| `RHMiniMaxH3FL2VAVAELoader` | RunningHub MiniMax H3 FL2VA Dual VAE Loader (Direct) |
| `RHMiniMaxH3Ref2VAModelLoader` | RunningHub MiniMax H3 Ref2VA Model Loader (Direct) |
| `RHMiniMaxH3Ref2VATextEncoderLoader` | RunningHub MiniMax H3 Ref2VA Qwen3-VL Loader (Direct) |
| `RHMiniMaxH3Ref2VAVAELoader` | RunningHub MiniMax H3 Ref2VA Dual VAE Loader (Direct) |

**`RunningHub/MiniMax H3/conditioning`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3T2VATarget` | RunningHub MiniMax H3 T2VA Target |
| `RHMiniMaxH3T2VATextEncode` | RunningHub MiniMax H3 T2VA Text Encode |
| `RHMiniMaxH3UnsupportedConditioning` | RunningHub MiniMax H3 Legacy Unsupported Conditioning (Migration Error) |

**`RunningHub/MiniMax H3/fl2va`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3FL2VAFirstFrameCondition` | RunningHub MiniMax H3 FL2VA First / First+Last |
| `RHMiniMaxH3FL2VALastFrameCondition` | RunningHub MiniMax H3 FL2VA Last Only |
| `RHMiniMaxH3FL2VATarget` | RunningHub MiniMax H3 FL2VA Target |
| `RHMiniMaxH3FL2VAEncode` | RunningHub MiniMax H3 FL2VA Encode |

**`RunningHub/MiniMax H3/ref2va`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3Ref2VAImageReference` | RunningHub MiniMax H3 Ref2VA Image Reference |
| `RHMiniMaxH3Ref2VAAudioReference` | RunningHub MiniMax H3 Ref2VA Audio Reference |
| `RHMiniMaxH3Ref2VAVideoReference` | RunningHub MiniMax H3 Ref2VA Video Reference |
| `RHMiniMaxH3Ref2VATarget` | RunningHub MiniMax H3 Ref2VA Target |
| `RHMiniMaxH3Ref2VAEncode` | RunningHub MiniMax H3 Ref2VA Encode |

**`RunningHub/MiniMax H3/latent`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3EmptyAVLatent` | RunningHub MiniMax H3 Empty AV Latent |
| `RHMiniMaxH3SeparateAVLatent` | RunningHub MiniMax H3 Separate AV Latent |
| `RHMiniMaxH3CombineAVLatent` | RunningHub MiniMax H3 Combine AV Latent |
| `RHMiniMaxH3EncodeVideoAVLatent` | RunningHub MiniMax H3 Encode Video → AV Latent |

**`RunningHub/MiniMax H3/sampling`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3FrameRate` | RunningHub MiniMax H3 Frame Rate (Experimental) |
| `RHMiniMaxH3DualSigmaSampler` | RunningHub MiniMax H3 Dual Sigma Sampler |

**`RunningHub/MiniMax H3/decode`**

| Node ID | Display name |
|---|---|
| `RHMiniMaxH3DecodeAV` | RunningHub MiniMax H3 Decode Video + Audio |

### 迁移旧工作流

节点 ID 加了 `RH` 前缀，双 VAE loader 的 `vae_path` 也拆成了两个输入，因此更早
保存的工作流会报 `Node type not found`。用迁移工具转换，不必手工重建：

```bash
python3 tools/migrate_workflow.py 旧工作流.json --in-place
```

前端格式与 API 格式都支持。工具会改节点 ID、拆分 VAE 输入、按当前签名补齐缺失的
widget；下拉里已不存在的旧模型名会替换成当前默认值，并逐条打印替换记录供你复核。
`--in-place` 会留一份 `.bak` 备份。

## 环境要求

- ComfyUI 0.27 或更高版本（建议 0.28+）
- 与 ComfyUI 匹配的 PyTorch CUDA、Triton 和 `comfy-kitchen`
- Ref2VA 视频/音频参考需要系统 `PATH` 中存在 `ffmpeg`、`ffprobe`
  （Encode / Video Reference 在节点加载期软探测；真正跑媒体计划时缺失会 fail-closed）
- 另行下载 MiniMax-H3 权重；本仓库不包含模型权重
- 安装 `requirements.txt` 中的 Python 依赖（`transformers>=4.57.0,<=5.8.1`）

该模型规模很大。INT8 主要降低权重磁盘占用和搬运成本，并不会把 H3 变成小模型。
BF16 DiT 的 layerwise offload 为 **auto**（对齐官方 `auto_dit_layerwise_offload`，
优化基准为单卡 24GB）：当可用显存 ≥ 整模权重 + `DIT_INFERENCE_RESERVE` 时自动关闭、
走整模驻留；放不下时非 block 模块常驻 GPU、transformer block 按层预取。开关见
`h3_settings.py` 的 `ENABLE_DIT_LAYERWISE_OFFLOAD`（`False`=强制整模）/
`DIT_LAYERWISE_PREFETCH`。INT8 仍可走 Comfy MixedPrecisionOps 的
partial/streaming offload。两种路径都需要较大的主机内存和高速磁盘。

采样热路径优化默认启用（均可在 `h3_settings.py` 单独关闭以便回滚）：
`OPT_SDPA_PRECOMPUTED_BOUNDS`（预计算 attention bounds，消除每层 CUDA→CPU 同步）、
`OPT_PREPARED_STRUCTURE`（RoPE/结构张量 session 缓存）、
`OPT_INPLACE_EULER_UPDATE`（原位更新 target rows，避免每步整序列 clone）、
`OPT_ADALN_SEGMENT_BROADCAST`（adaLN 按连续段广播 in-place，避免每层
`index_select` 物化整序列调制张量）、
`OPT_ADALN_PRECOMPUTE` / `OPT_ADALN_RELEASE_WEIGHTS`（采样前预计算全部
timestep 的 adaLN 并释放约 40% DiT 权重；缓存设备由 `OPT_ADALN_CACHE_DEVICE`
控制：`auto`/`ram`/`vram`）、
`OPT_PREBUILT_TIMESTEPS`（预生成连续 sigma/timestep 张量）、
`OPT_DYNAMIC_ACTIVATION_RESERVE`（按画布/序列估算激活预留并分档
`full`/`layerwise`/`partial`/`reject`；采样输出带 `residency_mode`）。

生命周期与缓存（均可在 `h3_settings.py` 关闭）：
- `OPT_RESIDENCY_LEASE` + `RESIDENCY_POLICY`（`safe`/`balanced`/`resident`）：
  推理后 DiT 租约驻留（`gpu-resident` / `layerwise-warm`），TTL 后冷卸载；
- `OPT_ENCODE_CACHE`：文本 / 多模态 Qwen / VAE 条件 rows 共用 LRU（CPU，按字节上限）；
- `OPT_VAE_RESIDENCY`：VAE offload 后跳过 `soft_empty_cache`，便于连续任务回载；
- `FORCE_ABSOLUTE_MODEL_ROOTS`：`True` 时 loader COMBO 一律写绝对路径；默认 `False`，
  按 ComfyUI 目录型模型的约定显示相对搜索路径的短名（如 `MiniMax-H3`），解析时按
  `folder_paths` 搜索路径顺序取首个命中；
- `OPT_WRITE_SIDECAR`：Decode 在 Comfy `output/` 写 JSON（任务/几何/驻留/telemetry + `env`：plugin commit / GPU / torch / Comfy）；
- 降档链：16:9 为 `1344x768→1024x576→832x480→640x352`（`runtime/downscale.py`）。

结构治理（公开节点 class 名不变）：
- `nodes.py` 薄 facade → `api/{loaders,targets,conditioning,sampling_nodes,decode,_shared}.py`
- `contracts/` → `constants` / `target` / `conditioning` / `components` / `fingerprints`（+ `_impl`）
- `sampling.py` → `runtime/sampler_core.py`
- `runtime/` 下 `packing` / `qwen_encoder` / `media_conditioning` / `model_loader` / `vae_adapter` / `components` / `dit` 均已分包
- DiT 工具：`runtime/attention.py`、`runtime/prepared_structure.py`

## 基准与可观测性

- `OPT_TELEMETRY`：采样/解码写入阶段耗时、每步 P50/P95、峰值显存；sidecar 带 `telemetry`
- 24GB 主矩阵：`benchmarks/matrix.json` + 采集说明 `benchmarks/BASELINE_24GB.md`
- 汇总：`python3 benchmarks/run_matrix.py --sidecars <Comfy output> --out benchmarks/results`
- latent golden：`python3 benchmarks/compare_golden.py --ref a.pt --cand b.pt`（默认 accel=off）

## 模型目录

权重分两处存放：**官方分片 release** 留在 `models/diffusers`（或
`models/minimax_h3`）下，**单文件转换产物**放进专属根
`ComfyUI/models/MiniMax-H3`。

```text
models/MiniMax-H3/                              # 扁平单文件权重（转换产物）
├── MiniMax-H3-FL2VA-int8_convrot.safetensors
├── MiniMax-H3-Ref2VA-int8_convrot.safetensors
├── qwen3-vl-32b-int8_convrot.safetensors
├── MiniMax-H3-video_vae.safetensors
└── MiniMax-H3-audio_vae.safetensors

models/diffusers/MiniMax-H3/                    # 官方分片 release
├── FL2VA/
│   ├── transformer/                  # 官方 BF16 DiT（分片）
│   ├── text_encoder/                 # 官方 Qwen3-VL（分片 + tokenizer/processor）
│   ├── video_vae/
│   └── audio_vae/
└── Ref2VA/
    └── ...                           # 组件结构相同
```

专属根**只放权重、不带任何 sidecar**：组件类型与分区一律由文件名判定
（`MiniMax-H3-<分区>-<格式>` / `qwen3-vl-32b-*` / `MiniMax-H3-{video,audio}_vae`），
不符合命名规范的文件会被忽略而不是猜类型。`config.json`、`source/config.json`、
tokenizer、`preprocessor_config.json` 仍然从 `model_root` 指向的分片 release 读取，
因此**两处都要有**：release 提供结构，专属根提供张量。

`model_root` 选官方 release 根。FL2VA 节点只解析 `FL2VA` 分区，Ref2VA 节点只解析
`Ref2VA` 分区。每个任务有三个显式组件加载节点，**每个下拉只列出对应类型的模型**：

- `... Model Loader (Direct)`：`transformer_path` 只列 DiT，且按分区过滤；
- `... Qwen3-VL Loader (Direct)`：`text_encoder_path` 只列文本/多模态编码器；
- `... Dual VAE Loader (Direct)`：拆成 `video_vae_path` 与 `audio_vae_path`
  两个下拉，一次性选择并加载 24 通道视频 VAE 和 32 通道音频 VAE。

节点不会在 BF16 和 INT8 之间静默切换。请按模型名选择，例如：

- DiT INT8（单文件）：`MiniMax-H3-FL2VA-int8_convrot.safetensors` /
  `MiniMax-H3-Ref2VA-int8_convrot.safetensors`
- DiT BF16（分片）：逻辑名 `MiniMax-H3-FL2VA` / `MiniMax-H3-Ref2VA`
- TE INT8（单文件）：`qwen3-vl-32b-int8_convrot.safetensors`
- TE BF16（分片）：逻辑名 `qwen3-vl-32b`
- VAE 单文件：`MiniMax-H3-video_vae.safetensors` /
  `MiniMax-H3-audio_vae.safetensors`
- VAE 分片/原始包：逻辑名 `MiniMax-H3-video_vae` / `MiniMax-H3-audio_vae`

扁平单文件没有 `quant_meta.json`，**分区凭证就是文件名**：把 Ref2VA 的 DiT 选进
FL2VA 节点会直接报错。选中的单文件路径会折进组件 fingerprint，换掉权重会立刻
被下游校验发现。

旧工作流里的目录名（如 `transformer_int8_convrot` / `vae`）以及 release 内的合并
双 VAE 包仍可解析；但旧的单 `vae_path` 输入已被 `video_vae_path` +
`audio_vae_path` 取代，含 VAE Loader 的旧工作流需要重连该节点。

加载 Qwen processor 时会校验官方 `preprocessor_config.json` /
`video_preprocessor_config.json`（短边/长边像素、patch/merge、mean/std）。
通用 Qwen3-VL 或错误硬编码像素阈值会直接报错，避免条件 embedding 静默偏移。

## FL2VA 工作流

支持首帧、尾帧、首帧+尾帧三种合法条件签名。条件图像与语义帧位置会作为整体
传递，并在采样前再次校验。

1. 使用 ComfyUI `LoadImage` 加载图片；
2. 使用 `RunningHub MiniMax H3 FL2VA First / First+Last`（或 `Last Only`）构造关键帧；
3. 分别使用三个 FL2VA Loader 加载 DiT、Qwen3-VL 与 VAE；
4. 创建 `FL2VA Target`，再执行 `FL2VA Encode`；
5. 将同一个 target 接到 `Empty AV Latent`；
6. 依次连接 `Dual Sigma Sampler`、`Decode Video + Audio`、`CreateVideo`、
   `SaveVideo`。

三种签名各一个工作流：
[`fl2va_first_frame.json`](examples/workflows/fl2va_first_frame.json) ·
[`fl2va_last_frame.json`](examples/workflows/fl2va_last_frame.json) ·
[`fl2va_first_last_frame.json`](examples/workflows/fl2va_first_last_frame.json)。
运行前请替换其中的占位输入图片名。

## Ref2VA 工作流

Ref2VA 的参考素材有严格顺序。添加每一个图片、音频、视频或带音轨视频时，应将
上一个节点的 `references` 输出接到下一个参考节点；改变链路顺序会改变多模态提示
和条件行的顺序。

1. 使用标准 `LoadImage`、`LoadAudio` 或 `LoadVideo` 加载素材；
2. 使用对应的 `RunningHub MiniMax H3 Ref2VA ... Reference` 节点按顺序追加；
3. 分别使用三个 Ref2VA Loader 加载 DiT、Qwen3-VL 与 VAE；
4. 将最终 reference 链同时接到 `Ref2VA Target` 和 `Ref2VA Encode`；
5. 依次连接 `Empty AV Latent`、`Dual Sigma Sampler`、
   `Decode Video + Audio`、`CreateVideo`、`SaveVideo`。

三种参考形态各一个工作流：
[`ref2va_image.json`](examples/workflows/ref2va_image.json) ·
[`ref2va_image_audio.json`](examples/workflows/ref2va_image_audio.json) ·
[`ref2va_video_audio.json`](examples/workflows/ref2va_video_audio.json)。
Ref2VA 的 Target 建议显式填 width/height；留空时按 aspect_ratio 默认解析到
1344×768，序列和耗时会大幅上升。
运行前请替换图片和音频占位文件名。

`Ref2VA Encode` 新增 `ref_image_size`，决定每张参考图解析到多大：

- `match`（默认）：按生成画布的像素面积等比只缩不放；
- `max`：参考管线独立的 2048 短边，identity 保真最好。

参考 token 每个采样步都参与注意力，同画布下 `max` 可能比 `match` 慢数倍。
此选项出现之前保存的工作流现在会按 `match` 运行；要精确复现旧结果请显式选
`max`。切换策略会重新编码，不会复用另一策略的缓存。

Ref2VA 视频参考按官方路径规范为 24 fps，Qwen 展示序列再从该序列按 2 fps 采样。
`video_audio` 类型必须包含实际音轨；参考音频会进入立体声/32 kHz 的音频 VAE
预处理路径。Comfy `AUDIO` 超过双声道且无 layout 时，会在 Reference 节点 / VAE
边界均值下混为 stereo；需要 ffmpeg 布局感知 `-ac 2` 时优先走文件/视频参考。

## Target 与采样语义

- 对外时长限制为 5–15 秒。运行时会把请求帧数向上对齐到 H3 的 `17n+5` 时间
  边界，例如 24 fps 下请求 5.0 秒会解析为 124 帧；
- FL2VA 的 `auto` 尺寸跟随关键帧素材；指定比例时使用官方 `adapt_shape_v1`
  画布规则。Ref2VA 使用六个官方比例桶：`21:9`、`16:9`、`4:3`、`1:1`、
  `3:4`、`9:16`，`auto` 默认解析为 16:9；
- `Ref2VA Target` 也支持可选的 `width`、`height`：两者都为 `0` 时保持上述比例桶
  策略；两者同时填写时以手动画布为准。尺寸必须为 32 的倍数、宽高比在 1:4–4:1
  内，且不超过 H3 的像素上限；
- Ref2VA 时长填 `0` 表示从唯一一个真实带音频 reference 推导。没有带音频参考或
  存在多个带音频参考时，必须显式填写 5–15 秒；
- 采样器分别创建视频、音频噪声。视觉条件行在每一步固定为 sigma `0.999`，音频
  参考行固定为 sigma `1.0`。50 个 sigma 点对应 49 次 DiT forward；
- 编码、采样、解码之间会校验 target、条件顺序、任务分区、release 和组件指纹。
  FL2VA/Ref2VA 组件交叉连接会直接报错，不会继续生成未定义结果。

## V2A（视频→音频，可选）

`Dual Sigma Sampler` 的 `denoise_video=False`：把 `av_latent.video` 整段冻结为
视觉条件（timestep floor `0.999`），只去噪音频。当前要求 **T2VA 布局**（packed
无既有 visual condition）。

典型接线：

1. `T2VA Target` + `Empty AV Latent`；
2. `Encode Video → AV Latent`（VAE + 与 target 对齐的 `IMAGE` 帧序列）写入视频；
   或用 `Separate` / `Combine AV Latent` 从已有 AV 壳拼出非空视频；
3. `T2VA Text Encode` + `Dual Sigma Sampler`（`denoise_video=false`）；
4. `Decode Video + Audio`（视频回传输入 latent，音频为新采样结果）。

`Empty AV Latent` 全零视频会直接报错；勿在 FL2VA/Ref2VA 既有 visual cond 布局上开 V2A。

## 帧率条件（实验性，可选）

`RunningHub MiniMax H3 Frame Rate (Experimental)` 对应 PR#15210 的实验能力，**不是**官方
训练契约，也不改 `target.fps=24` 时序格：

- `adaln=True`：把 fps 的 sinusoidal 加到 `TimeEmbedder`（即使填 24 也非 no-op）；
  与 adaLN 预计算兼容，会写入 modulation cache 键；
- `temporal_rope=True`：按 `24/fps` 缩放视频行时序 RoPE 低频（可选 hard/linear/
  smoothstep 频率与 sigma 剖面）；24fps 时缩放为 1。

接线：`Model Loader` → `Frame Rate` → `Dual Sigma Sampler`。换 fps 后若 DiT 已
释放 adaLN 权重，需重新加载模型。

## 单卡采样加速（可选）

开发/部署按**单卡**设计：不做多卡或 Ulysses 门禁。官方 4×H200 数字只作旋钮与
质量参考；单卡收益来自减少 DiT 次数（velocity-cache）或跳过 block 计算
（Cache-DiT）。默认 `accel=off`。

`Dual Sigma Sampler` 的 `accel`：

| 值 | 行为 | 单卡建议 |
| --- | --- | --- |
| `off` | 关闭（可作 GT） | 默认 |
| `auto` | 命中 1344×768/124f/50steps/shift12·3 时优先 velocity-cache | 推荐试 |
| `minimax-h3-velocity-cache-v1` | 整步 velocity 复用 + Taylor（无额外依赖） | **首选** |
| `minimax-h3-cache-v1` | Cache-DiT DBCache（需 `pip install cache-dit>=1.3.0`） | 备选 |
| `manual-velocity` / `manual-cache-dit` | 手调 stride 或 RDT/MC/warmup | 调试 |

官方参考：velocity-cache 约 **3.2×**、Cache-DiT 约 **2×**（均为 4×H200 证据）。
近似加速，**不要**当 consistency GT。profile 在
`minimax_h3_nodes/runtime/profiles/`。采样结束会打实际/理论 DiT 次数日志；
`auto` 未命中与 `manual-*` 也会记录当前 workload 并标明非 GT。

在 [`examples/workflows/`](examples/workflows) 任一工作流的采样器上
设置 `accel` 即可；导入前确认模型名与本地 INT8/VAE 选择一致。

与 `accel` 无关的两条融合 kernel 路径（均来自上游 PR#15224）：安装的 Comfy 暴露
了对应入口就自动启用，每进程探测一次并打日志；入口缺失（旧版 Comfy、没有
comfy-kitchen、非 CUDA 设备）则原样走现有 PyTorch 路径。

| 开关 | Kernel | 收益 |
| --- | --- | --- |
| `OPT_INT8_FUSED_SWIGLU` | `comfy.ops.linear_input_act` | INT8 MLP：swiglu 折进激活量化 kernel，省掉每层每步一次全尺寸中间张量 |
| `OPT_FUSED_QK_ROPE` | `comfy.quant_ops.ck.rms_rope_split_half_` | 注意力：per-head RMSNorm 与 split-half RoPE 一趟做完，就地写在 qkv 缓冲上 |

两者都在 `minimax_h3_nodes/runtime/h3_settings.py`；
`OPT_FUSED_QK_ROPE_CUDA_ONLY` 让 RoPE kernel 在非 CUDA 设备上一律回退
（comfy-kitchen 没有对应实现）。带梯度时融合 RoPE 也会自动让路——它要就地改写
autograd 视图。

## INT8 转换与 VAE 合并

必须按任务分区分别转换：

```bash
cd custom_nodes/ComfyUI-RH-MiniMax-H3
BASE=/path/to/ComfyUI/models/diffusers/MiniMax-H3

python3 tools/quantize_int8_convrot.py \
  --src "$BASE/FL2VA/transformer" --device cuda --verify
python3 tools/quantize_int8_convrot.py \
  --src "$BASE/Ref2VA/transformer" --device cuda --verify

python3 tools/quantize_text_encoder_int8_convrot.py \
  --src "$BASE/FL2VA/text_encoder" --device cuda --verify
python3 tools/quantize_text_encoder_int8_convrot.py \
  --src "$BASE/Ref2VA/text_encoder" --device cuda --verify

python3 tools/merge_vae.py --src "$BASE/FL2VA"
python3 tools/merge_vae.py --src "$BASE/Ref2VA"
```

VAE 只做合并打包，不做 INT8 量化。即使文件名相同，也不要用一个分区的文件修补
另一个分区；转换前应先校验完整的官方下载权重。

工具输出的是**组件目录**（`config.json` + 单文件权重 + `quant_meta.json`）。要用
专属根的扁平布局，把其中的 `.safetensors` 挪到 `models/MiniMax-H3/` 即可——文件名
已经带了模型/类型/量化格式，节点靠它判定类型与分区，配置继续从 `$BASE` 的分片
release 读：

```bash
FLAT=/path/to/ComfyUI/models/MiniMax-H3
mkdir -p "$FLAT"
mv "$BASE/FL2VA/transformer_int8_convrot/MiniMax-H3-FL2VA-int8_convrot.safetensors" "$FLAT/"
mv "$BASE/Ref2VA/transformer_int8_convrot/MiniMax-H3-Ref2VA-int8_convrot.safetensors" "$FLAT/"
mv "$BASE/FL2VA/text_encoder_int8_convrot/qwen3-vl-32b-int8_convrot.safetensors" "$FLAT/"
mv "$BASE/FL2VA/vae/video_vae/MiniMax-H3-video_vae.safetensors" "$FLAT/"
mv "$BASE/FL2VA/vae/audio_vae/MiniMax-H3-audio_vae.safetensors" "$FLAT/"
```

留在 release 里的组件目录（含 `quant_meta.json`）同样可用，两种形态都会出现在
对应类型的下拉里。

## AdaLN 曲线表 DiT（可选，checkpoint 缩小约 40%）

DiT 每层的 adaLN 投影是 `[96768, 2688]`，50 层合计 26 GB——占 BF16 DiT 的 39%、
INT8 的 55%（adaLN 不参与量化）。而它的输入只是 `silu(time_embedder(t))` 这条
一维曲线：把曲线投影到秩 `k` 的共享基后，基被折进每层权重（`[96768, k]`），
time embedder 由 `adaln_t_table [grid, k]` 采样表 + 线性插值取代。这就是上游
PR #15224 引入的 checkpoint 格式；加载器按 `adaln_t_table` 张量自动识别，两种
形态走同一套节点。

```bash
python3 tools/convert_adaln_curve.py \
  --src "$BASE/FL2VA/transformer" --verify           # BF16: 66.3 GiB -> 约 40 GiB
python3 tools/convert_adaln_curve.py \
  --src "$BASE/FL2VA/transformer_int8_convrot" --verify   # INT8: 47.0 GiB -> 约 21 GiB
```

产物写到 `<src>_adaln_curve/`，在 DiT 选择器里作为独立模型名出现。`--verify`
会在随机的非网格 timestep 上比对曲线路径与真实 adaLN 输出，低于
`--cosine-floor`（0.9999）直接失败——此时提高 `--rank` / `--grid`。默认
rank 64 / grid 1024。

与运行时 adaLN 预计算（原版 checkpoint 仍默认走它）的取舍：

- 磁盘更小，无需预计算，不占调制缓存，任意 timestep 都可用。
- adaLN 输入是秩 `k` 近似，而非精确值。
- 实验性 Frame Rate 节点的 `adaln` 模式依赖 time embedder，曲线表 checkpoint 会
  直接报错；`temporal_rope` 模式不受影响。

## 本地验证

```bash
python3 -m compileall -q minimax_h3_nodes tools tests
python3 -m unittest discover -s tests -v
```

这些命令验证本地结构以及 CPU 可执行合同，不能代替使用完整发布权重的真实 CUDA
端到端运行。

## 许可证与上游

插件代码按本仓库 Apache-2.0 许可证发布。模型权重不包含在仓库中，仍受上游模型
许可证及条款约束。实现参考官方
[MiniMax-H3 源码包](https://github.com/MiniMax-AI-Dev/Internal-0727-private-3)。