Patch Sol-Attn:
SolAttnPatch applies Sol-Attn to eligible self-attention during image or video generation. Self-attention helps the model relate one part of its working sequence to another; Sol-Attn aims to reduce the work involved by processing selected attention blocks exactly while using a sparser approach elsewhere. This can make long sequences less costly to process, although the speed and visual-quality tradeoff depends on your model, sequence length, and settings. The node can also preserve attention to packed conditioning information on MiniMax-H3 and optionally reorder video tokens to improve how nearby content is grouped. It is experimental and deliberately limited: unsupported attention calls continue through the existing attention backend rather than being forced through Sol-Attn.
Patch Sol-Attn Input Parameters:
model
The model you want to patch. Connect a MODEL from your model-loading or upstream model-patching workflow. The node clones this model and returns the patched clone, so connect its output to the rest of your generation workflow. No default, minimum, or maximum is specified.
tau
Controls the sparsity threshold: higher values generally keep fewer attention blocks in the exact branch, reducing work but potentially increasing approximation error. The source tooltip gives approximate exact-block proportions of 16% at 1.0, 7% at 1.5, and 2.7% at 2.0; these are guidance, not a promise of speed or image quality. Start near the default and compare results before increasing it. Default: 1.3; minimum: 0.0; maximum: 4.0; step: 0.05. A per-block profile can override this value for selected blocks.
start_percent
Sets the point in sampling before which attention stays dense. This lets early steps run without Sol-Attn sparsification; the source notes that the cited paper uses 0.2. The node converts this percentage to a model-specific sigma threshold, so it is a fraction of the sampling schedule, not a token count. Default: 0.2; minimum: 0.0; maximum: 1.0; step: 0.01.
end_percent
Sets the point in sampling after which attention returns to the existing dense backend. Together with start_percent, it defines the part of the sampling schedule in which Sol-Attn may run, subject to its other eligibility checks. Default: 0.9; minimum: 0.0; maximum: 1.0; step: 0.01.
min_tokens
Keeps sequences shorter than this threshold on the existing attention path. Sparse processing has setup work, so a threshold helps focus Sol-Attn on longer sequences where it may be more worthwhile. Lowering it allows shorter sequences to be considered but does not guarantee they will use Sol-Attn: other compatibility checks still apply. Default: 4096; minimum: 0; maximum: 1048576; step: 512.
int8_qk
Enables INT8 arithmetic for the exact branch’s query–key calculation. This can help performance when the exact branch remains relatively large; the source tooltip says it helps at tau values of 1.5 or below in its measurements, but can be a net loss at 2.0 or above because quantization work outweighs the smaller exact branch. Default: true; options: true or false. Enabling it requires the INT8 kernel to be available.
sink_conditioning
Controls how MiniMax-H3’s packed text, audio, and reference-conditioning rows are protected from sparse approximation. exact_kv makes every query attend to those conditioning rows exactly; exact_kv_and_rows also runs the conditioning query rows densely, making the generated audio stream exact according to the source tooltip; off disables this special handling. The tooltip estimates roughly 3% cost for exact_kv and 20% for exact_kv_and_rows, without specifying a universal performance baseline. This setting has no effect on other models. Default: exact_kv_and_rows; options: exact_kv, exact_kv_and_rows, off.
morton
Optionally reorders video tokens into Morton, or Z-order, so tokens in a processing block represent a more compact neighborhood. This is intended to improve sparse-attention routing at a given density; the source describes it as neutral for dense attention. It applies to supported Wan-style and MiniMax-H3 models only. For other model types, reordering is skipped and a warning is logged, while Sol-Attn may still operate. Default: false; options: true or false.
morton_curve
Chooses the reordering pattern when morton is enabled and supported. 3d interleaves time, height, and width; 2d_frame orders tokens within each frame while leaving frame order intact. The source recommends trying 2d_frame when frame spacing is uneven, as on MiniMax-H3, or when 3d degrades results at some frame counts. It does not change anything when Morton reordering is inactive. Default: 2d_frame; options: 3d, 2d_frame.
int8_pv
Also uses INT8 arithmetic for the exact branch’s probability–value calculation. It provides the other part of the intended INT8 performance benefit, but applies only when int8_qk is enabled; turning it on alone has no stated effect. Default: true; options: true or false.
verbose
Enables more detailed logging, including information about the selected attention path and conditioning sink when applicable. Use it to check whether your configuration is taking effect or why a call falls back; it does not itself change the intended visual result. Default: false; options: true or false.
use_tma
Requests TMA descriptor kernels instead of pointer-based kernels. The source says descriptors can address strided inputs directly, but this path is off by default because it was not faster on tested GPUs. It requires an SM90-or-newer GPU and Triton 3.3 or newer; otherwise the request is ignored. Enable verbose to see which path is used. Default: false; options: true or false.
dense_blocks
Lists transformer blocks that must retain dense attention. Use comma-separated indices and ranges, such as 0-2,-1 for the first three blocks and the last block; negative indices count backward from the end. This is useful when particular blocks show visible sensitivity to approximation. An empty string leaves all blocks eligible for sparsification, subject to other checks. Default: an empty string; no length limit or numeric input range is specified. Indices outside the available block range select no block, and models without an indexable .blocks list ignore this setting with a warning.
tau_profile
An optional STRING input for assigning different tau values to selected transformer blocks while leaving other blocks at the base tau. Connect a text source containing entries such as 0-30=2.0; 39-42=0.9; semicolons or newlines separate entries, # begins a comment, and later entries win where ranges overlap. Block selections follow the same index-and-range syntax as dense_blocks. Leave it unconnected to use one tau throughout. No default value or numeric limit for the values inside the string is specified; on a model without an indexable .blocks list, the profile is ignored with a warning.
Patch Sol-Attn Output Parameters:
MODEL
The single MODEL output is a clone of the input model configured with the Sol-Attn attention override and any applicable supporting options. Connect it where your workflow expects a model for sampling. It is not an image, a performance measurement, or a guarantee that every attention call will be sparse: masked calls, calls outside the configured sampling window, ineligible sequences, and kernel failures can use the prior attention override or existing backend instead.
Patch Sol-Attn Usage Tips:
- Start with the defaults, generate a reference result, and change one setting at a time. Compare both generation time and the details you care about; the source’s sparsity percentages do not directly predict either outcome.
- For long sequences, keep
min_tokensat4096initially. Lower it only after checking that shorter sequences benefit in your workflow. - If early structure or late details suffer, keep more sampling steps dense by raising
start_percentor loweringend_percent. The default window is0.2through0.9. - If certain transformer depths are sensitive, place them in
dense_blocksor connect atau_profilethat gives those blocks a lowertau. Use measured block behavior rather than assuming one setting fits every model. - On MiniMax-H3, retain
exact_kv_and_rowswhen preserving its packed conditioning and generated audio behavior matters most. Tryexact_kvif you want the less costly option described by the source, then compare results. - For supported video models, test
mortonwith the default2d_framecurve. Compare with3donly when your frames have suitable temporal spacing and the actual results justify it. - Keep
int8_qkandint8_pvenabled while testing lowertauvalues. At highertauvalues, benchmark with INT8 disabled as well, since quantization overhead can outweigh its benefit. - Leave
use_tmaoff unless your hardware and Triton version meet its requirements and your own measurements show an improvement. Turn onverbosewhen checking the selected path or investigating fallback behavior.
Patch Sol-Attn Common Errors and Solutions:
Sol-Attn kernel unavailable: ...
- Explanation: The required Sol-Attn kernel did not load, so the node stops before patching the model. The text after the colon contains the underlying import error.
- Solution: Read the full error in the ComfyUI console, then check that this extension and its required dependencies are installed in the environment running ComfyUI. Resolve the reported import issue and restart before retrying.
Sol-Attn INT8 kernel unavailable: ...
- Explanation:
int8_qkis enabled, but the separate INT8 kernel did not load. The underlying reason follows the colon. - Solution: Check the console’s import error and restore the missing or incompatible kernel dependency. To test the non-INT8 path in the meantime, turn off
int8_qk;int8_pvonly applies whenint8_qkis on.
cannot parse block spec '...'; use indices and ranges like '0-3,47,-1'
- Explanation: A block selection in
dense_blocksortau_profiledoes not match the supported comma-separated index-and-range syntax. - Solution: Use whole-number indices and ranges, such as
0-2,-1or0-2,47; remove labels and other punctuation from the block selection.
tau_profile entry '...' needs '=', e.g. '39-42=0.9'
- Explanation: A nonempty profile entry names blocks but does not assign a
tauvalue. - Solution: Write each entry as
blocks=value, such as39-42=0.9, and separate entries with semicolons or newlines.
tau_profile entry '...' has a non-numeric tau
- Explanation: The value after
=cannot be read as a number. - Solution: Replace it with a numeric value such as
1.3. Put any explanation after#as a comment rather than inside the number.
[sol_attn] dense_blocks/tau_profile ignored: ... has no .blocks list to index
- Explanation: The model does not expose the block list needed for per-block settings. This is a warning; the node clears those settings and continues.
- Solution: Leave
dense_blocksempty andtau_profileunconnected for that model, or use a compatible model with an indexable block list.
[sol_attn] Morton reordering skipped: ... is neither Wan-style nor MiniMax-H3. Sol-Attn itself still applies.
- Explanation:
mortonis on, but the detected model is not one of the supported reordering types. This warning does not mean the entire node failed. - Solution: Turn off
mortonfor that model. Keep it enabled only when using a supported Wan-style or MiniMax-H3 model and you intend to compare reordered results.
No visible speedup or Sol-Attn activity
- Explanation: This is not necessarily an error. A sequence may be shorter than
min_tokens, fall outside the sampling window, use a mask, fail another kernel eligibility check, or fall back after a kernel error. The node description also limits the optimized path to bf16 with head dimension 128. - Solution: Enableverboseand inspect the console. Check sequence length, model compatibility, sampling-window settings, and any reported kernel failure before changing quality-sensitive controls.
use_tma appears to have no effect
- Explanation: The source says TMA is ignored when its SM90-or-newer GPU and Triton 3.3-or-newer requirements are not met; it also does not promise a speed gain on supported systems.
- Solution: Enable
verboseto inspect the chosen path. Leaveuse_tmaoff unless your environment supports it and a direct benchmark shows a benefit.
