💯 Q-Align Scoring

CLIP scores have burned you before. They're useful for sorting, but "this batch scored higher" rarely means "this image actually looks better." Q-Align is the research-grade answer to that problem: a 7-billion-parameter multimodal LLM from an ICML 2024 paper (Haoning Wu et al., NTU/SJTU/SenseTime) fine-tuned to rate images the way a human reviewer would. This node is ZHO-ZHO-ZHO's unofficial ComfyUI wrapper around it, and it's about the closest you'll get to a second opinion that isn't your own eyeballs.

Feed it an image and you get two continuous scores - Image Quality Assessment (IQA, "is this technically clean?") and Image Aesthetic Assessment (IAA, "is this actually pleasing?") - plus a coarse rating string for each. Where you actually reach for it: comparing samplers or CFG values in a sweep, checking whether an upscale genuinely helped, auditing a batch of generations. Not a per-image staple; it's a slow, heavy, deliberate review step.

One honest note before you commit to it: the pack is marked WIP, and Q-Align has essentially no presence in the ComfyUI community - a search of r/comfyui and r/StableDiffusion turns up zero threads that even name it. It's a research tool wearing a node costume, not a community favorite.

How it works

The node instantiates the upstream Q-Align scorer, which loads the OneAlign checkpoint (q-future/one-align on Hugging Face) - a mPLUG-Owl2/Qwen-VL-style model on a LLaMA-2 backbone. It shows the image to the model with a prompt along the lines of "How would you rate the quality of this image?", then reads how much probability the model assigns to the five tokens excellent, good, fair, poor, bad. A weighted average of those probabilities is the score. So it's not one forward pass deciding a label - it's the model's full distribution over quality levels, collapsed into a number. The aesthetic scorer does the same thing with an aesthetics-flavored prompt. Note it loads two separate copies of the 7B model - one per scorer - which is why the author's own note says you need more than 16GB VRAM.

Inputs and outputs

One required input:

• image (IMAGE) - any ComfyUI image tensor, from Load Image or straight off a VAE Decode.

Four outputs:

• Image Quality Score (IQA) (FLOAT) - continuous quality score.
• IQA Rating (STRING) - one of bad / poor / fair / good / excellent, bucketed from the score.
• Image Aesthetics Score (IAA) (FLOAT) - continuous aesthetics score.
• IAA Rating (STRING) - same five-level label for aesthetics.

There are no knobs. No weights, no prompt editing, no scale override - you get what you get. This is a terminal node: wire the FLOATs into a Show Text or Primitive to read them, or concatenate the strings into labels if you're building a comparison grid.

Install

ComfyUI Manager (search "Q-Align") or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/ZHO-ZHO-ZHO/ComfyUI-Q-Align

Restart ComfyUI. The pack's requirements install the upstream package straight from GitHub (git+https://github.com/Q-Future/Q-Align.git@main), so pip drags in that whole repo and its dependency tree - this is not a lightweight install.

First run is the real install: the node auto-downloads q-future/one-align from Hugging Face, roughly 14GB of weights. Budget the disk space and a slow, patient first execution.

Where people get burned

• The float and the string can disagree. The current upstream scorer returns a weighted token probability that lands in 0–1, but this node's rating buckets assume a 1–5 scale (thresholds at 1.5 / 2.5 / 3.5 / 4.5). In practice that means the STRING rating can read "bad" on images that are plainly fine. Trust the raw FLOAT outputs; treat the strings as decorative until the wrapper is updated.
• The model reloads on every run. The node constructs fresh scorers each time the queue executes instead of caching them, so every run is two slow 7B model loads. Don't chain this into a live loop - run it as a one-off review.
• VRAM is genuinely a wall. Two 7B models plus whatever you generated with. On a 16GB card this can be the thing that OOMs you.
• License. OneAlign rides on LLaMA-2, and the upstream repo flags that commercial use of the checkpoints should comply with the LLaMA-2 license.

If you just want a quick quality read, a CLIP score is cheaper and good enough. Q-Align is for when you want the number to mean what a human grader would mean - and are willing to pay 14GB and a slow load for it.