--- 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 --- # MiniMax-H3 INT8 Lean ConvRot This repository contains a quality-oriented mixed-precision ComfyUI derivative of [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3). The currently released checkpoint is the **FL2VA** diffusion transformer. It is designed as a first 24 GiB GPU candidate while preserving more of the original model than the official pruned INT8 checkpoint. The release is not an official MiniMax or ComfyOrg checkpoint. It uses the standard MiniMax-H3 `adaln_t_table` format and loads in an unmodified ComfyUI. ## Included files | Path | Purpose | |---|---| | [`FL2VA/minimax-h3-fl2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors`](FL2VA/minimax-h3-fl2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors) | Stock-compatible FL2VA diffusion transformer, 20.940 GiB | | [`vae/minimax_h3_video_vae_fp16.safetensors`](vae/minimax_h3_video_vae_fp16.safetensors) | Stock ComfyUI MiniMax-H3 visual VAE, FP16, 4.850 GiB | | [`vae/minimax_h3_audio_vae_fp32.safetensors`](vae/minimax_h3_audio_vae_fp32.safetensors) | Stock ComfyUI MiniMax-H3 stereo audio VAE, FP32, 0.564 GiB | | [`reports/layer_policy.json`](reports/layer_policy.json) | Exact per-layer precision policy | | [`reports/validation.json`](reports/validation.json) | Structural, numerical, and CPU-load results | | [`reports/mm_quant_profile_fl2va.json`](reports/mm_quant_profile_fl2va.json) | Row-sampled reconstruction profile for all 200 main matrices | This repository intentionally does **not** include the MiniMax-H3 text encoder. It is being prepared as a separate repository. ComfyUI does not require the Diffusers scheduler, tokenizer, processor, or remote-code Python bundles as separate downloads: the standard workflow needs this diffusion model, the two included VAEs, and a compatible MiniMax-H3 text encoder. Ref2VA is not included in this release. ## What was changed The original FL2VA Diffusers shards contain 50 transformer blocks with separate Q, K, and V tensors. The converter streams those shards directly and performs the layout changes required by current ComfyUI MiniMax-H3 support: - packs attention rows as global `cat(Q, K, V)`; - swaps the two `fc1` halves from `[value, gate]` to `[gate, value]`; - stores 170 selected main attention/MLP matrices as INT8 ConvRot with group size 256 and per-row FP32 scales; - keeps 30 high-error main matrices as exact BF16 copies; - keeps the two-block token refiner, norms, Q/K norms, and condition projection at their source precision; - keeps patch projections and video/audio output heads in source FP32; - evaluates the original FP32 time embedder offline and stores its smooth one-dimensional output curve as a dense FP32 table with 4,097 rows and 16 coordinates; - replaces only the redundant input width of the 51 large AdaLN projections, while keeping every block and final AdaLN projection separate in FP32. The checkpoint contains 872 tensor entries: 170 INT8 weights, 170 quantization configuration blobs, 250 BF16 entries, and 282 FP32 entries. ## Precision policy Every DiT block has four main matrices: QKV, attention output, MLP `fc1`, and MLP `fc2`, for 200 matrices total. The `quality21` profile stores 170 in INT8 and 30 in BF16. The BF16 island is: - attention output projections in blocks 0–15, 17, 19, 20, 27, 38, 43–47, and 49 (27 matrices); - MLP `fc2` in blocks 39, 45, and 49 (3 matrices). These were selected from a deterministic reconstruction audit using 64 output rows and every input column of each matrix. Attention output projections were the most error-prone family and are considerably cheaper to retain in BF16 than QKV or `fc1`. The exact machine-readable list is in [`reports/layer_policy.json`](reports/layer_policy.json). ## Time conditioning and the AdaLN table The time embedder maps the current diffusion timestep/noise level to a 2,688-dimensional signal. Every transformer block turns this signal into its own AdaLN shifts, scales, and gates, telling the network which denoising stage is being evaluated. At inference this frozen mapping traces a smooth one-dimensional curve because its input is a single scalar timestep. This release evaluates the original FP32 time MLP offline, projects the curve onto a shared 16-dimensional basis, and stores those coordinates at 4,097 evenly spaced points: ```text u(t) = SiLU(original_time_embedder(t)) table[j] = project(u(j / 4096)) AdaLN_i(t) = linear_i(interpolate(table, t)) ``` Each of the 50 block AdaLN projections and the final AdaLN projection remains a different FP32 linear layer. Only their shared input curve is compressed. On 19 validation timesteps, the relative AdaLN output error against the raw HF weights was `3.04e-7` to `3.82e-7` for blocks 0, 24, 49, and the final layer. For context, the official pruned rank-8 FP16 table measured about `0.016%–0.021%` on the same projections. This comparison covers only the time/AdaLN path, not end-to-end generation quality. ## Comparison with official ComfyOrg files | Checkpoint | Size | Main matrices | Time/AdaLN representation | |---|---:|---:|---| | Official regular INT8 ConvRot | about 31.70 GiB | 200 INT8 | full AdaLN weights | | Official pruned INT8 ConvRot | 19.530 GiB | 200 INT8 | FP16 rank-8 table | | This `quality21` release | 20.940 GiB | 170 INT8 + 30 BF16 | FP32 rank-16 table, 4,097 rows | This file is 1.410 GiB (7.22%) larger than the official pruned INT8 checkpoint. The added space is intentionally spent on a much denser, higher-precision time curve and a BF16 island for the most sensitive main matrices. The full 200-matrix sampled reconstruction proxy produced: | Metric | Official-style absmax INT8 | This profile | |---|---:|---:| | Unweighted mean relative matrix error | 0.9345% | 0.7639% | For this profile, selected BF16 matrices count as zero storage reconstruction error. On the remaining 170 INT8 matrices, searched scales reduced the mean proxy from 0.9109% to 0.8987%. The overall 18.26% reduction is a sampled weight reconstruction result, **not** a perceptual or generation benchmark. ## ComfyUI installation 1. Use a current ComfyUI checkout with MiniMax-H3 and native INT8 ConvRot support. This release was CPU-load-tested on a clean, unmodified ComfyUI commit `14b05228cef127ce529bc0c08660770d4af3e9a8`. 2. Place the FL2VA safetensors file in `ComfyUI/models/diffusion_models/`. 3. Place both files from `vae/` in `ComfyUI/models/vae/`. 4. Load the three files with the standard diffusion-model and VAE loaders in a MiniMax-H3 FL2VA workflow. Supply a compatible text encoder separately. ```text ComfyUI/models/ |-- diffusion_models/ | `-- minimax-h3-fl2va-int8-lean-convrot-table-k16-g4097-quality21.safetensors |-- vae/ | |-- minimax_h3_video_vae_fp16.safetensors | `-- minimax_h3_audio_vae_fp32.safetensors `-- text_encoders/ `-- ``` No custom node or core patch is required for this checkpoint. ## Validation status Completed: - safetensors structure, shapes, dtypes, and all 170 ConvRot descriptors; - SHA-256: `ad0cf8b50ba92068b5a4477527d5da73412a22db99cded35b07195504e78cf6a`; - BF16 main island: 30/30 matrices bitwise equal to raw HF; - 871/871 tensors outside the time representation preserved bit-for-bit during the final stock-table conversion; - FP32 table grid reproduced exactly and interpolation checked at every one of the 4,096 interval midpoints; - full CPU load through a clean, unmodified ComfyUI as `ModelPatcher -> MiniMaxH3Model`, table mode `(4097, 16)`. - both companion VAE files fully loaded on CPU through the same clean ComfyUI: `MiniMaxH3VideoVAE` in FP16 with native internal tiling, and `MiniMaxH3AudioVAE` in FP32 with 32 kHz stereo output; - companion VAE SHA-256 checksums match the official Comfy-Org repackaged files: `7c1f131492e7eddacaac9069a61b81bdd39de5cc96561e677c5eab1cdce5e522` (video) and `8e505d95dd1561d47abd43d4238fd40d9bb1ae9e147ed0a4cba778d76ae4db48` (audio). Not completed at release time: - CUDA/GPU loading of this exact checkpoint; - peak VRAM measurement for a target resolution and frame count; - end-to-end FL2VA generation; - same-seed visual/audio A/B against BF16 and official pruned variants. Therefore, 20.940 GiB is the on-disk tensor payload, not a promise that every workflow will remain under 24 GiB. Activations, runtime buffers, resolution, frame count, batch size, and offloading policy determine peak VRAM. ## Conversion provenance The converter reads the original top-level `transformer/` Diffusers shards from MiniMaxAI directly; it does not create a 61+ GiB merged BF16 intermediate. The nested task-specific transformer folder was not used because its already-packed QKV is head-major, while current ComfyUI expects global `cat(Q,K,V)` packing. The official [`minimax_h3_fl2va_pruned_int8_convrot.safetensors`](https://huggingface.co/Comfy-Org/MiniMax-H3/blob/main/diffusion_models/minimax_h3_fl2va_pruned_int8_convrot.safetensors) was used only as a layout reference and as the source of the FP32 `rope.inv_freq` tensor absent from the raw Diffusers state dict. The two files under `vae/` are unmodified, bit-identical copies of the standard [`Comfy-Org/MiniMax-H3`](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae) repackages. The original remote-code VAE bundles are more complicated: the visual VAE constructs a causal 3D-CNN encoder and 36-layer ViT decoder from Python and configuration files, while the audio VAE constructs a DAC-lineage encoder and BigVGAN decoder. ComfyUI implements both architectures natively. The single-file visual repack casts all 560 source weight tensors from FP32 to FP16 and embeds the latent statistics; the audio repack preserves 743 tensors, folds 172 weight-normalized pairs into ordinary FP32 weights, and embeds its latent statistics. No remote Python code or external VAE config is required. ## Limitations and intended use This release is intended for research and local ComfyUI inference. It is a new, structurally validated operating point, not a completed quality benchmark. The current layer policy was profiled on FL2VA and must not be assumed optimal for Ref2VA without a separate audit. ## License This derivative is distributed under the [MiniMax H3 Community License Agreement](LICENSE). The license limits use and distribution to its defined Applicable Territory, excludes the European Union, United Kingdom, Republic of Korea, and United States, and includes additional use and redistribution conditions. Read the full license and [`NOTICE`](NOTICE) before downloading, using, or redistributing these files. ## Links - [Original MiniMax-H3 repository](https://huggingface.co/MiniMaxAI/MiniMax-H3) - [Official ComfyOrg MiniMax-H3 files](https://huggingface.co/Comfy-Org/MiniMax-H3) - [ComfyUI](https://github.com/Comfy-Org/ComfyUI)