HunyuanImage-3.0 HAP:
HunyuanImage3HAP applies head-adaptive attention pruning, abbreviated HAP, to HunyuanImage-3.0 to reduce attention computation when generating images larger than 1024×1024. Attention is the mechanism that lets different parts of an image exchange information during generation; its computational cost can become substantial at higher resolutions. This node uses a method from HRDiT that measures an attention radius for each attention head during the first generation step. After that step, each head limits its attention to nearby image tokens within its measured radius. Image tokens are the small image units processed by the model, and attention heads are separate components that learn different relationships between those units. Using a separate radius for each head makes the restriction adaptive rather than applying the same neighborhood everywhere. The goal is faster attention processing during high-resolution generation, although the supplied code does not establish a specific speed improvement or guarantee identical results to unpruned attention. The pruning has no effect at or below 1024×1024.
HunyuanImage-3.0 HAP Input Parameters:
model
The required MODEL connection supplies the model to which the HAP configuration will be applied. Use a compatible HunyuanImage-3.0 model from your workflow: this is a model-specific patch, not a general attention optimization for every image model. The node clones the supplied model wrapper and attaches its HAP configuration to that clone, leaving the original model connection available for an unpatched workflow branch. This cloning should not be interpreted as loading a second independent copy of all model weights. The node configures how the model will operate during subsequent generation; it does not generate an image itself. This parameter has no numeric minimum, maximum, or default value, and requires a MODEL connection.
mass
The required FLOAT parameter specifies the share of each attention head’s attention that its measured radius must retain. Its default is 0.95, its minimum is 0.5, its maximum is 1.0, and its interface adjustment step is 0.01. For example, 0.95 asks the radius-selection process to retain 95% of that head’s measured attention mass; it does not mean keeping 95% of image tokens or achieving a 95% speed improvement. A higher value sets a stricter retention target and generally allows less aggressive pruning, while a lower value permits a smaller retained attention share and potentially more aggressive pruning. Because the radius is determined separately for each head, the same setting can produce different neighborhoods across heads. Lower values may affect the generated result, so evaluate them visually rather than treating them as a guaranteed quality-preserving optimization. A value of 1.0 requests full attention-mass retention, but the supplied node code does not establish it as an explicit off switch.
HunyuanImage-3.0 HAP Output Parameters:
MODEL
The MODEL output is the cloned model with the HAP plan installed in its transformer options under hy3_hap. Connect this output to the sampling or generation stage that would otherwise receive the original model. Its importance is that the optimization is carried forward through this particular model connection: using the original model on a separate branch does not apply the newly configured HAP plan to that branch. This output is still a model, not an image, latent, attention map, or performance measurement. The node itself only installs the configuration; the compatible HunyuanImage-3.0 implementation uses that configuration during generation, with no pruning effect at or below 1024×1024.
HunyuanImage-3.0 HAP Usage Tips:
- Place the node after your compatible HunyuanImage-3.0 model-loading stage and before sampling. Make sure the sampler receives this node’s MODEL output rather than the original model connection.
- Start with the default
massof 0.95. It provides a 95% attention-mass retention target for each head and is a useful baseline before testing more aggressive pruning. - Use this optimization for high-resolution generation, such as 2048×2048. For images at or below 1024×1024, the documented behavior is no effect, so adding the node will not provide the intended attention speed-up.
- If you want to explore stronger pruning, reduce
massgradually, for example from 0.95 to 0.94 or 0.93. Compare composition, repeated structures, fine detail, and overall visual consistency before lowering it further. - If a lower
massproduces unwanted changes, increase it toward 1.0 or bypass the node for an unpatched comparison. Do not assume that setting 1.0 is identical to removing the patch. - Compare patched and unpatched runs using the same prompt, seed, resolution, sampling settings, and hardware. Measure complete generation time as well as visual results, since faster attention does not necessarily translate into the same proportional improvement for the entire workflow.
- Expect the pruning benefit to begin after the first step. The first step supplies the measurements used to determine the per-head attention radii, so a short test may not represent the benefit over a longer generation.
HunyuanImage-3.0 HAP Common Errors and Solutions:
Missing required input: model or mass
- Explanation: Both inputs are required by the node interface. A missing model connection or missing required value can prevent execution during workflow validation. The exact validation message depends on your ComfyUI version; the supplied node class does not define a custom missing-input message.
- Solution: Connect a compatible HunyuanImage-3.0 MODEL to
modeland ensuremasshas a value, such as the default 0.95.
mass is outside the supported range
- Explanation: The declared range is 0.5 to 1.0. Values outside that range do not match the node’s interface constraints and may be rejected during validation. The node class does not provide a custom error string for this condition.
- Solution: Set
massto a value between 0.5 and 1.0 inclusive. Enter 0.95 for a 95% attention-mass target, not 95.
HAP appears to have no effect
- Explanation: This is a troubleshooting symptom rather than an explicit exception. The node is documented to have no effect at or below 1024×1024. The patch can also be absent from the active generation path if the sampler still receives the original model instead of this node’s output.
- Solution: Test a clearly larger resolution, such as 2048×2048, and trace the MODEL connections to confirm that generation uses the patched output. Use a compatible HunyuanImage-3.0 model.
Incompatible model or patch not recognized
- Explanation: This is a compatibility issue, not a specific error message defined by the node. The implementation installs a HunyuanImage-3.0-specific transformer option; accepting a MODEL connection does not establish that another model family supports it. An incompatible model may ignore the option or fail elsewhere during generation.
- Solution: Use the node with the HunyuanImage-3.0 implementation provided by the relevant custom-node package. If generation fails, inspect the full ComfyUI error log and verify that the installed package and workflow are compatible.
CUDA out of memory
- Explanation: This is a possible runtime error during high-resolution generation, not an error explicitly raised by this node. HAP targets attention computation and does not guarantee that the model, image dimensions, batch size, or other workflow stages will fit in your available GPU memory.
- Solution: Reduce resolution or batch size, close other GPU-heavy applications, and use memory-management options supported by your model and ComfyUI setup. Do not rely on lowering
massas a guaranteed fix for insufficient memory.
Generation is not noticeably faster
- Explanation: This is a performance symptom rather than an exception. HAP targets attention after the first step, while model loading, other model operations, and image decoding still contribute to total runtime. The supplied code does not promise a fixed speed-up.
- Solution: Compare repeated runs after model loading under otherwise identical conditions. Test at a resolution above the documented threshold and start with
massat 0.95; consider gradually lower values only if the resulting image quality remains acceptable.
Generated images change after enabling HAP
- Explanation: This is a possible consequence of restricting attention rather than a validation error. A lower retention target permits more attention to be excluded, and the supplied source does not guarantee that pruned generation will match an unpatched result.
- Solution: Increase
massand compare against an unpatched run with the same seed and settings. If preserving the unpatched result is more important than the potential attention speed-up, bypass the node.
