ComfyUI-FastH3-VSA

Experimental preview: this repository makes FastVideo's four-step FastH3 VSA checkpoint run through ComfyUI today. It depends on an unmerged two-file ComfyUI loader change and a specific official Comfy Kitchen build. Read the pinned installation steps before opening an issue.

Latest local strict-VSA generation
5.17 s · 608 × 352 · 124 frames · synchronized stereo audio · 300 VSA calls · 0 fallbacks

Play or download with audio · Exact hero workflow · Core-sampler quick start

This pack adds learned VSA (Variable Sparse Attention) execution for the FastH3 T2VA preview checkpoint. It uses ComfyUI's ModelPatcher lifecycle and Comfy Kitchen's native chunked Sol-Attn/VSA kernel. It does not make network requests at runtime.

The FastH3 model card describes four transformer forwards, synchronized video/audio output, and VSA-H3 training at 90% sparsity. This integration retains 10% of video blocks by default to match that training setup.

• FastH3 model card: https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree
• Draft ComfyUI loader support: Comfy-Org/ComfyUI#15958
• Merged Comfy Kitchen kernel work: Comfy-Org/comfy-kitchen#117

Start here

Required FastH3 checkpoint: minimax_h3_fastvideo_vsa_datafree_1300step_4step_int8_convrot.safetensors (22.9 GB). Place it in ComfyUI/models/diffusion_models.

Complete the pinned installation and model download, then choose one of these workflows:

Goal	Workflow	Additional requirement
Prove VSA with the fewest moving parts	fast_h3_vsa_t2va_workflow.json	None beyond this repository's pinned stack
Reproduce the hero recipe exactly	fast_h3_vsa_hero_res2s_workflow.json	RES4LYF at e716cd1cb2c5cff90131bf4914b75b75a0489d48
Submit the hero graph through the API	fast_h3_vsa_hero_res2s_api.json	RES4LYF at the same commit

The dependency-light workflow is the recommended first proof. Load it in ComfyUI, leave its model filenames and strict VSA settings unchanged, and queue it once. The exact hero graph is an optional reproduction of the video above.

Hero demo recipe

The linked MP4 is the byte-for-byte ComfyUI output and retains its embedded prompt and workflow metadata. Its prompt was:

An amazing single-shot high energy 2D anime scene; a girl holding a teddy bear throws the bear up toward the sky and the bear grows quickly into a protector - ready for battle.

Setting	Hero value
Seed	703916324385509
Size	608 × 352 × 124 frames at 24 fps
VSA	10% keep, min_tokens=0, failure_mode=error
Sigma shift	video 12 / audio 3
Scheduler	linear_quadratic, 3 steps, denoise 1.0
Sampler	res_2s from RES4LYF
Strict VSA result	300 kernel calls, 0 dense fallbacks, 0 errors

Although KSamplerSelect is a core node, res_2s is registered by RES4LYF. Install the exact revision only if you want to reproduce the hero recipe:

git clone https://github.com/ClownsharkBatwing/RES4LYF.git `
  "$ComfyApp\custom_nodes\RES4LYF"
git -C "$ComfyApp\custom_nodes\RES4LYF" checkout `
  e716cd1cb2c5cff90131bf4914b75b75a0489d48

The exported hero graph preserves allow_unsupported_conditioning=true from the recorded run. Its actual conditioning is native T2VA, so that override was not exercised; keep the option false in new workflows. The three-step res_2s recipe performs two model evaluations per step and is not directly comparable to the four-step timing later in this README.

Nodes

• FastH3 VSA Patch (Experimental) patches all 50 main MiniMax H3 attention blocks and emits a preflight report.
• FastH3 VSA Inspect reports gate-layer, CUDA-device, native-extension, and patch readiness without exposing local filesystem paths.

Support boundary

The following is validated:

• Windows, one NVIDIA CUDA GPU, and the exact stack below.
• Native MiniMax H3 text-to-audio-video conditioning.
• Four simple scheduler steps with res_multistep.
• BF16 model compute and the 22.9 GB INT8 ConvRot FastH3 checkpoint.
• 50 H3 blocks with head dimension 128.

The following is not validated:

• Linux, WSL, other GPU architectures, or less VRAM.
• AMD, Intel, Apple Silicon, CPU, or DirectML.
• ComfyUI MultiGPU.
• FL2VA or Ref2VA. The preview checkpoint was distilled for T2VA only.
• Combining this node with SageAttention, a general Sol-Attn patch, or another H3 attention patch.

The node enforces CUDA SM80 or newer, exactly 50 H3 blocks, head dimension 128, complete VSA gate weights, and one GPU. The tested card had 32 GiB VRAM; that is a tested configuration, not a claimed minimum.

Exact tested environment

Captured on 2026-08-31:

Component	Exact tested value
OS	Windows 11 Pro Insider Preview x64, 10.0.26300
ComfyUI runtime	0.33.1
Reproducible ComfyUI base	tag v0.33.1, commit 72865f4f27eaf5396f8f36370e0a2be3a9a090ee, plus the bundled patch
Original local checkout	21e42ee029abbe0a1c171e71c5732d8849edde3c; the two relevant files matched v0.33.1 before patching
ComfyUI frontend	1.48.7
Workflow templates	0.11.41
Python	3.11.0
PyTorch	2.10.0+cu130
torchvision	0.25.0+cu130
torchaudio	2.10.0+cu130
CUDA runtime used by PyTorch	13.0
cuDNN	9.12.0
triton-windows	3.6.0.post26
Comfy Kitchen	development wheel labelled 0.2.31, commit dae00a13d458876570804523ae045a487fd92961
NVIDIA driver	620.02, reporting CUDA 13.2
GPU	NVIDIA RTX PRO 4500 Blackwell, SM120, 34,179,055,616 bytes VRAM
System RAM	approximately 64 GiB
Tested launch flags	--disable-pinned-memory --enable-triton-backend --cache-lru 1

The launch flags describe the test machine; this project has not established that each flag is mandatory.

Installation: exact Windows/Python 3.11 path

These commands reproduce the tested directory layout. Adjust only the two path variables if your ComfyUI install lives elsewhere.

1. Use the tested ComfyUI base

For a fresh source install:

git clone https://github.com/Comfy-Org/ComfyUI.git C:\ComfyUI\app
git -C C:\ComfyUI\app checkout 72865f4f27eaf5396f8f36370e0a2be3a9a090ee

Set the tested paths:

$ComfyApp = 'C:\ComfyUI\app'
$ComfyPython = 'C:\ComfyUI\.venv\Scripts\python.exe'

Create the tested Python/Torch base if this is a fresh checkout:

py -3.11 -m venv C:\ComfyUI\.venv
& $ComfyPython -m pip install --upgrade pip
& $ComfyPython -m pip install `
  'torch==2.10.0+cu130' `
  'torchvision==0.25.0+cu130' `
  'torchaudio==2.10.0+cu130' `
  --index-url https://download.pytorch.org/whl/cu130
& $ComfyPython -m pip install -r "$ComfyApp\requirements.txt"

The tested Python environment was a regular venv, not ComfyUI Portable. Portable users must point $ComfyPython at their embedded Python executable and select a wheel matching that Python version. The tested install also had triton-windows==3.6.0.post26; the native VSA path itself does not import Triton.

2. Clone this node pack

git clone https://github.com/exportAnything/ComfyUI-FastH3-VSA.git `
  "$ComfyApp\custom_nodes\ComfyUI-FastH3-VSA"

There is deliberately no requirements.txt. Installing ordinary comfy-kitchen==0.2.31 from PyPI would install the wrong binary for this preview.

3. Apply the bundled ComfyUI gate-loader patch

Stock ComfyUI 0.33.1 drops the FastH3 VSA gate projections because it does not construct those modules. Apply the pinned compatibility patch from the ComfyUI repository root:

Set-Location $ComfyApp
$CorePatch = 'custom_nodes\ComfyUI-FastH3-VSA\patches\comfyui-0.33.1-fasth3-gates.patch'
git apply --check $CorePatch
git apply $CorePatch

The patch changes only:

• comfy/ldm/minimax/model.py
• comfy/model_detection.py

It constructs to_gate_compress on every detected VSA block and rejects a partially gated checkpoint. It follows draft ComfyUI PR #15958, head 10febb01d7be73d1491cf5e5347b5ab8b6c2c09e, with stricter 50/50 gate validation.

Do not reapply this patch after equivalent support lands upstream. A failed git apply --check is a reason to inspect the current ComfyUI diff, not to use --force.

4. Install the exact Comfy Kitchen wheel

The required Sol-Attn/VSA code is in official Comfy Kitchen merge commit dae00a13d458876570804523ae045a487fd92961. The wheel used here came from successful official Actions run 33281832369, artifact wheels-windows-cuda-hip-3.11.

Important: PyPI's wheel is also labelled 0.2.31, but it is an older binary without the required sol_attn_chunked API. Version text alone is insufficient.

Install GitHub CLI, run gh auth login, and then:

$WheelDir = Join-Path $env:TEMP 'comfy-kitchen-dae00a1'
New-Item -ItemType Directory -Force -Path $WheelDir | Out-Null

gh run download 33281832369 `
  --repo Comfy-Org/comfy-kitchen `
  --name wheels-windows-cuda-hip-3.11 `
  --dir $WheelDir

$Wheel = Get-ChildItem -LiteralPath $WheelDir `
  -Filter 'comfy_kitchen-0.2.31-cp311-cp311-win_amd64.whl' |
  Select-Object -First 1 -ExpandProperty FullName

$ExpectedWheelHash = 'C3A940DD102113F647E0C6D5E75FEBAF6A12721D77E6281E384B0A0EB63F1FD8'
if ((Get-FileHash -Algorithm SHA256 -LiteralPath $Wheel).Hash -ne $ExpectedWheelHash) {
    throw 'Unexpected Comfy Kitchen wheel hash'
}

& $ComfyPython -m pip install --force-reinstall --no-deps --no-cache-dir $Wheel

Exact wheel manifest:

file: comfy_kitchen-0.2.31-cp311-cp311-win_amd64.whl
size: 48,157,851 bytes
sha256: c3a940dd102113f647e0c6d5e75febaf6a12721d77e6281e384b0a0eb63f1fd8
source commit: dae00a13d458876570804523ae045a487fd92961
Actions artifact id: 9723433945
artifact expiry: 2026-11-27

The official run also contains other Python and Linux artifacts, but this pack has only been tested with the Windows CPython 3.11 wheel.

Verify the native extension before starting ComfyUI:

& $ComfyPython -c @'
import comfy_kitchen
from comfy_kitchen.backends import cuda

required = (
    'sol_attn_plan',
    'sol_producer_begin',
    'sol_producer_chunk',
    'sol_attn_core',
)
assert callable(getattr(comfy_kitchen, 'sol_attn', None))
assert callable(getattr(cuda, 'sol_attn_chunked', None))
assert getattr(cuda, '_EXT_AVAILABLE', False)
assert all(callable(getattr(cuda._C, name, None)) for name in required)
print('Comfy Kitchen native VSA APIs: ready')
'@

5. Download the exact model files

Model weights are not included in this repository.

Using the Hugging Face hf CLI:

hf download Kijai/MiniMax-H3-experimental `
  minimax_h3_fastvideo_vsa_datafree_1300step_4step_int8_convrot.safetensors `
  --local-dir "$ComfyApp\models\diffusion_models"

hf download Comfy-Org/MiniMax-H3 `
  text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors `
  vae/minimax_h3_video_vae_fp16.safetensors `
  vae/minimax_h3_audio_vae_fp32.safetensors `
  --local-dir "$ComfyApp\models"

Exact tested model manifest:

ComfyUI path	Bytes	SHA256
models/diffusion_models/minimax_h3_fastvideo_vsa_datafree_1300step_4step_int8_convrot.safetensors	22,898,594,920	7221ae65d78780354d51e5048d29728d9f1f8fb9baf50b1dd3df85f5101413d3
models/text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors	15,687,142,551	35a88d51044231fe332301d7a62aa81e3f2cba62febeb446e2c1e3e0ef76f2c6
models/vae/minimax_h3_video_vae_fp16.safetensors	5,207,808,496	7c1f131492e7eddacaac9069a61b81bdd39de5cc96561e677c5eab1cdce5e522
models/vae/minimax_h3_audio_vae_fp32.safetensors	605,254,808	8e505d95dd1561d47abd43d4238fd40d9bb1ae9e147ed0a4cba778d76ae4db48

The converted checkpoint contained 1,082 state-dict keys, including all 50 to_gate_compress.weight entries and their quantization metadata.

Restart ComfyUI after installing the wheel, applying the core patch, and cloning this repository.

Recommended workflow

Load examples/fast_h3_vsa_t2va_workflow.json, or construct the native MiniMax H3 T2VA graph:

UNETLoader
  -> FastH3 VSA Patch
  -> MiniMaxH3SigmaShift
  -> BasicScheduler / BasicGuider / SamplerCustomAdvanced

First-test settings:

Setting	Value
UNET weight dtype	default
VSA keep percent	10.0
VSA min tokens	0
VSA failure mode	error
Allow unsupported conditioning	false
Sigma shift video/audio	12.0 / 3.0
Scheduler	simple, 4 steps, denoise 1.0
Sampler	res_multistep
Example size	608 x 352 x 124 frames
Output	24 fps H.264 video with stereo AAC audio

Use MiniMaxH3ImageToVideo without first/last images for native T2VA conditioning. Do not add a Turbo LoRA or another attention optimization to the proof workflow.

The equivalent API graph is examples/fast_h3_vsa_t2va_api.json.

To recreate the repository hero instead, use the optional RES4LYF hero workflow documented in Hero demo recipe.

Proving that VSA actually ran

Keep failure_mode=error and min_tokens=0. A successful four-step render must produce:

[FastH3 VSA] kernel active: sequence=... padded=... video_keep=10.0% block=64
[FastH3 VSA] run complete: kernel_calls=200 dense_fallbacks=0 errors=0 ...

Four model forwards multiplied by 50 attention blocks equals 200 kernel calls. If the summary is missing, or if any dense fallback occurred, the render is not a strict VSA validation.

The final local validation produced:

• 124 H.264 frames at 608 x 352 and 24 fps.
• 32 kHz stereo AAC audio.
• Matched video/audio durations of approximately 5.17 seconds.
• 200 VSA calls, zero dense fallbacks, and zero errors.

In one deliberately small 608 x 352 comparison, VSA denoising took about 7.8 seconds versus 8.6 seconds for dense attention, approximately 1.1x. This is one low-resolution measurement, not a general speedup claim. Benchmark your actual resolution and duration; Comfy Kitchen can favor dense attention at shorter sequences.

Tests

From the ComfyUI application directory:

& $ComfyPython -m unittest discover `
  -s custom_nodes\ComfyUI-FastH3-VSA\tests `
  -v

The repository tests cover T2VA layout acceptance, unsupported reference-layout rejection, and exact VSA tile/inverse mapping.

Troubleshooting

• Inspect says gates are missing: the ComfyUI compatibility patch is absent or ComfyUI was not restarted after applying it.
• Inspect says native VSA APIs are missing: the ordinary PyPI 0.2.31 wheel is installed instead of the official dae00a1 Actions artifact.
• Patch node reports another attention patch: remove SageAttention, general Sol-Attn, or other H3 attention patch nodes.
• Strict mode raises: preserve the full chained exception and server log when opening an issue. Do not switch to dense fallback and report the result as VSA.
• Out of memory: reduce width, height, or frame count. Minimum VRAM has not been established.
• MultiGPU error: this preview integration intentionally rejects ComfyUI MultiGPU clones.

Rollback

Bypass or remove the FastH3 VSA Patch node to return the workflow to dense attention.

To remove the compatibility patch while still on the exact tested ComfyUI base:

Set-Location $ComfyApp
git apply --reverse `
  'custom_nodes\ComfyUI-FastH3-VSA\patches\comfyui-0.33.1-fasth3-gates.patch'

To restore the ordinary PyPI Kitchen wheel:

& $ComfyPython -m pip install --force-reinstall --no-deps --no-cache-dir `
  'comfy-kitchen==0.2.31'

The ordinary wheel disables this preview path because it lacks the required native APIs.

Upstream and licensing

As checked on 2026-08-31:

• ComfyUI PR #15958 was an open draft at head 10febb01d7be73d1491cf5e5347b5ab8b6c2c09e.
• Comfy Kitchen PR #117 was merged as dae00a13d458876570804523ae045a487fd92961.
• The matching PyPI Kitchen release had not yet been published under a new version.

This repository is GPL-3.0 licensed. See LICENSE and NOTICE.

Model files are not redistributed. FastH3 and MiniMax H3 weights remain subject to their source repositories and the MiniMax H3 Community License. This project is an independent experimental integration and is not an official FastVideo, MiniMax, ComfyUI, or NVIDIA release.