HPSv3 Score

You generated forty images while you were making coffee. Maybe seven are keepers. HPSv3 Score is the node that tells you which seven, in one pass, without opening a single file - and, unlike the "AI image rating" sites Google will offer you, it runs on your own card. No account, no upload, no key.

What it is, and why you'd bother

HPSv3 is a human-preference reward model. You hand it an image and the prompt that was supposed to produce it, and it returns a number representing how much a human would probably prefer that image for that prompt. The uses are concrete:

• Dataset curation. This isn't hypothetical - the Qwen finetune Rebalance shipped with an hpsv3_score field baked into its training metadata JSON, i.e. the author scored his own training images with this thing before he curated them. If you're building a LoRA set and want to drop the blurry, mushy, badly-composed tail without eyeballing 2,000 files, this is exactly the tool.
• Comparing checkpoints or LoRA weights at a fixed seed. Same prompt, same seed, two models, two numbers. Weak evidence on its own, but it beats vibes when you're five variants deep and your eyes have gone.

How it works

The node pulls the NF4 reward model in through the model input (that's the HPSV3_MODEL handle from HPSv3 Model Loader - nothing else produces that type), feeds it each incoming image together with your prompt text, and reads back a scalar per image.

The important mental model: this is a learned preference, not a measurement. It has taste, and its taste is whatever was in its training data. A reward model is a proxy for human judgement, and a proxy can be gamed - tune your prompts against the score alone and you'll converge on whatever the scorer likes, which is not the same as what looks good. Treat the number as a relative signal inside one model family, not as an absolute truth about image quality.

There's precedent for the caution: people testing the earlier generation of scorers (HPSv2, ImageReward) kept finding that all of them, on average, rated SDXL output above Flux output - which nobody looking at the images believed. Score your own variants; don't crown a model with it.

Inputs and outputs that matter

• model - from the HPSv3 loader. Wrong series (an HPSv3++ model) and the graph won't validate.
• images - anything IMAGE-shaped, including a whole batch straight off a VAE Decode.
• prompt - multiline text. Same prompt is applied to every image in the batch; if you feed a list of prompts, you need exactly as many as you have images. Score an image against the wrong prompt and you get a confident, meaningless number.
• score_mode - three settings, and you'll want a different one depending on the job:
  • banner - adds white space above the image and prints the score there. Useful, and it never covers your pixels.
  • metadata - leaves the image alone and writes the model name, score and evaluation prompt into the PNG's hpsv3 text chunk as JSON.
  • both - does the two above to the same file.
• filename_prefix - defaults to Hpsv3. It takes the usual ComfyUI substitutions, so %date:yyyy%/%date:MM%/%date:dd%/HPSv3 gives you dated folders for free.

Outputs are images (the stamped PNGs, per-image, in input order) and scores (a FLOAT per image, same order). Wire scores into anything that takes a float - a display/log node while you're calibrating, or a switch if you're building an auto-filter. Wire images into your upscaler, or nothing at all.

Two gotchas worth knowing before you build around it. First, this node is an output node: it always executes and it always saves a PNG into output/, the same way Save Image does - so a workflow you run 50 times leaves 50 files. Second, the score metadata belongs to this node's file. Pass images to a plain Save Image downstream and the hpsv3 chunk does not come with it.

Install

Manager: search ComfyUI-HPSv3 (Node Pack search type), confirm Stella2211/ComfyUI-HPSv3, install, restart. By hand:

cd ComfyUI/custom_nodes
git clone https://github.com/Stella2211/ComfyUI-HPSv3.git
cd ComfyUI-HPSv3
uv pip install --python <ComfyUI Python> -r requirements.txt
uv run --no-project --python <ComfyUI Python> python install.py

Needs an NVIDIA CUDA card with BF16, 12 GB VRAM as the guideline (8 GB untested), Python 3.12+. CPU, AMD and Apple are not supported. The 5.9 GB model downloads itself on first run into ComfyUI/models/hpsv3/HPSv3-bnb-NF4/.

Common issues

It runs forever the first time. That's the download plus the model load. Watch the ComfyUI terminal; progress prints there, not in the browser.

Type error on the model socket. You've connected a loader from the other series. HPSv3 and HPSv3++ models are mutually incompatible - match the loader to the scoring node.

Prompt count mismatch. A list of prompts has to match the image count exactly.

Missing transformers or bitsandbytes. Repair the extension's dependencies in Manager and restart; never let it replace PyTorch or torchvision.

CUDA out of memory. The reward model is resident while it works. If your generation graph is already near the ceiling, score outputs in a separate, lighter workflow.