SSR Load Aligner

LoadSSRAligner ("SSR Load Aligner") is the first node you'll drop into an SSR-Encoder workflow, and also the most forgettable - which is the point. It loads one ~25MB file (ssr_aligner.safetensors) from your ComfyUI/models/ssr folder and hands you an SSR_ALIGNER wire. That wire feeds every EncodeSSRQuery node in your graph, and without it the query side of the pipeline has nothing to run on.

Why you'd reach for it

Every node in this pack is a piece of the SSR-Encoder mechanism from the CVPR 2024 paper (Xiaojiu-z et al.). The "aligner" is the token-to-patch network that's the whole trick behind SSR's selectivity: it takes your text query and your reference image and works out which patches of the image match what the query is describing. That's how the pipeline can pull the fur out of a wolf-woman photo and leave the woman behind. LoadSSRAligner is just the loader that makes the aligner available - small job, but nothing downstream happens without it.

How it works

The mechanics are dead simple, and that's a feature. The node scans ComfyUI/models/ssr for checkpoint files, presents them in its checkpoint dropdown, and when you pick one it loads the safetensors state dict into a freshly built SSRAligner - a small transformer with a 768-dim query space (matching SD 1.5's CLIP text encoder), a 1024-dim vision space (matching CLIP ViT-L/14), and six parallel attention heads. Six heads, six vision layers: EncodeSSRQuery grabs exactly six intermediate vision features and hands each to one head. That structural match is why the dimensions are what they are.

Inputs and outputs

One input, one output:

checkpoint - a dropdown listing every .safetensors file in ComfyUI/models/ssr. Pick the aligner.
SSR_ALIGNER - the loaded model, wired into EncodeSSRQuery's ssr_aligner input.

That's the entire surface area. Note that you only need one LoadSSRAligner even if you're chaining several EncodeSSRQuery nodes (for multiple subjects) - just split the SSR_ALIGNER wire to all of them. The node is also cheap: the aligner is ~25MB and gets shuttled between VRAM and system memory as needed.

Installing

ComfyUI Manager: search "SSR Encoder", install, restart. Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/logtd/ComfyUI-SSREncoder

The pack ships no requirements.txt - it runs on stock ComfyUI. The model is the actual requirement:

mkdir -p ComfyUI/models/ssr
# download ssr_aligner.safetensors (~25MB) from
# https://huggingface.co/logtd/ssr_encoder/tree/main into that folder

Common issues

The one failure mode beginners actually hit: the checkpoint dropdown is empty. That means the file isn't in ComfyUI/models/ssr - double-check the folder, since models/checkpoints is the usual wrong guess, and the folder only gets auto-created the first time the pack's nodes load. A shape error when you run EncodeSSRQuery usually means the file you picked isn't the aligner (yes, ssr_attentions.safetensors also lives in that folder - different file, different job, it goes to the other loader). And one ground rule worth repeating: the aligner is hard-coded for SD 1.5's CLIP text encoder and a ViT-L/14 vision encoder, so this pack simply doesn't do SDXL or Flux. If you're on SD 1.5 and the file's in place, the loader just works - which is more than you can say for most custom nodes.