Qinglong Score

Qinglong Score is inspired by the original imscore project.

Qinglong Score is a contract-first PyTorch interface for image reward and aesthetic scorers. load_scorer() returns the typed public Scorer interface; it accepts image tensors, distinguishes exact autograd from an explicitly declared surrogate, and returns exactly one score per sample.

All six 0.1.0 scorers have real-checkpoint Windows and Linux evidence, including applicable legacy and Transformers endpoint gates. HPSv3 additionally has explicit FlashAttention 2 and SDPA score, batch-isolation, and input-gradient evidence on both platforms. Version 0.2.0 added CycleReward, HPSv3++, and three UniPercept views. HPSv3++ and the UniPercept views are now stable Registry entries; HPSv3++ retains its official surrogate-gradient classification and UniPercept remains evaluation-only. Version 0.2.2 adds metadata-only checkpoint discovery and a non-default HPSv3++ ConvRot8 row that follows its maintainer-owned repository while recording the exact commit used by each load.

Install

Package installation, clean import, and the offline contract are tested on Python 3.10 through 3.13 on both Linux and Windows. Real-checkpoint Windows GPU qualification remains Python 3.11 only, as does the supported Windows FlashAttention wheel.

From PyPI:

python -m pip install qinglong-score

From a checkout:

python -m pip install .

There are no model or experimental runtime extras. HPSv2 uses a finite private model and tokenizer runtime rather than an installed OpenCLIP distribution. Its exact ftfy==6.3.1 and regex==2026.7.19 requirements are part of the score definition. They can make an environment with incompatible dependency requirements unresolvable; use a dedicated environment rather than overriding the resolver or installing with --no-deps. The default V2.5 checkpoint downloads its independently pinned SigLIP backbone and predictor head on first load.

Quick Start

import torch

from qinglong_score import get_scorer_spec, load_scorer

spec = get_scorer_spec("aesthetic_predictor_v2_5")
assert spec.gradient_kind == "exact"

scorer = load_scorer(
    "aesthetic_predictor_v2_5",
    device="cuda",
    dtype=torch.float16,
    gradient_requirement="exact",
)
print(scorer.checkpoint_identity)

images = torch.rand(
    2,
    3,
    768,
    512,
    device=scorer.device,
    dtype=scorer.input_dtype,
    requires_grad=True,
)
scores = scorer.score(images)
assert scores.shape == (2,)
scores.mean().backward()
assert images.grad is not None

gradient_requirement rejects an unsuitable registered gradient kind before device probing or checkpoint download. scorer.checkpoint_identity records the exact remote checkpoint row, or the path and format of an explicitly supplied local checkpoint, so experiment logs can distinguish numerically different weights.

The public image contract is strict: [B, 3, H, W] with positive dimensions, floating point, finite, within 1e-6 of [0, 1], on scorer.device, and exactly scorer.input_dtype; the output is exactly [B]. Model-specific shape limits are documented by the owning Adapter rather than imposed on unrelated scorers. The boundary tolerance only avoids rejecting floating-point roundoff. Qinglong Score does not silently clamp, cast, rescale, or move input, including tolerated boundary values. Loaded scorers reject post-load transforms that would change or copy their parameters, plus .train() and .requires_grad_(True); call load_scorer() again for a different runtime configuration. A true device/dtype no-op remains valid, so a scorer loaded on the final device can safely live inside a parent module later moved to that same configuration.

Discovery

from qinglong_score import get_scorer_spec, list_scorers

print(list_scorers())
print(get_scorer_spec("aesthetic_predictor_v2_5"))

Checkpoint rows are discoverable without loading an Adapter, probing a device, initializing CUDA, or accessing the network:

from qinglong_score import list_checkpoints, load_scorer

for checkpoint in list_checkpoints("hpsv3_plus_plus"):
    print(checkpoint.identifier, checkpoint.is_default, checkpoint.tracks_updates)

scorer = load_scorer(
    "hpsv3_plus_plus",
    checkpoint="bdsqlsz/HPSV3-PlusPLus-INT8-ConvRot",
    device="cuda",
)
print(scorer.checkpoint_identity)

list_checkpoints() returns the frozen Registry source rows. Most rows are pinned with tracks_updates=False. The HPSv3++ INT8 row is the sole tracking row: it has tracks_updates=True, follows repository reference main, and is non-default. Loading it resolves main once and records that concrete commit in scorer.checkpoint_identity. The lossless BF16 row remains the default.

The registry is closed for each release; public ScorerSpec and checkpoint metadata do not expose factories, and unavailable models do not receive stubs that only raise at runtime.

0.2.2 Checkpoint Discovery

Version 0.2.2 publishes list_checkpoints() and admits the explicitly selected bdsqlsz/HPSV3-PlusPLus-INT8-ConvRot checkpoint. The admitted bundle quantizes 252 language-backbone Linear modules and passed its predeclared full HPDv3++ gate at resolved commit e9210d19b2dc2337b866297394eae9d8c6bc04a1. Its initial 10,185-pair result had 0.9998725 image-score Pearson correlation, 0.9997557 margin correlation, 99.4207% ranking agreement, and a -0.0491 percentage-point preference accuracy change relative to BF16.

Because the row intentionally follows main, a future repository update can change numerical results without a Qinglong Score release. Every load still binds one resolved commit, and the runtime validates the closed file structure; numerical quality of later heads is the repository owner's publication policy. See the 0.2.2 release notes and admission evidence.

0.2.1 Runtime Cleanup

Version 0.2.1 removes the external OpenCLIP and Timm runtime distributions. HPSv2 now owns its fixed ViT-H/14 graph, tokenizer, and verified BPE asset; UniPercept uses a separately attributed private DropPath subset. The four approved stability changes are guarded against the frozen v0.2.0 Registry metadata, so checkpoints, dtypes, gradient kinds, and backend preferences cannot move with the status change. The promotion decision retains unexecuted platform and backend checks as accepted limitations rather than reporting them as passing evidence. The HPSv2 migration passed bit-exact CPU comparison and the official/legacy CUDA gates on Windows and Linux; see the 0.2.1 release notes, runtime evidence, and stability promotion record.

0.2.0 Release

CycleReward is the admitted second-batch family: Combo is the default, I2T and T2I are explicit checkpoint rows, and all three passed pinned official-reference, batch, exact-gradient, Windows, and Linux gates. Version 0.2.0 also adds exact checkpoint identity, gradient-kind preflight, the public convrot8 format family, an offline audited HPSv3++ pickle-to-safetensors converter, and the thin hpsv3_plus_plus runtime backed by the published four-shard BF16 checkpoint. It also registers unipercept_iaa, unipercept_iqa, and unipercept_ista against pinned checkpoint artifacts. Those scorers share the official 101-token score definition but load independent model instances and explicitly declare gradient_kind="none".

SpectraReward remains absent from the Registry: it produced connected gradients on FA2 and SDPA but no common epsilon passed the frozen exact directional gate. HPSv3++ loaded and backpropagated on FA2, but its official capability encoder detaches an image-dependent branch, so the registered scorer declares gradient_kind="surrogate" rather than "exact". The pinned UniPercept artifacts passed identity, tokenizer, architecture, Tensor-preprocessing, and Windows runtime/isolation checks. Current stable classifications and their accepted limitations are recorded without manufacturing additional gates. Failed candidates still receive no placeholder factories.

See the public contract, the V2.5 model evidence, AestheticSigLIP evidence, PickScore evidence, HPSv2 evidence, ImageReward evidence, CycleReward evidence, SpectraReward exclusion evidence, UniPercept evidence, HPSv3++ runtime evidence, HPSv3 evidence, and the migration guide. Cross-platform test and clean distribution evidence is recorded in the release matrix. The frozen 0.1.0 criteria remain mapped in their evidence index, and the 25 0.2.0 criteria are mapped in the 0.2.0 evidence index. The eight 0.2.2 criteria are mapped in the 0.2.2 evidence index. The complete approved expansion design is recorded in the 0.2.0 design specification. See the 0.2.2 release notes for checkpoint discovery and the admitted tracking row, the 0.2.1 release notes for runtime cleanup and stability changes, and the 0.2.0 release notes for the earlier compatibility and candidate decisions. Maintainers should follow the release process for the tag-to-PyPI Trusted Publishing path.

Quality Benchmarks

The committed HPSv3++ BF16-versus-ConvRot8 evaluations cover 10,185 official preference pairs. The current 252-module published row and the historical 368-module experiment have separate results, alongside the component-ablation study, in the quality benchmark results. Runtime smoke checks and platform qualification are deliberately kept out of that report.

License

Qinglong Score is licensed under AGPL-3.0-only. Vendored and derived upstream components retain their own notices in THIRD_PARTY_NOTICES.md.

Citations

aesthetic_predictor_v2_5 uses the SigLIP backbone paper:

@misc{zhai2023sigmoidlosslanguageimage,
  title = {Sigmoid Loss for Language Image Pre-Training},
  author = {Xiaohua Zhai and Basil Mustafa and Alexander Kolesnikov and Lucas Beyer},
  year = {2023},
  eprint = {2303.15343},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2303.15343}
}

aesthetic_siglip uses the SigLIP 2 paper:

@misc{tschannen2025siglip2multilingualvisionlanguage,
  title = {SigLIP 2: Multilingual Vision-Language Encoders with Improved Semantic Understanding, Localization, and Dense Features},
  author = {Michael Tschannen and Alexey Gritsenko and Xiao Wang and Muhammad Ferjad Naeem and Ibrahim Alabdulmohsin and Nikhil Parthasarathy and Talfan Evans and Lucas Beyer and Ye Xia and Basil Mustafa and Olivier H{\'e}naff and Jeremiah Harmsen and Andreas Steiner and Xiaohua Zhai},
  year = {2025},
  eprint = {2502.14786},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2502.14786}
}

cycle_reward uses the CycleReward paper:

@misc{bahng2025cycleconsistencyrewardlearning,
  title = {Cycle Consistency as Reward: Learning Image-Text Alignment without Human Preferences},
  author = {Hyojin Bahng and Caroline Chan and Fredo Durand and Phillip Isola},
  year = {2025},
  eprint = {2506.02095},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2506.02095}
}

pickscore uses the Pick-a-Pic paper:

@misc{kirstain2023pickapicopendatasetuser,
  title = {Pick-a-Pic: An Open Dataset of User Preferences for Text-to-Image Generation},
  author = {Yuval Kirstain and Adam Polyak and Uriel Singer and Shahbuland Matiana and Joe Penna and Omer Levy},
  year = {2023},
  eprint = {2305.01569},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2305.01569}
}

hpsv2 uses the HPSv2 paper:

@misc{wu2023humanpreferencescorev2,
  title = {Human Preference Score v2: A Solid Benchmark for Evaluating Human Preferences of Text-to-Image Synthesis},
  author = {Xiaoshi Wu and Yiming Hao and Keqiang Sun and Yixiong Chen and Feng Zhu and Rui Zhao and Hongsheng Li},
  year = {2023},
  eprint = {2306.09341},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2306.09341}
}

image_reward uses the ImageReward paper:

@misc{xu2023imagerewardlearningevaluatinghuman,
  title = {ImageReward: Learning and Evaluating Human Preferences for Text-to-Image Generation},
  author = {Jiazheng Xu and Xiao Liu and Yuchen Wu and Yuxuan Tong and Qinkai Li and Ming Ding and Jie Tang and Yuxiao Dong},
  year = {2023},
  eprint = {2304.05977},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2304.05977}
}

hpsv3 uses the HPSv3 paper:

@misc{ma2025hpsv3widespectrumhumanpreference,
  title = {HPSv3: Towards Wide-Spectrum Human Preference Score},
  author = {Yuhang Ma and Yunhao Shui and Xiaoshi Wu and Keqiang Sun and Hongsheng Li},
  year = {2025},
  eprint = {2508.03789},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2508.03789}
}

hpsv3_plus_plus uses the HPSv3++ paper:

@misc{liu2026hpsv3scalingrewardmodels,
  title = {HPSv3++: Scaling Reward Models Across the Full Spectrum of Diffusion Model Capabilities},
  author = {Yijun Liu and Jie Huang and Zeyue Xue and Yuming Li and Ruizhe He and Haoran Li and Shijia Ge and Siming Fu},
  year = {2026},
  eprint = {2606.14657},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2606.14657}
}

unipercept_iaa, unipercept_iqa, and unipercept_ista share the UniPercept paper:

@misc{cao2025uniperceptunifiedperceptuallevelimage,
  title = {UniPercept: Towards Unified Perceptual-Level Image Understanding across Aesthetics, Quality, Structure, and Texture},
  author = {Shuo Cao and Jiayang Li and Xiaohui Li and Yuandong Pu and Kaiwen Zhu and Yuanting Gao and Siqi Luo and Yi Xin and Qi Qin and Yu Zhou and Xiangyu Chen and Wenlong Zhang and Bin Fu and Yu Qiao and Yihao Liu},
  year = {2025},
  eprint = {2512.21675},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2512.21675}
}