Nodes/comfyui-svdint4/Configure Sol Sparse Attention
ComfyUI Node

Configure Sol Sparse Attention

Configure Sol Sparse Attention

By wjie98·Created 2 months ago·Updated 3 days ago· 2
Configure Sol Sparse Attention
  • model
  • model
routing_threshold1.0
prefix_policyauto
manual_prefix_tokens0
skipped_residual1x64
sparse_reference_imagefalse
sparse_reference_videotrue
sparse_reference_audiofalse
dense_prefix_steps1
dense_suffix_steps0
dense_prefix_layers2
dense_suffix_layers0
debug_route_densityfalse

That video model you're sampling is spending most of its time attending over every one of a few thousand tokens - when, for any given 128-token window, most of those K/V tokens barely matter. Configure Sol Sparse Attention is the "stop doing that" switch. You drop a MODEL in, you get a patched MODEL out, and the sampling that follows computes far fewer attention blocks. It's a pure performance patch from wjie98's ComfyUI Turing Utils pack (the repo is comfyui-svdint4 - the folder name and the branding inside disagree, that's normal here), the same pack that brings you the ConvRot INT8 loaders. If you run long-context video - Wan, Bernini, MiniMax H3 - on a 20- or 30-series card with no fp8 acceleration, attention is where the seconds go, and this is the node that spends them differently.

How it works

Sol is a model-generic sparse-attention backend: no particular loader required. For every 128-token query block, it decides which 64-token K/V blocks to compute exactly and which to approximate. Each block gets a cheap proxy score, computed on the same prequantized INT8 Q/K tensors that the exact path uses, and a block is skipped when its score beats mean + routing_threshold × std. Skipped blocks aren't deleted - each is replaced by one 64-token centroid (the default 1x64 mode) that still contributes an online-softmax correction, so V comes out approximately right rather than missing. 2x32 keeps two residual centroids per skipped block for better fidelity without changing which blocks route. Whether the numeric path is integer (W8A8) or FP16 depends on the dense backend your model inherits from Load ConvRot DiT - w8a8 picks the INT8 Tensor Core path, sage/sdpa the floating one.

It's a "strategy" node, which is a rename and a small upgrade: the old Patch Sol Sparse Attention is still registered so saved workflows don't break, but the Configure version inherits its dense backend from the loader instead of asking you to flip a use_w8a8 checkbox. Use the new one in fresh workflows.

The inputs that matter

  • routing_threshold - the dial. Default 1.0 matches the official Sol policy. Lower it and more blocks stay exact (slower, closer to dense); raise it and more get skipped.
  • dense_prefix_layers / dense_prefix_steps - defaults 2 layers and 1 step keep the first layers and the first denoising step fully dense. This is the "don't let the first pass mangle the structure" guard; raise it if early frames look off, lower it for max speed.
  • sparse_reference_image / _video / _audio - false, true, false by default. Long reference-video blocks get sparsified; keyframes, reference images, and dialogue/audio conditioning stay exact unless you deliberately flip them.
  • prefix_policy - auto applies the model's own semantic layout; manual protects just the leading manual_prefix_tokens tokens.

Everything flows out through the single model output, straight into your sampler.

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/wjie98/comfyui-svdint4
cd comfyui-svdint4
python -m pip install -v --no-build-isolation -e ./kernel

That last line is the part people miss. requirements.txt deliberately excludes the CUDA kernel so ComfyUI Manager won't silently kick off a compile - the kernel build is an explicit step either way, and it compiles for every visible GPU (a 2080 Ti + 3070 box builds 7.5;8.6 in one pass). GPU-less build hosts fall back to 7.5; set COMFYUI_TURING_UTILS_ARCH_LIST to override. You need a CUDA NVIDIA GPU (Turing/Ampere/Ada or newer), Python 3.10+, and PyTorch with CUDA. ConvRot models additionally want comfy-kitchen>=0.2.26.

Troubleshooting

  • No speedup, no errors. The node falls back to the dense backend (eventually SDPA) when the kernel isn't built or the model didn't come through the ConvRot loader. Pair it with Load ConvRot DiT so the W8A8 integer path actually engages, and confirm the kernel installed.
  • Short sequences auto-crossover to dense. Sol is pointless below its minimum sequence length - it only pays off on genuinely long contexts.
  • Watch the dense guardrails. If dense_prefix_layers + dense_suffix_layers reaches the model's layer count, every layer runs dense and the sparse path silently disables. That's intentional, not a bug.
  • Slow at high sparsity with video references? That's sparse_reference_video defaulting to true. If the reference video is the part that matters, flip it off.
CategoryTuring Utils/patches

Inputs (13)

NameTypeDefaultDescription
modelMODEL
routing_thresholdFLOAT1.0-4–4Route blocks whose input-adaptive proxy score exceeds mean + threshold × standard deviation. Lower values preserve more exact blocks; 1.0 matches the official Sol policy.
prefix_policyCOMBOautoAuto applies the model's semantic segments and the three reference switches; none protects no modality ranges; manual protects only the leading token count below.
manual_prefix_tokensINT00–262144Leading Query tokens kept dense and leading K/V tokens kept exact only for manual policy. Boundaries round outward to 64-token blocks.
skipped_residualCOMBO1x64Official-style 1x64 uses one K/V centroid per skipped block. 2x32 keeps two residual centroids for higher approximation quality without changing routing.
sparse_reference_imageBOOLEANfalseAllow reference-image Query/KV interactions to use Sol routing. Disabled protects keyframes and reference images with dense Query and exact KV blocks.
sparse_reference_videoBOOLEANtrueAllow long reference-video and pose/control-video Query/KV interactions to use Sol routing instead of protecting the complete control sequence.
sparse_reference_audioBOOLEANfalseAllow reference-audio Query/KV interactions to use Sol routing. Disabled preserves reference audio and dialogue conditioning exactly.
dense_prefix_stepsINT10–1000Leading steps of every sampler invocation that use the loader-selected dense backend across every transformer layer.
dense_suffix_stepsINT00–1000Trailing steps of every sampler invocation that use the loader-selected dense backend across every transformer layer.
dense_prefix_layersINT20–256Leading transformer layers kept on the loader-selected dense backend during sparse steps.
dense_suffix_layersINT00–256Trailing transformer layers kept on the loader-selected dense backend during sparse steps.
debug_route_densityoptBOOLEANfalseLog min/mean/max route density once per denoising step. Disabled by default; enabling it adds tiny reductions and one synchronization per step.

Outputs (1)

NameTypeDescription
modelMODEL