# Q-ReAlign says it matches Q-Align on all seven benchmarks, and its own table shows three losses

> Q-ReAlign is a set of three lightweight vision-language judges for image quality and aesthetics scoring, packaged as qalign with 0.8B, 4B and 9B checkpoints on the Hugging Face Hub. The results summary and the results table do not agree, the averages do not reconcile with the cells, and the runtime stack is pinned to three different version numbers in three places.

**Q-Future/Q-ReAlign** — Q-Align-style framework with lightweight LMMs, including 0.8B, 4B, and 9B checkpoints, dataset builders, caching, scoring, and CLI workflows.

- Repository: https://github.com/Q-Future/Q-ReAlign
- Stars: 468 · Forks: 3
- Language: Python
- License: not declared
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/q-future-q-realign

## Three names: the repo, the package, the checkpoints

The project carries three identifiers and they are not interchangeable. The repository is Q-ReAlign, the distribution is `qalign` at version 0.1.0 with a console script of the same name wired to `qalign.cli:main`, and the weights are three Hugging Face repositories under the q-future organisation, `Q-ReAlign-Mini-0.8B`, `Q-ReAlign-Lite-4B` and `Q-ReAlign-Pro-9B`. Any of those three repository IDs can be passed as a checkpoint argument and the weights download on demand. The packaging metadata describes the package as a modernized, model-agnostic Q-Align with quality and aesthetics scoring as discrete text levels on any ms-swift vision-language model, and the repository description frames it the same way, naming the three sizes. the licence is where the naming story stops being tidy: the packaging metadata declares MIT, no licence is recorded in the repository's own metadata, and there is no licence file anywhere in the top level of the tree.

## The summary claims seven wins the table does not contain

The results prose states that all three variants match or beat the original Q-Align across KonIQ, SPAQ, KADID, AGI, LIVE, AVA and LSVQ. The table immediately under it says otherwise for the smallest model. Q-Align scores 0.942 SRCC on KonIQ against 0.935 for Mini, 0.912 on KADID against 0.903, and 0.798 on AVA against 0.797. So three of the seven benchmarks are losses for the 0.8B model, two of them by more than half a hundredth, and the sentence above the table is not describing the table below it. The pattern across the rest of the grid is coherent and worth reading as the real finding: the small model is competitive on the datasets closest to its training mix, AVA and KonIQ among them, and loses where the original had the advantage of scale, while the two larger variants take or share the lead nearly everywhere. Every model is trained on the same ONE-ALIGN mix of six public datasets, KonIQ, SPAQ, KADID, AGIQA-20K, AVA and LSVQ, combining IQA, IAA and VQA data.

## The averages were computed before the cells were rounded

A footnote admits it: the average SRCC for the 9B and 0.8B models uses reported values of 0.8956 and 0.8792, and rankings are taken on full precision before rounding. That is the honest way to do it, and it has a consequence for anyone checking the work. Averaging the seven printed SRCC cells for the 9B model gives 0.897, not the 0.896 printed in the average column, and the 0.8B row averages to 0.879 against a printed 0.879. So one row disagrees with its own cells by about a thousandth and another agrees to three decimals. The 4B row averages to 0.886 against a printed 0.889, a difference of three thousandths, which the footnote does not mention because it does not apply the full-precision rule there. The practical point is that the average column cannot be recomputed from this page, and the headline comparison of 0.896 against Q-Align's 0.869 rests on that column.

## Half the parameters cannot be checked, because Q-Align's size is never stated

The one-line pitch above the news section is that this is Q-Align-level performance with 50% fewer parameters. The table gives parameter counts for the three Q-ReAlign variants, 0.8B, 4B and 9B, and gives SRCC and PLCC for Q-Align, but nowhere on this page does Q-Align's parameter count appear. The claim is therefore not checkable from what is published here, and the direction of the arithmetic is not obvious: the largest Q-ReAlign model is 9B, so a 50% reduction against Q-Align implies a baseline of roughly 18B, while the average-column gains come mostly from the 4B and 9B variants rather than from the 0.8B one. What the page does establish is narrower and still useful. If the goal is the cheapest thing that matches the original, Mini is that model, needing under 4 GB of GPU memory and running on CPU. If the goal is the best number, Pro is, at 0.896 average SRCC.

## Five levels, five fixed weights, and a zero at the bottom

The scoring mechanism is deliberately crude, and it is the part most worth copying. The model is asked to name one of five discrete levels, and the number comes from a lookup:

```python
LEVELS, WEIGHTS = ["excellent", "good", "fair", "poor", "bad"], [1.0, 0.75, 0.5, 0.25, 0.0]
```

So the judge never emits a continuous score. It classifies, and the score is a constant. Two properties follow. The output range is bounded to [0, 1] by construction rather than by post-processing, and the worst level maps to exactly zero, which means a genuinely bad image and a refused or misparsed judgement are hard to tell apart from the score alone. The pyiqa integration reports `lower_better` as False and accepts either an image path or an RGB tensor in [0, 1], and the same metric object also exposes an `aesthetic` task alongside the default `quality` scoring, so one checkpoint serves both the IQA and IAA halves of the training mix.

## Three transformers statements and a ms-swift patch mismatch

The runtime stack is described in three places and does not agree. The quick run comment asks for transformers 5.2.0 or newer for Qwen3.5 support, the pyiqa install line asks for `transformers>=5.2` with a note that the Qwen3.5-VL backbone needs 5.0, and the packaging metadata pins `transformers==5.3.0` in the runtime extra. The ms-swift line is a genuine conflict: the extra pins `ms-swift==4.0.2` while the container image it is built on is described as carrying ms-swift 4.0.3, and the Dockerfile explains the arrangement by saying the build deliberately avoids `pip install .[runtime]` because that would try to pull 4.0.2 and fight the base image. So the extra is a dead end inside the container and the authoritative version lives in the image tag. Two smaller gaps: the extra omits torch and flash-attn even though both are named in its own comment and in requirements.txt.

## The default base image is a US-West mirror, and the override example is Hangzhou

The container story is the most careful part of the documentation. The image is not built from a Python base at all; it inherits an official ModelScope and ms-swift image that already carries torch 2.10, ms-swift 4.0.3, transformers, deepspeed and vLLM on CUDA 12.8.1 with Python 3.11, and the repository layer adds only `qalign` plus decord for video, then runs an import check that prints the package version. The build accepts a `BASE` argument, and the default value is the us-west-1 ModelScope registry, while the documented override for a region-local pull points at the cn-hangzhou registry. That default choice matters in practice: a builder outside the United States will pull its base image across an ocean unless it passes the override. The install story follows the same logic of separating the layers.

```bash
pip install -e .
pip install -e ".[runtime]"
pip install -e ".[dev]"
```

The core install is numpy, scipy, pillow and pyyaml, and the packaging metadata states that ms-swift and torch are imported lazily inside the model, scorer and train modules so `import qalign` works on a laptop.

## Conclusion

The modelling here is unremarkable and well packaged: five discrete levels mapped to fixed weights, three sizes, a CPU path, and a two-line integration through pyiqa that avoids the training stack entirely. Two things to reconcile before trusting the numbers. The claim that all three variants match or beat Q-Align on every benchmark is not what the table shows, so read the cells rather than the sentence. And the printed averages come from full precision while the cells are rounded, which means an average cannot be recomputed from the page. For reproduction, pin the runtime deliberately: ms-swift is pinned to 4.0.2 in the extra while the verified container image carries 4.0.3, and transformers is described three different ways. And note that the packaging metadata declares MIT while no licence file exists in the tree.

## FAQ

### What is Q-ReAlign?

A set of three lightweight vision-language judges for image quality and aesthetics scoring, sized 0.8B, 4B and 9B and published as the Q-ReAlign-Mini, Q-ReAlign-Lite and Q-ReAlign-Pro checkpoints on the Hugging Face Hub. The package itself is named qalign, and all three are trained on the same ONE-ALIGN mix of six public datasets.

### How does Q-ReAlign turn a model answer into a score?

The judge names one of five levels, excellent, good, fair, poor or bad, and the numeric value comes from a fixed weight per level: 1.0, 0.75, 0.5, 0.25 and 0.0. Scores therefore land in [0, 1] by construction, and the lowest level maps to exactly zero.

### How do I use Q-ReAlign without installing the training stack?

Through IQA-PyTorch: install pyiqa and transformers 5.2 or newer, then call `pyiqa.create_metric("qrealign")`, which defaults to the 0.8B Mini model. `qrealign-lite` and `qrealign-pro` select the 4B and 9B variants, and the checkpoints download from the Hub automatically.

### Does Q-ReAlign need a GPU?

Not for the 0.8B model, which is stated to need under 4 GB of GPU memory and to be CPU-runnable. `import qalign` works without a GPU because ms-swift and torch are imported lazily, and the core install pulls only numpy, scipy, pillow and pyyaml.

## Sources

- [Issues](https://github.com/Q-Future/Q-ReAlign/issues)
- [Q-Future/Q-ReAlign on GitHub](https://github.com/Q-Future/Q-ReAlign)
- [README](https://github.com/Q-Future/Q-ReAlign/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/q-future-q-realign