flux-restoration

zhangjinyang/flux-restoration

flux-restoration is a machine learning model from zhangjinyang. Use it for the machine learning task on the model card, and read the license before you ship it in a product.

Inference-only release package for a unified blind and reference-based face restoration adapter built on FLUX.2-klein-base-4B.

Downloads · 30 days

Access

Public

Updated Apr 5, 2026

Repo size

198 MB

Likes

Public

Hugging Face

Repo makeup

Click a slice to open those files.

.png134 MB · 67%

At a glance

Access: Public
Created: Apr 5, 2026
Updated: Apr 5, 2026
SHA: 1e1c5537

Model card

From the Hugging Face model README

flux-restoration

Inference-only release package for a unified blind and reference-based face restoration adapter built on FLUX.2-klein-base-4B.

Visual Results

Selected qualitative results from the bundled examples are shown below.

Each row shows the degraded input together with blind, single-reference, and multi-reference restoration results.

<table> <thead> <tr> <th>Identity</th> <th>Degraded</th> <th>Blind</th> <th>Ref-Single</th> <th>Ref-Multi</th> </tr> </thead> <tbody> <tr> <td><code>alyssa_chia/005</code></td> <td><img src="examples/lq/alyssa_chia/5.png" width="160"></td> <td><img src="examples/outputs/blind/alyssa_chia/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/alyssa_chia/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/alyssa_chia/005/pred.png" width="160"></td> </tr> <tr> <td><code>bill_gates/003</code></td> <td><img src="examples/lq/bill_gates/3.png" width="160"></td> <td><img src="examples/outputs/blind/bill_gates/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/bill_gates/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/bill_gates/003/pred.png" width="160"></td> </tr> <tr> <td><code>chen_baoguo/004</code></td> <td><img src="examples/lq/chen_baoguo/4.png" width="160"></td> <td><img src="examples/outputs/blind/chen_baoguo/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/chen_baoguo/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/chen_baoguo/004/pred.png" width="160"></td> </tr> <tr> <td><code>donald_trump/003</code></td> <td><img src="examples/lq/donald_trump/3.png" width="160"></td> <td><img src="examples/outputs/blind/donald_trump/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/donald_trump/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/donald_trump/003/pred.png" width="160"></td> </tr> <tr> <td><code>donald_trump/005</code></td> <td><img src="examples/lq/donald_trump/5.png" width="160"></td> <td><img src="examples/outputs/blind/donald_trump/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/donald_trump/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/donald_trump/005/pred.png" width="160"></td> </tr> <tr> <td><code>eddie_peng/001</code></td> <td><img src="examples/lq/eddie_peng/1.png" width="160"></td> <td><img src="examples/outputs/blind/eddie_peng/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/eddie_peng/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/eddie_peng/001/pred.png" width="160"></td> </tr> <tr> <td><code>elon_musk/001</code></td> <td><img src="examples/lq/elon_musk/1.png" width="160"></td> <td><img src="examples/outputs/blind/elon_musk/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/elon_musk/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/elon_musk/001/pred.png" width="160"></td> </tr> <tr> <td><code>gao_yuanyuan/005</code></td> <td><img src="examples/lq/gao_yuanyuan/5.png" width="160"></td> <td><img src="examples/outputs/blind/gao_yuanyuan/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/gao_yuanyuan/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/gao_yuanyuan/005/pred.png" width="160"></td> </tr> <tr> <td><code>jensen_huang/004</code></td> <td><img src="examples/lq/jensen_huang/4.png" width="160"></td> <td><img src="examples/outputs/blind/jensen_huang/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/jensen_huang/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/jensen_huang/004/pred.png" width="160"></td> </tr> <tr> <td><code>lei_jun/005</code></td> <td><img src="examples/lq/lei_jun/5.png" width="160"></td> <td><img src="examples/outputs/blind/lei_jun/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/lei_jun/005/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/lei_jun/005/pred.png" width="160"></td> </tr> <tr> <td><code>leslie_cheung/003</code></td> <td><img src="examples/lq/leslie_cheung/3.png" width="160"></td> <td><img src="examples/outputs/blind/leslie_cheung/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/leslie_cheung/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/leslie_cheung/003/pred.png" width="160"></td> </tr> <tr> <td><code>leslie_cheung/001</code></td> <td><img src="examples/lq/leslie_cheung/1.png" width="160"></td> <td><img src="examples/outputs/blind/leslie_cheung/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/leslie_cheung/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/leslie_cheung/001/pred.png" width="160"></td> </tr> <tr> <td><code>liu_yifei/001</code></td> <td><img src="examples/lq/liu_yifei/1.png" width="160"></td> <td><img src="examples/outputs/blind/liu_yifei/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/liu_yifei/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/liu_yifei/001/pred.png" width="160"></td> </tr> <tr> <td><code>liu_yifei/003</code></td> <td><img src="examples/lq/liu_yifei/3.png" width="160"></td> <td><img src="examples/outputs/blind/liu_yifei/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/liu_yifei/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/liu_yifei/003/pred.png" width="160"></td> </tr> <tr> <td><code>sam_altman/001</code></td> <td><img src="examples/lq/sam_altman/1.png" width="160"></td> <td><img src="examples/outputs/blind/sam_altman/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/sam_altman/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/sam_altman/001/pred.png" width="160"></td> </tr> <tr> <td><code>sam_altman/002</code></td> <td><img src="examples/lq/sam_altman/2.png" width="160"></td> <td><img src="examples/outputs/blind/sam_altman/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/sam_altman/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/sam_altman/002/pred.png" width="160"></td> </tr> <tr> <td><code>sam_altman/003</code></td> <td><img src="examples/lq/sam_altman/3.png" width="160"></td> <td><img src="examples/outputs/blind/sam_altman/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/sam_altman/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/sam_altman/003/pred.png" width="160"></td> </tr> <tr> <td><code>sam_altman/004</code></td> <td><img src="examples/lq/sam_altman/4.png" width="160"></td> <td><img src="examples/outputs/blind/sam_altman/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/sam_altman/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/sam_altman/004/pred.png" width="160"></td> </tr> <tr> <td><code>satya_nadella/002</code></td> <td><img src="examples/lq/satya_nadella/2.png" width="160"></td> <td><img src="examples/outputs/blind/satya_nadella/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/satya_nadella/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/satya_nadella/002/pred.png" width="160"></td> </tr> <tr> <td><code>sundar_pichai/003</code></td> <td><img src="examples/lq/sundar_pichai/3.png" width="160"></td> <td><img src="examples/outputs/blind/sundar_pichai/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/sundar_pichai/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/sundar_pichai/003/pred.png" width="160"></td> </tr> <tr> <td><code>tim_cook/002</code></td> <td><img src="examples/lq/tim_cook/2.png" width="160"></td> <td><img src="examples/outputs/blind/tim_cook/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/tim_cook/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/tim_cook/002/pred.png" width="160"></td> </tr> <tr> <td><code>tony_leung_chiu_wai/002</code></td> <td><img src="examples/lq/tony_leung_chiu_wai/2.png" width="160"></td> <td><img src="examples/outputs/blind/tony_leung_chiu_wai/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/tony_leung_chiu_wai/002/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/tony_leung_chiu_wai/002/pred.png" width="160"></td> </tr> <tr> <td><code>zhang_ziyi/004</code></td> <td><img src="examples/lq/zhang_ziyi/4.png" width="160"></td> <td><img src="examples/outputs/blind/zhang_ziyi/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/zhang_ziyi/004/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/zhang_ziyi/004/pred.png" width="160"></td> </tr> <tr> <td><code>zhao_hongfei/001</code></td> <td><img src="examples/lq/zhao_hongfei/1.png" width="160"></td> <td><img src="examples/outputs/blind/zhao_hongfei/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/zhao_hongfei/001/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/zhao_hongfei/001/pred.png" width="160"></td> </tr> <tr> <td><code>zhao_hongfei/003</code></td> <td><img src="examples/lq/zhao_hongfei/3.png" width="160"></td> <td><img src="examples/outputs/blind/zhao_hongfei/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_single/zhao_hongfei/003/pred.png" width="160"></td> <td><img src="examples/outputs/ref_multi/zhao_hongfei/003/pred.png" width="160"></td> </tr> </tbody> </table>

Model

Base model: black-forest-labs/FLUX.2-klein-base-4B
Hugging Face: https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B
Default LoRA checkpoint inside this release package:

pretrained_models/lora_weights.safetensors

The LoRA path is relative. Do not hardcode an absolute path in code.

Download the FLUX.2-klein-base-4B snapshot and pass its directory via --model_dir, for example:

--model_dir /path/to/FLUX.2-klein-base-4B

The directory should contain:

flux-2-klein-base-4b.safetensors
vae/
text_encoder/
tokenizer/

Install

cd release/flux-restoration
pip install -r requirements.txt

Recommended runtime:

Python 3.9+
PyTorch 2.1+

Inference

scripts/infer.py

It supports two usage patterns:

Direct single-image inference
Batch inference from a manifest JSON

Modes:

blind
ref-single
ref-multi

Direct Single-Image Inference

Blind

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --mode blind \
  --degraded_image examples/lq/bill_gates/1.png \
  --output_dir outputs/demo

Single Reference

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --mode ref-single \
  --degraded_image examples/lq/elon_musk/3.png \
  --reference_image examples/hq/elon_musk/1.png \
  --output_dir outputs/demo

Multiple References

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --mode ref-multi \
  --degraded_image examples/lq/zhang_ziyi/3.png \
  --reference_image examples/hq/zhang_ziyi/1.png \
  --reference_image examples/hq/zhang_ziyi/2.png \
  --reference_image examples/hq/zhang_ziyi/4.png \
  --output_dir outputs/demo

Notes:

blind ignores any reference input.
ref-single uses the first provided --reference_image.
ref-multi uses up to --max_reference_images references. Default is 3.

Batch Inference From JSON

Three manifests are bundled under:

examples/manifests/
  blind.json
  ref_single.json
  ref_multi.json

Batch Blind

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --manifest_json examples/manifests/blind.json

Batch Single-Reference

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --manifest_json examples/manifests/ref_single.json

Batch Multi-Reference

CUDA_VISIBLE_DEVICES=0 python scripts/infer.py \
  --model_dir /path/to/FLUX.2-klein-base-4B \
  --manifest_json examples/manifests/ref_multi.json

Each manifest item contains:

degraded_image
target_image
reference_images
output_path
mode
sample metadata such as identity and index

Bundled Examples

Bundled example assets are organized as:

examples/
  lq/
    <identity>/
      1.png
      2.png
      ...
  hq/
    <identity>/
      1.png
      2.png
      ...
  manifests/
    blind.json
    ref_single.json
    ref_multi.json
    summary.json
  outputs/
    blind/
    ref_single/
    ref_multi/

Path convention:

degraded input comes from examples/lq/<identity>/<index>.png
references come from examples/hq/<identity>/<other_index>.png

The bundled manifests in examples/manifests/ point to these files and to the corresponding output locations under examples/outputs/.

Outputs

For manifest runs, predictions are written to the paths stored in the JSON files, for example:

examples/outputs/blind/bill_gates/001/pred.png
examples/outputs/ref_single/elon_musk/003/pred.png
examples/outputs/ref_multi/zhang_ziyi/003/pred.png

For direct single-image inference, outputs default to:

outputs/release_lora_ref/

Created: Apr 5, 2026
Updated: Apr 5, 2026