Add README.md

README.md

@@ -0,0 +1,198 @@
+---
+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
+  - experimental
+---
+
+# MiniMax-H3 INT8 Lean ConvRot — Dynamic Time / Separate QKV
+
+> **Experimental, patch-required release.** These checkpoints do not load in
+> unmodified ComfyUI. Apply the included core patch before loading them. For
+> stock ComfyUI, use the table-based checkpoints in
+> [`DmitryDB/MiniMax-H3-INT8-Lean-ConvRot`](https://huggingface.co/DmitryDB/MiniMax-H3-INT8-Lean-ConvRot).
+
+This repository contains the experimental dynamic-time, physically
+separate-Q/K/V editions of a quality-oriented mixed-precision INT8 ConvRot
+conversion of [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3).
+FL2VA and Ref2VA are provided separately because their diffusion-transformer
+weights are task-specific.
+
+These are community derivatives, not official MiniMax or ComfyOrg checkpoints.
+
+## Files
+
+| Path | Purpose |
+|---|---|
+| `FL2VA/minimax-h3-fl2va-int8-lean-convrot-dynamic-k16-separate-qkv-quality21.safetensors` | FL2VA diffusion transformer, 20.999 GiB |
+| `Ref2VA/minimax-h3-ref2va-int8-lean-convrot-dynamic-k16-separate-qkv-quality21.safetensors` | Ref2VA diffusion transformer, 20.999 GiB |
+| `patches/comfyui-minimax-h3-dynamic-time-separate-qkv.patch` | Required ComfyUI core patch |
+| `reports/validation_dynamic_separate_fl2va.json` | Structural and numerical FL2VA validation |
+| `reports/validation_dynamic_separate_ref2va.json` | Structural and numerical Ref2VA validation |
+| `reports/loadtest_dynamic_separate_fl2va.json` | Full CPU loader result for FL2VA |
+| `reports/loadtest_dynamic_separate_ref2va.json` | Full CPU loader result for Ref2VA |
+| `reports/layer_policy*.json` | Per-layer BF16/INT8 quality policy |
+| `reports/mm_quant_profile*.json` | Row-sampled reconstruction profiles |
+
+The MiniMax-H3 text encoder and VAEs are not duplicated here. The two standard
+VAE files remain available in the stock-compatible repository linked above.
+A compatible MiniMax-H3 Qwen3-VL text encoder must be installed separately.
+
+## What is different
+
+### Original FP32 time MLP
+
+The official pruned checkpoints replace the wide time/AdaLN path with a cached
+table. These checkpoints instead keep all four tensors of the original FP32
+time MLP. At each forward pass:
+
+```text
+full_t = SiLU(original_time_embedder(t))
+coords = full_t @ shared_rank16_basis
+AdaLN_i(t) = separate_linear_i(coords)
+```
+
+The rank-16 basis compresses the shared input subspace of the 51 wide AdaLN
+projections. It does not replace the time MLP with interpolation, and every
+block plus the final layer keeps an independent FP32 projection.
+
+### Physically separate Q, K and V
+
+The source MiniMax Diffusers checkpoints contain separate `to_q`, `to_k`, and
+`to_v` tensors. Stock ComfyUI normally expects a fused `qkv_proj` tensor. This
+release preserves separate projections through loading and forward execution:
+
+- 50 main transformer attention blocks and two token-refiner blocks;
+- 156 separate Q/K/V projection tensors in total;
+- no fused `qkv_proj` weights;
+- three projection calls per attention block.
+
+The released Q/K/V tensors were checked bit-for-bit against the corresponding
+contiguous slices used by the stock-compatible quality21 conversion.
+
+### Mixed-precision quality21 policy
+
+Both variants use the same quality-oriented policy:
+
+- 170 of the 200 semantic main transformer 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;
+- dynamic time MLP, basis, and all 51 AdaLN projections are FP32.
+
+Because Q, K and V are stored separately, each checkpoint contains 270
+physical INT8 ConvRot modules even though the policy represents the same 170
+semantic main matrices as the stock-compatible quality21 edition.
+
+## Why a patch is required
+
+Unmodified ComfyUI detects the stock MiniMax-H3 layout through fused
+`qkv_proj` weights and either `adaln_t_table` or the standard wide AdaLN
+construction. It does not construct the combination used here:
+
+- independent `q_proj`, `k_proj`, and `v_proj` modules;
+- original wide FP32 time MLP;
+- shared dynamic rank-16 coordinates;
+- 51 separate reduced AdaLN projections.
+
+The included patch adds model detection, construction, forward execution, and
+partial-offload support for this exact layout. No custom node is required after
+the core patch is applied.
+
+## Installation
+
+1. Apply the patch from the root of your ComfyUI checkout:
+
+   ```powershell
+   git apply --check C:\path\to\comfyui-minimax-h3-dynamic-time-separate-qkv.patch
+   git apply C:\path\to\comfyui-minimax-h3-dynamic-time-separate-qkv.patch
+   ```
+
+   The patch was checked against ComfyUI commit `14b05228`. If `--check`
+   fails on a newer checkout, do not force it; port the small changes to the
+   current MiniMax implementation and validate loading again.
+
+2. Put one or both diffusion checkpoints in:
+
+   ```text
+   ComfyUI/models/diffusion_models/
+   ```
+
+3. Install a compatible MiniMax-H3 Qwen3-VL text encoder and the standard
+   MiniMax-H3 visual/audio VAEs.
+
+4. Use the FL2VA checkpoint for T2VA/I2VA/first-last-frame workflows and the
+   Ref2VA checkpoint for multimodal reference workflows.
+
+## Validation performed
+
+The following checks were completed on CPU:
+
+- safetensors structure, shapes, dtypes, and all ConvRot descriptors;
+- 1,181 keys and 270 INT8 ConvRot descriptors per checkpoint;
+- zero fused-QKV keys;
+- all 156 Q/K/V projection tensors matched their stock quality21 slices
+  bit-for-bit;
+- all four FP32 time-MLP tensors matched the raw MiniMax-H3 source bit-for-bit;
+- dynamic AdaLN output relative error on 19 tested timesteps was approximately
+  `2.85e-7` to `3.29e-7`;
+- both files fully loaded through patched ComfyUI as `MiniMaxH3Model`, with
+  dynamic basis enabled, table mode disabled, and independent Q/K/V modules in
+  the main stack and token refiner.
+
+SHA-256:
+
+```text
+495b9d565b17194196646ef39b0c04ac7dde4a8df695b103b3fcbe04b5da00a6  FL2VA/minimax-h3-fl2va-int8-lean-convrot-dynamic-k16-separate-qkv-quality21.safetensors
+82d16de12bee9d006c83c80b8843f2bb7e05cd25320724113ca7d128c6be6a04  Ref2VA/minimax-h3-ref2va-int8-lean-convrot-dynamic-k16-separate-qkv-quality21.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, official INT8, and the
+  stock table-based quality21 edition;
+- throughput comparison between fused QKV and three independent projections.
+
+Therefore, the 20.999 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.
+
+## Intended use
+
+This edition is for testing whether retaining the original time encoder and
+independent Q/K/V projections improves quality or behavior enough to justify a
+small core patch and extra projection launches. Users who want ordinary ComfyUI
+compatibility should use the stock table edition instead.
+
+Do not treat CPU structural/numerical validation as proof of perceptual video
+quality. End-to-end fixed-seed generation remains required.
+
+## 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)
+- [Stock-compatible Lean ConvRot edition](https://huggingface.co/DmitryDB/MiniMax-H3-INT8-Lean-ConvRot)
+- [Official ComfyOrg MiniMax-H3 files](https://huggingface.co/Comfy-Org/MiniMax-H3)
+- [ComfyUI](https://github.com/comfyanonymous/ComfyUI)