README.md

---
license: apache-2.0
language:
  - en
tags:
  - image-quality-assessment
  - vision-language
  - reinforcement-learning
  - image-editing
---

<h1><img src="https://raw.githubusercontent.com/RobinY99/MR-IQA-2/main/assets/logo.png" alt="MR-IQA-2 logo" width="36" style="display:inline-block; margin:0 8px 0 0; vertical-align:middle;">MR-IQA-2</h1>

MR-IQA-2 couples a multimodal Actor, a frozen FLUX.2-klein-4B Editor, and a
frozen E5 Judge. Masked credit assigns reasoning and rating rewards only to
their eligible completion tokens.

![MR-IQA-2 masked-credit training overview](assets/figures/masked_credit_assignment.png)

## Quick start: one image, one GPU

Download the runnable code bundle, create the two pinned inference
environments, and provide one image:

```bash
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 --gpu 0
```

Actor, Editor, and Judge run sequentially in separate processes on the selected
GPU. The Actor solution is forwarded verbatim to the Editor; the Judge reports
`J0`, `J1`, and `J1-J0`. No HTTP service is started.

On hosts with multiple CUDA toolkits, select the toolkit used for runtime
extension compilation:

```bash
python examples/quick_start.py /absolute/path/to/input.jpg \
  --gpu 0 \
  --cuda-home /usr/local/cuda
```

Outputs are written to `outputs/quick_start/`: `actor_raw.txt`,
`assessment.json`, `edited.png`, `evaluation.json`, and `result.json`.
The release path was smoke-tested end to end on one NVIDIA A6000 (48 GB), with
`J0=3.42`, `J1=4.12`, and `J1-J0=+0.70`.

## PLCC/SRCC performance

Actor-only rating performance on six generalization datasets. Each entry is
`PLCC / SRCC`; Average is the unweighted macro mean.

| Model | KonIQ-10K | SPAQ | LIVE-W | AGIQA-3K | KADID-10K | CSIQ | Average |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| [MR-IQA](https://github.com/RobinY99/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](https://arxiv.org/pdf/2606.29760). MR-IQA-2 uses the released
masked-credit E5 Actor at step 1,455. Exact coefficients and valid-row counts
are in the
[checkpoint results](https://github.com/RobinY99/MR-IQA-2/blob/main/docs/checkpoints.md#field-e5-recommended).

## Released folders

- `actor/`: masked-credit E5 Actor, step 1,455;
- `judge/`: frozen E5 Judge, step 725;
- `editor/`: FLUX.2-klein-4B;
- `code/`: runnable single-image inference bundle.

Actor and Judge load with `AutoModelForImageTextToText.from_pretrained` using
`subfolder="actor"` or `subfolder="judge"`. The Editor loads from
`editor/` with `Flux2KleinPipeline.from_pretrained`.

A real Actor → Editor sample, including the exact completion and provenance,
is available in
[`examples/actor_editor/sample_0001.json`](examples/actor_editor/sample_0001.json).
Training, evaluation, and deployment code is available on
[`RobinY99/MR-IQA-2`](https://github.com/RobinY99/MR-IQA-2).