(Down)load Q-ReAlign

Q-ReAlign is the "ask a language model to grade the picture" approach to image quality, and it's the heaviest thing in this pack. It's built on a Qwen3.5-VL backbone using Q-Align's recipe, comes in three sizes, and it's the one scorer here that the author says is worth the compute if you have it. This is its own loader rather than a variant on the generic one because three things about it don't fit the generic path: the size tiers, the int8 quantised builds, and a dtype choice.

Picking a size

model_name is a six-entry dropdown, int8 entries first:

• qrealign-mini-0.8B (int8_convrot) / qrealign-lite-4B (int8_convrot) / qrealign-pro-9B (int8_convrot)
• then the plain builds of the same three

Mini is the fast one. Pro is the best-correlating and the slowest. Lite is the compromise nobody writes about. Your first decision is which tier your card and your patience can afford; your second is whether to take the quantised copy.

dtype is auto (follows the checkpoint, bfloat16), or bfloat16 / float16 / float32 forced. It's ignored for the int8 entries - those weights are already int8 with bf16 compute, so there's nothing to cast.

Custom snapshot folders work too: a directory with a config.json in models/pyiqa/Q-ReAlign/ appears as an extra entry named after the folder.

What int8_convrot actually is

This part is worth understanding because it's why the numbers in the dropdown look surprising. The int8 builds use ComfyUI's native int8_tensorwise + ConvRot format - the same recipe Comfy-Org ships for its official int8_convrot text encoders. Per-channel int8 weights plus a group-256 Hadamard rotation applied to both weights and activations, so the int8 matmuls land on tensor cores without the accuracy cliff naive int8 gives you.

Critically, the rotation and the int8 matmul are handled by ComfyUI's own tensor-subclass dispatch (comfy.quant_ops + comfy_kitchen). The model's forward pass is untouched, so a quantised Q-ReAlign is the same code path as the plain one, not a fork of it. That's also why there's no extra widget: no group size, no calibration flag. Just pick the entry.

The sizes, which are the whole argument:

| Variant | bf16 | int8_convrot | |---|---|---| | Pro 9B | 17.5 GiB | 11.55 GiB | | Lite 4B | 9.7 GiB | 6.28 GiB | | Mini 0.8B | 2.1 GiB | 1.56 GiB |

And the accuracy: on eight real photos, mean absolute difference vs bf16 was 0.0008 for Pro, 0.0031 for Mini, 0.0085 for Lite, with no ranking flips on the probe set. Pro tracks bf16 almost exactly partly because its vision tower stays bf16 (hidden size 1152 isn't divisible by the 256 rotation group) - so Pro's quantisation is really only the language side. Mini and Lite quantise the vision tower too.

For most people the int8 entry is simply the right pick. You get the big model on the card you own and the score drift is well below the noise between two generations.

Outputs

model goes into QReAlign NR Score - that's the only node that takes it. model_name is the pyiqa registry name the build corresponds to (qrealign-mini, or qrealign for a custom snapshot). variant_label echoes the dropdown entry.

The transformers catch

Q-ReAlign needs transformers>=5 and the pack deliberately does not pin it in requirements.txt, because forcing that upgrade on every install would quietly break other packs. Instead the loader checks the version at load time and raises with the exact pip command:

python -m pip install -U "transformers>=5"

Run that inside ComfyUI's own venv, not your system Python. Half the "I installed it and it still says missing" threads in this hobby are someone pip-installing into the wrong interpreter.

Install and weights

cd ComfyUI/custom_nodes
git clone https://github.com/AnsteinHuynh/ComfyUI-pyiqa-toolbox
python -m pip install -r ComfyUI-pyiqa-toolbox/requirements.txt

Manager works too - search pyiqa-toolbox. Restart, then look under pyiqa/QReAlign.

Nothing is bundled and Pro is a big download. Weights are looked up in the registered pyiqa folders as Q-ReAlign-<variant>-int8-convrot/ (at the folder root or inside Q-ReAlign/), and if absent the loader pulls just that variant's files from the AnsteinHuynh/Q-ReAlign-int8-convrot HuggingFace repo via a scoped snapshot_download - roughly nine files, not the whole repo. Set PYIQA_TOOLBOX_INT8_REPO if you'd rather host your own mirror.

Common issues

Out of VRAM with Pro next to SDXL. The pack frees ComfyUI's cache before big metrics allocate, and the loader is evaluated lazily (after your image exists, not at graph setup), but 11.5 GiB is 11.5 GiB. Drop to Lite, or score in a second pass.

"It says transformers 4" on a headless server. The check runs at load time. Install into the venv that runs ComfyUI and restart the process.

Two folders, one listed twice. The loader recognises both the root and the Q-ReAlign/ layout and de-duplicates them; if you see a duplicate, you've probably got two differently-named copies.