Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,179 @@
+---
+language:
+  - en
+library_name: pytorch
+tags:
+  - image-classification
+  - ai-generated-image-detection
+  - deepfake-detection
+  - universal-detector
+  - robustness-asymmetry
+  - dinov3
+  - diffusion-generated-image-detection
+license: other
+pipeline_tag: image-classification
+metrics:
+  - accuracy
+---
+
+# RA-Det: Robustness Asymmetry Detection for AI-Generated Images
+
+Official pretrained checkpoint for **RA-Det** _(ICML 2026)_ — a behavior-driven detector that decides whether an image is real or AI-generated by examining how it **behaves** under controlled perturbations, rather than how it **looks**.
+
+> 📄 **Paper:** _RA-Det: Towards Universal Detection of AI-Generated Images via Robustness Asymmetry_ ([arXiv:2603.01544](https://arxiv.org/abs/2603.01544))
+> 💻 **Code:** [github.com/dongdongunique/RA-Det](https://github.com/dongdongunique/RA-Det)
+> 🏛️ **Venue:** ICML 2026
+
+---
+
+## TL;DR
+
+Most detectors hunt for visual artifacts. Modern generators (Stable Diffusion, DALL·E, GANs) increasingly erase those artifacts, so appearance-based methods generalize poorly. RA-Det instead exploits a **robustness asymmetry**:
+
+- **Natural images** keep a stable semantic representation under small perturbations.
+- **AI-generated images** drift much more under the *same* perturbations.
+
+RA-Det learns a perturbation operator that amplifies this gap, then classifies images from the resulting behavior — making it **data-agnostic, model-agnostic, and transferable to unseen generators**.
+
+---
+
+## How it works
+
+RA-Det combines two components:
+
+1. **Differential Robustness Probing (DRP)** — a learnable U-Net that applies a *bounded* perturbation (ε = 16/255) to the input, calibrated to maximally separate real vs. generated images in embedding space.
+2. **Multi-Branch Detector** — aggregates three complementary cues:
+   - **Semantic features** — from a frozen **DINOv3 ViT-L/16** foundation model (1024-d embeddings).
+   - **Discrepancy features** — distance, similarity, and covariance statistics between the *clean* and *DRP-perturbed* embeddings (the core of the robustness-asymmetry signal).
+   - **Low-level residual features** — capture high-frequency / forensic artifacts.
+
+A **four-branch ensemble** variant adds an L²-based branch for additional robustness. This checkpoint is the recommended four-branch ensemble configuration.
+
+> ⚠️ The statistics-based discrepancy branch needs enough samples per batch for stable covariance estimation. That is why **a batch size of 256 (32 per GPU × 8 GPUs) is strongly recommended** — smaller batches noticeably degrade accuracy.
+
+---
+
+## Model details
+
+| | |
+|---|---|
+| **Configuration** | `ensemble_vitl16_raw_lpd_discrepancy` (four-branch ensemble) |
+| **Backbone** | DINOv3 ViT-L/16, frozen (1024-d embeddings) |
+| **Perturbation module** | Differential Robustness Probing (U-Net), ε = 16/255 |
+| **Detector branches** | Semantic (DINOv3) + Discrepancy + Low-level residual (+ L²) |
+| **Loss** | Discrepancy loss (margin = 1.0) + classification loss |
+| **Training data** | ProGAN (Wang2020 format), `0_real/` & `1_fake/` per category |
+| **Checkpoint file** | `checkpoint_best.pt` (PyTorch state_dict) |
+| **Framework** | PyTorch (`torchrun` distributed training/eval) |
+| **License** | See the [code repository](https://github.com/dongdongunique/RA-Det) (intended for research use) |
+
+---
+
+## Results
+
+- Evaluated against **14+ diverse generative models** (ProGAN, Stable Diffusion v1.4, DALL·E 2, and more).
+- Outperforms **10+ existing detection methods**.
+- **+7.81% average performance improvement** over prior art, with strong transfer to **unseen generators**.
+
+Per-generator accuracy tables and ablations are available in the [paper](https://arxiv.org/abs/2603.01544) and the [code repository](https://github.com/dongdongunique/RA-Det).
+
+---
+
+## How to use
+
+This is **not** a single self-contained `.safetensors` model — RA-Det's forward pass requires the DINOv3 backbone plus the DRP U-Net and multi-branch detector defined in the codebase. The intended way to run it is via the official repository.
+
+### 1. Get the code and weights
+
+```bash
+git clone https://github.com/dongdongunique/RA-Det.git
+cd RA-Det
+pip install -r requirements.txt
+
+# DINOv3 backbone weights -> models/dino/dinov3_vitl16_pretrain.pth
+# DINOv3 source -> models/dinov3_repo  (see repo README)
+```
+
+### 2. Download this checkpoint
+
+```python
+from huggingface_hub import hf_hub_download
+
+ckpt_path = hf_hub_download(
+    repo_id="dongdongunique/RA-Det-Checkpoints",
+    filename="checkpoint_best.pt",
+    repo_type="model",
+)
+print(ckpt_path)
+```
+
+### 3. Configure data paths
+
+Edit `paths.py` (or set env vars) to point at your data in **Wang2020 format**:
+
+```python
+PROGAN_TRAIN_DATA_PATH = "/path/to/progan_train"   # .../airplane/{0_real,1_fake}/...
+AIGCTEST_DATA_PATH     = "/path/to/AIGCTestset/test"  # progan/, stable_diffusion_v_1_4/, DALLE2/, ...
+```
+
+### 4. Run evaluation
+
+The recommended entry point uses the same initialization as training:
+
+```bash
+bash scripts/validate.sh --gpus 8 --checkpoint /path/to/checkpoint_best.pt
+```
+
+…which expands to:
+
+```bash
+torchrun --nproc_per_node=8 train.py \
+    --config ensemble_vitl16_raw_lpd_discrepancy \
+    --eps 0.06274509803921569 \
+    --margin 1.0 \
+    --four-branch-ensemble \
+    --normalize-loss \
+    --validate-checkpoint /path/to/checkpoint_best.pt
+```
+
+### Reproduce training
+
+```bash
+# 8 GPUs, recommended batch size 256 (32/GPU), eps=16/255, margin=1.0
+bash scripts/main.sh --gpus 8 --niter 1
+```
+
+| Parameter | Default | Note |
+|---|---|---|
+| `--eps` | 16/255 (0.0627) | Perturbation budget |
+| `--margin` | 1.0 | Discrepancy-loss margin |
+| `--niter` | 1 | Training epochs |
+| `--gpus` | 8 | GPUs for `torchrun` |
+| Batch size | **256** | Required for stable discrepancy statistics |
+
+---
+
+## Intended use & limitations
+
+- **Intended for** research on AI-generated image detection, media forensics, and robustness analysis.
+- **Out of scope:** real-world deployment as the sole decision in high-stakes moderation, surveillance, or identity-related judgments. Detector scores are probabilistic and can be wrong, especially on heavily post-processed, compressed, or adversarially crafted inputs.
+- **Bias considerations:** detection performance varies across generators, image content, and demographics; treat outputs as one signal among several, never as ground truth.
+- Generalization to **future, unseen generators** is a moving target — re-evaluate on your specific data before relying on results.
+
+---
+
+## Citation
+
+If you use this checkpoint or the RA-Det method, please cite:
+
+```bibtex
+@misc{wang2026radetuniversaldetectionaigenerated,
+      title={RA-Det: Towards Universal Detection of AI-Generated Images via Robustness Asymmetry},
+      author={Xinchang Wang and Yunhao Chen and Yuechen Zhang and Congcong Bian and Zihao Guo and Xingjun Ma and Hui Li},
+      year={2026},
+      eprint={2603.01544},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2603.01544},
+}
+```