Update README.md

README.md

@@ -14,4 +14,53 @@ tags:
 - fasth3
 - vsa
 - sparse-attention
----
+---
+
+# FastH3 VSA-DataFree LoRA + Gate for ComfyUI (experimental)
+
+Two files that let you run **FastVideo's Video Sparse Attention (VSA) 4-step distillation LoRA** for MiniMax H3 inside ComfyUI's native H3 stack, without needing FastVideo's own inference pipeline.
+
+> ⚠️ **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
+
+Conversion script (`convert_fastvideo_vsa_to_comfy.py`) is in the [node repo](https://github.com/barelymining/ComfyUI-MiniMax-H3-FastVideo) if you want to re-run it yourself.
+
+## 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)