| --- |
| license: other |
| license_link: https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA/blob/main/LICENSE |
| base_model: |
| - MiniMaxAI/MiniMax-H3 |
| - FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree |
| library_name: diffusers |
| tags: |
| - comfyui |
| - safetensors |
| - lora |
| - video |
| - minimax-h3 |
| - fasth3 |
| - vsa |
| - sparse-attention |
| --- |
| |
|
|
| # FastH3 VSA-DataFree LoRA + Gate for ComfyUI (experimental) |
|
|
| Two files that let ComfyUI run **MiniMax H3 video generation in 4 steps** using FastVideo's Video Sparse Attention. On a 24 GB RTX 3090 Ti, this drops a 5-second, 0.8 MP clip from ~8 minutes (base, 20 steps) to under 1 minute (draft) or ~2.5 minutes (best quality). Requires the [companion custom node](https://github.com/barelymining/ComfyUI-MiniMax-H3-FastVideo) — you can't load these with a normal LoRA loader alone. |
|
|
| > **Most people should probably use one of the established H3 turbo LoRAs** (e.g. [Comfy-Org's official 4-step turbo](https://huggingface.co/Comfy-Org/MiniMax-H3), [lightx2v's 8-step turbo](https://huggingface.co/lightx2v/Minimax-h3-Turbo)) — they're simpler to set up and don't need a custom node. This project exists for people who want to experiment with FastVideo's sparse-attention approach and see if the speed/quality tradeoff works better for their use case, or for people on older cards (RTX 3090 / 4090) who can't run FastVideo's latest official releases that target Hopper/Blackwell GPUs. Compare and pick what you like. |
|
|
| > ⚠️ **Experimental.** Tested on one machine (RTX 3090 Ti). Requires the companion custom node — this is not a drop-in for standard LoRA loading. See the node repo before downloading. |
|
|
| ## Files |
|
|
| - **`fasth3_vsa_v5.safetensors`** (2.05 GB) — the LoRA (backbone + AdaLN projected into the pruned base's compressed AdaLN space, with q/k/v fused into `qkv_proj` to match Comfy's H3 layout) |
| - **`fasth3_vsa_gate.safetensors`** (3.6 GB) — 50 `to_gate_compress` weight tensors extracted from FastVideo's VSA-DataFree checkpoint, loaded at runtime by the companion custom node |
|
|
| ## Why two files? |
|
|
| FastVideo's VSA training added a `to_gate_compress` layer to each transformer block. That layer doesn't exist in ComfyUI's stock H3 model. A LoRA can only modify existing layers — it can't add new ones. So the gate weights ship separately and are injected at runtime by the custom node. |
|
|
| ## Required companion custom node |
|
|
| You need [ComfyUI-MiniMax-H3-FastVideo](https://github.com/barelymining/ComfyUI-MiniMax-H3-FastVideo) — a ComfyUI custom node that injects the gate layers and routes attention through FastVideo's Triton VSA kernel. |
|
|
| Installation, requirements, workflow, performance numbers, and known limitations are all documented there. |
|
|
| ## Base model |
|
|
| Designed for [`minimax_h3_fl2va_pruned_int8_convrot.safetensors`](https://huggingface.co/Comfy-Org/MiniMax-H3) from Comfy-Org. Other pruned INT8 FL2VA variants should also work if their `adaln_t_table` matches. Not tested with the non-pruned or non-INT8 variants. |
|
|
| ## Quick usage |
|
|
| 1. Install the [companion node](https://github.com/barelymining/ComfyUI-MiniMax-H3-FastVideo) and its `vsa` Python dependency |
| 2. Place both `.safetensors` files here in `ComfyUI/models/loras/` |
| 3. Load with a standard `LoraLoader` (for the `_v5` file) + the `MiniMax H3 VSA (FastVideo + gate)` node (for the gate file) |
| 4. 4 steps, CFG 1.0, `topk_ratio` 0.10 for drafts or 1.0 for finals |
|
|
| ## Provenance / conversion |
|
|
| Converted from FastVideo's [VSA-DataFree checkpoint](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree). Conversion involved: |
| - Renaming Diffusers-style keys to Comfy's H3 naming |
| - Fusing separate q/k/v LoRA branches into Comfy's `qkv_proj` (block-diagonal B, concatenated A, alpha = 3 × rank) |
| - Projecting `adaln_proj.linear.lora_A` from full BF16 space (`[96768, 2688]`) into the pruned model's 8-dim compressed space via least-squares fit against the base's `adaln_t_table` (residual ≈ 0 — mathematically lossless) |
| - Extracting `to_gate_compress.set_weight` tensors into a separate file for runtime injection |
|
|
| ## Attribution |
|
|
| - Original weights: [FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree) |
| - Base model: [MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3), pruned INT8 by [Comfy-Org](https://huggingface.co/Comfy-Org/MiniMax-H3) |
| - VSA kernel: [hao-ai-lab/FastVideo](https://github.com/hao-ai-lab/FastVideo) |
| - Distributed under the [MiniMax H3 Community License](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA/blob/main/LICENSE) |
