piper-nodes

Piper Nodes

ComfyUI nodes for optimized inference operators from the Piper package family.

The initial release focuses on attention operators from piper-kernels. It provides two model patch nodes:

• Piper Attention
• Piper SageAttention2++

Both nodes accept and return a ComfyUI MODEL. They apply the selected operator to compatible attention calls without modifying the input model.

Requirements

• Python 3.13 or newer
• ComfyUI
• An NVIDIA GPU supported by the selected Piper attention operator
• Windows or Linux

The piper-kernels[triton] dependency selects triton-windows on Windows and stock Triton on Linux.

Installation

Clone this repository into ComfyUI's custom_nodes directory, then install its requirements with the Python interpreter used by ComfyUI:

python -m pip install -r custom_nodes/piper-nodes/requirements.txt

Restart ComfyUI after installation. The nodes appear under Piper/Kernels/Attention.

Compatibility and fallback

The integration uses Piper attention when a call satisfies the operator contract. It delegates to the attention implementation already selected by ComfyUI when a call uses:

• an attention mask or grouped-query attention;
• a dtype or head dimension not supported by the selected operator;
• training or explicitly requested FP32 attention; or
• an accelerator not supported by the selected optimized backend.

Piper Attention is selected on NVIDIA SM8x and SM12x. Piper SageAttention2++ is selected on NVIDIA GPUs with compute capability 8.9 or newer. Kernel execution errors are not silently swallowed.

If another model node already installed a ComfyUI attention override, Piper preserves it as the fallback implementation.

Development

uv sync --dev
uv run ruff check .
uv run pyright
uv run pytest

The repository deliberately keeps ComfyUI-specific code separate from Piper's operator implementations:

• piper_comfyui/nodes defines the ComfyUI node contracts.
• piper_comfyui/adapters translates ComfyUI attention layouts and call options.
• piper_comfyui/compat isolates the small ComfyUI model-patching seam.

ConvRot and integrations with other Piper packages are intentionally outside the initial scope.