README.md

---
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)