Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,68 @@
+---
+license: other
+license_name: minimax-h3-community-license-agreement
+license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE
+base_model: MiniMaxAI/MiniMax-H3
+tags:
+- comfyui
+- nvfp4
+- video
+- quantized
+---
+
+# MiniMax H3 ref2va — NVFP4 (ComfyUI-native)
+
+NVFP4 quantization of the [MiniMax H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)
+**reference-to-video** DiT (`ref2va`), in ComfyUI's native quant layout — loads with
+the stock `UNETLoader` on any Blackwell GPU (sm_120: RTX 5090 / RTX PRO 6000, and
+newer). Derived from
+[Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3)'s
+`minimax_h3_ref2va_bf16.safetensors`.
+
+## Files
+
+| File | Size | GEMM path |
+|---|---|---|
+| `diffusion_models/minimax_h3_ref2va_nvfp4.safetensors` | 38.6 GB | native FP4 tensor-core |
+| `diffusion_models/minimax_h3_ref2va_nvfp4_fpmm.safetensors` | 38.6 GB | dequant → bf16 (quality-safe, same path the official NVFP4 text encoder uses) |
+
+Quantization policy mirrors the official `int8_convrot` release: the 50 main
+blocks' `attn.qkv_proj`, `attn.out_proj`, `mlp.fc1`, `mlp.fc2` (200 layers) go
+to NVFP4 (E2M1, per-16 FP8-E4M3 block scales + global FP32 scale); everything
+quality-critical — adaln/modulation, norms, patch/condition projections, token
+refiner, final layers — stays bf16. Weight-only PTQ (no activation calibration),
+produced with the included `convert_nvfp4.py` via ComfyUI's `comfy_kitchen`
+`quantize_nvfp4` kernels.
+
+## Usage (ComfyUI)
+
+Drop into `ComfyUI/models/diffusion_models/` and select in `UNETLoader`
+(weight_dtype `default`) inside the official
+[MiniMax H3 r2v template](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/video_minimax_h3_r2v.json).
+Pair with the official `qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors` text
+encoder and both H3 VAEs from
+[Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3).
+
+## Benchmarks (RTX PRO 6000 Blackwell Max-Q, 96 GB, SageAttention, 1344×768×124f, 20 steps)
+
+| DiT variant | Size | s/step | Notes |
+|---|---|---|---|
+| bf16 (reference) | 66.3 GB | 14.65 | baseline quality |
+| pruned int8_convrot (official) | 21.0 GB | 22.7 | pruned arch, W8A16 dequant path |
+| **nvfp4 (this repo)** | 38.6 GB | 19.8* | full (unpruned) model |
+| **nvfp4_fpmm (this repo)** | 38.6 GB | ~bf16* | full (unpruned) model |
+
+\* measured on torch 2.8+cu128, where comfy_kitchen runs **fallback** (emulated)
+FP4 ops — a cu130 torch build unlocks the optimized CUDA kernels and these
+numbers will be updated. Same-seed visual quality vs bf16: no quantization
+artifacts observed (trajectory divergence only, PSNR vs bf16 ≈ within the
+pipeline's chaotic-divergence regime; see sample).
+
+A same-seed sample generated with this checkpoint is in
+[`assets/sample_r2v_5s.mp4`](assets/sample_r2v_5s.mp4).
+
+## License
+
+MiniMax H3 Community License. This is a derivative work of MiniMaxAI/MiniMax-H3;
+see the [license](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE)
+for terms.