--- license: other license_name: minimax-h3-community-license-agreement license_link: LICENSE base_model: MiniMaxAI/MiniMax-H3 library_name: comfyui pipeline_tag: image-text-to-video tags: - minimax-h3 - comfyui - quantization - int8 - convrot - video - audio - fl2va - ref2va --- # MiniMax-H3 INT8 Lean ConvRot — Stock ComfyUI Edition This repository contains stock-compatible, quality-oriented mixed-precision INT8 ConvRot conversions of [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3), plus the standard MiniMax-H3 visual and audio VAEs. FL2VA and Ref2VA are separate because their diffusion-transformer weights are task-specific. These are community derivatives, not official MiniMax or ComfyOrg checkpoints. The diffusion checkpoints use the standard MiniMax-H3 `adaln_t_table` layout and load in unmodified ComfyUI. No core patch or custom node is required. The experimental edition with the original FP32 time MLP and physically separate Q/K/V projections has moved to [`DmitryDB/MiniMax-H3-INT8-Lean-ConvRot-Dynamic-Time-Separate-QKV`](https://huggingface.co/DmitryDB/MiniMax-H3-INT8-Lean-ConvRot-Dynamic-Time-Separate-QKV). It requires a ComfyUI core patch and is intentionally kept separate to avoid confusion. ## Included files | Path | Purpose | |---|---| | `FL2VA/minimax-h3-fl2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors` | Stock-compatible FL2VA diffusion transformer, 20.940 GiB | | `Ref2VA/minimax-h3-ref2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors` | Stock-compatible Ref2VA diffusion transformer, 20.940 GiB | | `vae/minimax_h3_video_vae_fp16.safetensors` | Stock ComfyUI MiniMax-H3 visual VAE, FP16, 4.850 GiB | | `vae/minimax_h3_audio_vae_fp32.safetensors` | Stock ComfyUI MiniMax-H3 stereo audio VAE, FP32, 0.564 GiB | | `reports/validation.json` / `validation_ref2va.json` | Structural, table-error, and clean-Comfy CPU-load validation | | `reports/layer_policy.json` / `layer_policy_ref2va.json` | Exact BF16/INT8 layer policy | | `reports/mm_quant_profile_fl2va.json` / `mm_quant_profile_ref2va.json` | Row-sampled reconstruction profiles | The MiniMax-H3 Qwen3-VL text encoder is not included in this repository. A standard workflow needs one selected diffusion checkpoint, both VAEs, and a compatible MiniMax-H3 text encoder installed separately. ## Quantization policy The original FL2VA and Ref2VA transformers each contain 50 main transformer blocks. Each block has four attention projections and two MLP matrices, for 300 main matrices. The quality21 policy keeps the high-risk matrices in their source precision and compresses the rest: - 170 main matrices use INT8 ConvRot with Hadamard group size 256; - 30 high-risk main matrices remain BF16; - token-refiner attention/MLP weights remain BF16; - normalization tensors remain BF16; - patch projections and video/audio output heads retain source FP32; - 51 AdaLN projections are represented through separate FP32 rank-16 table projections. Q, K, and V originate as separate Diffusers tensors. For stock ComfyUI they are packed as global `cat(Q,K,V)` into `qkv_proj`, which is the layout expected by the unmodified runtime. The BF16 islands were selected by deterministic row-sampled reconstruction analysis rather than by a blanket first/last-block rule. FL2VA and Ref2VA were profiled independently and selected the same 30 matrices. ## Time conditioning The raw model uses a wide FP32 time MLP followed by 51 large AdaLN projections. The release samples the original FP32 time path on 4,097 points, derives a shared 16-dimensional basis, and stores one independent FP32 projection for every transformer block plus the final layer. The saved `adaln_t_table` has shape `[4097, 16]`. ComfyUI linearly interpolates the 16 coordinates and applies the per-layer projection. On 19 validation timesteps, relative AdaLN output error against the raw HF dynamic path was: - FL2VA: about `3.04e-7` to `3.82e-7`; - Ref2VA: about `3.42e-7` to `4.46e-7`. This is substantially more accurate than using a direct wide cached table at the same grid density while remaining compatible with stock ComfyUI. ## Comparison with official ComfyOrg files | Checkpoint | Size | Main matrices | Time/AdaLN representation | |---|---:|---:|---| | Official full INT8 ConvRot | 27.557 GiB | 300 INT8 | Wide FP32 AdaLN table | | Official pruned INT8 ConvRot | 19.530 GiB | 200 INT8 | Wide FP32 AdaLN table | | This stock quality21 edition | 20.940 GiB | 170 INT8 + 30 BF16 | FP32 `[4097,16]` table + 51 projections | Each file is about 1.410 GiB larger than its official pruned INT8 counterpart. The additional space is intentionally spent on the rank-16 time representation and BF16 islands. The sampled weight-reconstruction proxy improved from about `0.9345%` mean relative error for official-style absmax INT8 to about `0.7639%` for this mixed profile. This is a proxy, not an end-to-end perceptual result. ## Installation Place one or both diffusion checkpoints in: ```text ComfyUI/models/diffusion_models/ ``` Place both VAE files in: ```text ComfyUI/models/vae/ ``` Install a compatible MiniMax-H3 Qwen3-VL text encoder separately, then use the matching stock MiniMax-H3 FL2VA or Ref2VA workflow. ## Validation performed - safetensors structure, shapes, and dtypes; - 170/170 INT8 ConvRot blobs with group size 256; - all 30 BF16 main matrices present according to the published policy; - non-quantized source tensors compared against the raw MiniMax-H3 shards; - FP32 rank-16 time tables and 51 projections checked numerically; - full CPU load through clean, unmodified ComfyUI commit `14b05228` as `ModelPatcher -> MiniMaxH3Model`, table mode enabled and no dynamic time MLP; - both VAE files fully loaded through the same clean ComfyUI; - VAE checksums match the standard ComfyOrg repackaged files. SHA-256: ```text ad0cf8b50ba92068b5a4477527d5da73412a22db99cded35b07195504e78cf6a FL2VA/minimax-h3-fl2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors f4b2a8b4a53446f5d696a39deb693b09ac7ce37013793a8b19340644e38b154f Ref2VA/minimax-h3-ref2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors 7c1f131492e7eddacaac9069a61b81bdd39de5cc96561e677c5eab1cdce5e522 vae/minimax_h3_video_vae_fp16.safetensors 8e505d95dd1561d47abd43d4238fd40d9bb1ae9e147ed0a4cba778d76ae4db48 vae/minimax_h3_audio_vae_fp32.safetensors ``` ## Validation not yet completed - GPU loading and peak-VRAM measurement; - fixed-seed end-to-end FL2VA/Ref2VA generation; - video and audio A/B quality comparison against BF16 and official INT8. The 20.940 GiB file size is a disk-weight target, not a guarantee that every 24 GiB workflow will fit. Runtime memory also depends on activation size, resolution, frame count, attention implementation, and offload settings. ## License MiniMax H3 is distributed under the MiniMax H3 Community License Agreement. Read `LICENSE` before using or redistributing these derivatives. The modification summary is provided in `NOTICE`. ## Links - [Original MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) - [Experimental dynamic-time / separate-QKV edition](https://huggingface.co/DmitryDB/MiniMax-H3-INT8-Lean-ConvRot-Dynamic-Time-Separate-QKV) - [Official ComfyOrg MiniMax-H3 files](https://huggingface.co/Comfy-Org/MiniMax-H3) - [ComfyUI](https://github.com/comfyanonymous/ComfyUI)