MR-IQA-2

Qualitative comparison before and after masked-credit training.

Quick start: one image, one GPU

Download only the small runnable code bundle from this model repository, create the two pinned inference environments, and provide one input image:

python -m pip install 'huggingface-hub==0.34.4'
huggingface-cli download RobinY99/MR-IQA-2 \
  --include 'code/**' \
  --local-dir mr-iqa-2-hf
cd mr-iqa-2-hf/code
bash scripts/setup_envs.sh --profile inference
python examples/quick_start.py /absolute/path/to/input.jpg

The Actor first writes evidence, solution, and rating; after that process exits and releases GPU memory, the Editor uses the generated solution on the same GPU. The frozen E5 Judge then scores the input and edited images as J0 and J1 and reports J1-J0. No HTTP service is started. Outputs are written to outputs/quick_start/, including assessment.json, edited.png, evaluation.json, and result.json. The runnable file is available directly at code/examples/quick_start.py, with its small dependency set under code/.

One-command environments

The model repository bundle can configure inference or the isolated CPU test environment:

bash code/scripts/setup_envs.sh --profile inference
bash code/scripts/setup_envs.sh --profile test

Full training and the complete contract test suite live in the GitHub source repository. On Linux with CUDA 13.0, clone it and provide the validated FlashAttention wheel to create training and test environments together:

git clone https://github.com/RobinY99/MR-IQA-2.git
cd MR-IQA-2
FLASH_ATTN_WHEEL=/absolute/path/to/validated_flash_attn.whl \
  bash scripts/setup_envs.sh --profile all

This installs the pinned software and creates .env when needed. Model/data paths and the machine-specific wheel still need to be supplied locally; the setup command does not provision GPUs or datasets.

PLCC/SRCC performance

Actor-only rating performance on the six generalization datasets is shown below. Each entry is PLCC / SRCC; Average is the unweighted macro mean of the six dataset-level coefficients.

Model	KonIQ-10K	SPAQ	LIVE-W	AGIQA-3K	KADID-10K	CSIQ	Average
MR-IQA	0.949 / 0.931	0.892 / 0.897	0.899 / 0.883	0.804 / 0.732	0.672 / 0.683	0.767 / 0.732	0.831 / 0.810
MR-IQA-2	0.937 / 0.917	0.900 / 0.899	0.893 / 0.863	0.809 / 0.739	0.667 / 0.669	0.824 / 0.785	0.838 / 0.812

MR-IQA values are from the released Qwen3-VL-2B result in the MR-IQA paper. MR-IQA-2 values use the released masked-credit E5 Actor at step 1,455; exact valid-row counts and unrounded coefficients are reported in the checkpoint results.

Load Actor or Judge

from transformers import AutoModelForImageTextToText, AutoProcessor

repo_id = "RobinY99/MR-IQA-2"
role = "actor"  # or "judge"

processor = AutoProcessor.from_pretrained(
    repo_id, subfolder=role,
)
model = AutoModelForImageTextToText.from_pretrained(
    repo_id,
    subfolder=role,
    torch_dtype="auto",
    device_map="auto",
    use_safetensors=True,
)

Load Editor

from pathlib import Path

import torch
from diffusers import Flux2KleinPipeline
from huggingface_hub import snapshot_download

snapshot = Path(
    snapshot_download(
        "RobinY99/MR-IQA-2",
        allow_patterns=["editor/**"],
    )
)
editor = Flux2KleinPipeline.from_pretrained(
    snapshot / "editor",
    torch_dtype=torch.bfloat16,
    local_files_only=True,
)

The Editor mirrors black-forest-labs/FLUX.2-klein-4B.

Single-step Actor to Editor example

This is a real deterministic run of the released masked-credit E5 Actor and FLUX.2 Klein Editor. The Actor's reasoning.solution was passed to the Editor unchanged; the Judge was not used.

The Actor returned:

{
  "reasoning": {
    "evidence": "The image suffers from significant color cast and noise, particularly in the brick wall background and the red bicycle frame, which appear dull and lack vibrancy.",
    "solution": "Super-resolution to enhance fine details and textures, super-smooth super-structure for clean architecture, super-smooth sky for clear background, super-smooth road for clear pavement, super-smooth bicycle for clean vehicle, super-smooth wall for clean brickwork, super-smooth ground for clear pavement, and super-smooth wheels for clear tires."
  },
  "rating": 4.3
}

The complete raw completion, generation settings, Editor request, and runtime provenance are recorded in examples/actor_editor/sample_0001.json. The runnable code is examples/actor_to_editor.py.

Training and evaluation code is available at RobinY99/MR-IQA-2.