Deploy A-EYE remote full ensemble backend

.gitattributes

@@ -1,35 +1,3 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -1,31 +1,23 @@
-# A-EYE 추론 백엔드 — 클라우드 배포용 이미지
-FROM python:3.11-slim
-
-ENV PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1 \
-    MODEL_PATH=/app/models/best.pt
-
-WORKDIR /app
-
-# grad-cam(opencv) 실행에 필요한 시스템 라이브러리
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
-    && rm -rf /var/lib/apt/lists/*
-
-# CPU 전용 torch/torchvision 을 먼저 설치해 이미지 용량을 줄입니다.
-RUN pip install --upgrade pip \
-    && pip install torch==2.5.1 torchvision==0.20.1 \
-       --index-url https://download.pytorch.org/whl/cpu
-
-COPY requirements.txt .
-RUN pip install -r requirements.txt
-
-COPY . .
-
-# 모델 다운로드/캐시가 가능하도록 쓰기 가능 디렉터리 보장
-# (Hugging Face Spaces 등 비루트 사용자로 실행되는 환경 대비)
-RUN mkdir -p /app/models && chmod -R 777 /app/models
-
-# 클라우드 플랫폼이 주입하는 $PORT 를 사용합니다(없으면 8000).
-EXPOSE 8000
-CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}"]
+# A-EYE production ensemble backend for Hugging Face Docker Spaces.
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    A_EYE_MODELS=32,37,34,36 \
+    A_EYE_MODEL_REPO=wonjun12/aeye-ensemble-models \
+    A_EYE_RANDOM_INIT_BACKBONES=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --upgrade pip \
+    && pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+CMD ["sh", "-c", "python -u app.py"]

README_HF_ENSEMBLE.md

@@ -0,0 +1,66 @@
+# A-EYE Hugging Face Ensemble Backend
+
+This backend runs the production ensemble server.
+
+Recommended model set:
+
+```text
+A_EYE_MODELS=32,37,34,36
+A_EYE_MODEL_REPO=wonjun12/aeye-ensemble-models
+```
+
+Required files:
+
+```text
+app.py
+Dockerfile
+requirements.txt
+scripts/app_production.py
+src/
+experiments/32_practical_quality_balanced/config.yaml
+experiments/32_practical_quality_balanced/checkpoints/best32.pt
+experiments/37_real_fp_mined_balanced/config.yaml
+experiments/37_real_fp_mined_balanced/checkpoints/best.pt
+experiments/34_latest_hardpair_balanced/config.yaml
+experiments/34_latest_hardpair_balanced/checkpoints/best.pt
+experiments/36_realworld_guard_v2/config.yaml
+experiments/36_realworld_guard_v2/checkpoints/best.pt
+```
+
+Run command:
+
+```bash
+python -u app.py
+```
+
+Docker Spaces will use the included `Dockerfile`, which runs the same command.
+
+For the full ensemble on a free Space, keep large checkpoints in a separate
+model repository and let the Space download them at startup:
+
+```text
+wonjun12/aeye-ensemble-models
+```
+
+If the model repository is private, add a Space secret named `HF_TOKEN` with
+read access to that model repository.
+
+Health check:
+
+```bash
+curl https://YOUR_SPACE_URL/api/health
+```
+
+Prediction endpoint:
+
+```text
+POST /api/predict
+multipart form field: image
+optional fields: mode=production, xai=0 or 1
+```
+
+Notes:
+
+- CPU Spaces will be slow because four checkpoints are loaded.
+- A GPU Space is recommended for app deployment.
+- Large `.pt` files should be uploaded with Git LFS or `huggingface-cli upload`.

app.py

@@ -0,0 +1,15 @@
+"""Hugging Face Spaces entrypoint for the A-EYE ensemble backend."""
+
+from __future__ import annotations
+
+import os
+
+os.environ.setdefault("A_EYE_MODELS", "32,37,34,36")
+os.environ.setdefault("A_EYE_MODEL_REPO", "wonjun12/aeye-ensemble-models")
+os.environ.setdefault("A_EYE_PORT", os.environ.get("PORT", "7860"))
+
+from scripts.app_production import main  # noqa: E402
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1,10 +1,8 @@
-fastapi==0.115.6
-uvicorn[standard]==0.34.0
-pydantic==2.10.4
-python-multipart==0.0.20
-pillow==11.0.0
-numpy==2.1.3
-torch==2.5.1
-torchvision==0.20.1
-grad-cam==1.5.4
-python-dotenv==1.0.1
+flask==3.0.3
+pyyaml>=6.0
+pillow>=10.0.0
+numpy>=1.24.0
+torch>=2.1.0
+torchvision>=0.16.0
+transformers>=4.38.0
+huggingface_hub>=0.24.0

scripts/app_production.py

@@ -0,0 +1,788 @@
+"""Production-style A-EYE tester with ensemble triage and XAI.
+
+This server is meant for app/backend testing. It reduces confident mistakes by
+combining several strong checkpoints and returning "review" when evidence is
+not stable enough for a paid user-facing decision.
+"""
+
+from __future__ import annotations
+
+import io
+import copy
+import json
+import os
+import shutil
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from hashlib import sha1
+from pathlib import Path
+from threading import Lock
+
+import torch
+import yaml
+from flask import Flask, jsonify, render_template_string, request
+from PIL import Image, ImageOps
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+DEVICE = torch.device(
+    "cpu"
+    if os.environ.get("A_EYE_FORCE_CPU", "").strip().lower() in {"1", "true", "yes"}
+    else ("cuda" if torch.cuda.is_available() else "cpu")
+)
+
+FEEDBACK_DIR = ROOT / "hard_examples" / "production_feedback"
+DEFAULT_MODELS = ("32", "37", "34", "36")
+REMOTE_DOWNLOAD_LOGGED: set[str] = set()
+
+MODEL_REGISTRY = {
+    "38": {
+        "exp": "38_paid_service_balanced",
+        "label": "38번 유료 서비스 균형 모델",
+        "role": "실제사진 오탐과 AI 미탐 동시 개선",
+        "weight": 0.48,
+    },
+    "32": {
+        "exp": "32_practical_quality_balanced",
+        "label": "32번 실사용 균형 모델",
+        "role": "전체 균형과 최신 AI 탐지",
+        "weight": 0.45,
+    },
+    "37": {
+        "exp": "37_real_fp_mined_balanced",
+        "label": "37번 실제사진 보호 모델",
+        "role": "실제사진 오탐 억제",
+        "weight": 0.30,
+    },
+    "34": {
+        "exp": "34_latest_hardpair_balanced",
+        "label": "34번 최신 hardpair 모델",
+        "role": "고품질 AI 이미지 보강",
+        "weight": 0.15,
+    },
+    "36": {
+        "exp": "36_realworld_guard_v2",
+        "label": "36번 realworld guard v2",
+        "role": "저조도와 웹 이미지 안정성",
+        "weight": 0.10,
+    },
+}
+
+
+@dataclass
+class ModelState:
+    model_id: str
+    exp_name: str
+    label: str
+    role: str
+    weight: float
+    model: torch.nn.Module
+    transform: object
+    config: dict
+    checkpoint: Path
+    threshold: float
+    checkpoint_mtime: float
+    loaded_at: str
+
+
+@dataclass
+class EnsembleState:
+    models: list[ModelState]
+    loaded_at: str
+
+
+app = Flask(__name__)
+app.config["MAX_CONTENT_LENGTH"] = 36 * 1024 * 1024
+
+STATE: EnsembleState | None = None
+STATE_LOCK = Lock()
+
+
+def _read_json(path: Path, default):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return default
+
+
+def _download_model_file(rel_path: Path) -> bool:
+    repo_id = os.environ.get("A_EYE_MODEL_REPO", "").strip()
+    if not repo_id:
+        return False
+    dst = ROOT / rel_path
+    if dst.exists() and dst.stat().st_size > 0:
+        return True
+    try:
+        from huggingface_hub import hf_hub_download
+
+        token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN") or None
+        cached = hf_hub_download(
+            repo_id=repo_id,
+            repo_type=os.environ.get("A_EYE_MODEL_REPO_TYPE", "model"),
+            filename=rel_path.as_posix(),
+            token=token,
+        )
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(cached, dst)
+        key = rel_path.as_posix()
+        if key not in REMOTE_DOWNLOAD_LOGGED:
+            print(f"[A-EYE production] downloaded {key} from {repo_id}", flush=True)
+            REMOTE_DOWNLOAD_LOGGED.add(key)
+        return True
+    except Exception as exc:
+        key = rel_path.as_posix()
+        if key not in REMOTE_DOWNLOAD_LOGGED:
+            print(f"[A-EYE production] remote model file unavailable: {key} ({exc})", flush=True)
+            REMOTE_DOWNLOAD_LOGGED.add(key)
+        return False
+
+
+def _ensure_experiment_files(exp_name: str) -> None:
+    exp_rel = Path("experiments") / exp_name
+    for rel in [
+        exp_rel / "config.yaml",
+        exp_rel / "threshold_report.json",
+        exp_rel / "history.json",
+        exp_rel / "checkpoints" / "best.pt",
+        exp_rel / "checkpoints" / "best32.pt",
+    ]:
+        _download_model_file(rel)
+
+
+def _checkpoint_for(exp_name: str) -> tuple[Path, Path]:
+    _ensure_experiment_files(exp_name)
+    exp_dir = ROOT / "experiments" / exp_name
+    ckpt_dir = exp_dir / "checkpoints"
+    ckpt = exp_dir / "checkpoints" / "best.pt"
+    cfg = exp_dir / "config.yaml"
+    if not ckpt.exists():
+        alternates = [
+            ckpt_dir / "best32.pt",
+            *sorted(ckpt_dir.glob("best*.pt"), key=lambda p: p.stat().st_mtime, reverse=True),
+            *sorted(ckpt_dir.glob("epoch_*.pt"), key=lambda p: p.stat().st_mtime, reverse=True),
+        ]
+        ckpt = next((path for path in alternates if path.exists()), ckpt)
+    if not ckpt.exists():
+        raise FileNotFoundError(f"checkpoint not found under: {ckpt_dir}")
+    if not cfg.exists():
+        raise FileNotFoundError(f"config not found: {cfg}")
+    return ckpt, cfg
+
+
+def _threshold_from(exp_name: str, checkpoint_metrics: dict) -> float:
+    _ensure_experiment_files(exp_name)
+    exp_dir = ROOT / "experiments" / exp_name
+    threshold_report = _read_json(exp_dir / "threshold_report.json", {})
+    candidates = [
+        threshold_report,
+        checkpoint_metrics,
+        checkpoint_metrics.get("val", {}) if isinstance(checkpoint_metrics, dict) else {},
+    ]
+    for source in candidates:
+        if not isinstance(source, dict):
+            continue
+        for key in ("threshold", "calibrated_threshold"):
+            try:
+                value = float(source[key])
+            except Exception:
+                continue
+            if 0.001 <= value <= 0.999:
+                return value
+
+    best_score = -1e9
+    best_threshold = None
+    history = _read_json(exp_dir / "history.json", [])
+    if isinstance(history, list):
+        for row in history:
+            val = row.get("val", {}) if isinstance(row, dict) else {}
+            score = val.get("calibrated_real_guarded_score", val.get("real_guarded_score"))
+            threshold = val.get("calibrated_threshold", val.get("threshold"))
+            try:
+                score_f = float(score)
+                threshold_f = float(threshold)
+            except Exception:
+                continue
+            if 0.001 <= threshold_f <= 0.999 and score_f > best_score:
+                best_score = score_f
+                best_threshold = threshold_f
+    return float(best_threshold) if best_threshold is not None else 0.5
+
+
+def _model_ids_from_env() -> list[str]:
+    raw = os.environ.get("A_EYE_MODELS", ",".join(DEFAULT_MODELS))
+    ids = [part.strip() for part in raw.split(",") if part.strip()]
+    valid = [model_id for model_id in ids if model_id in MODEL_REGISTRY]
+    return valid or list(DEFAULT_MODELS)
+
+
+def _load_one(model_id: str) -> ModelState:
+    from src.data.artifact_transforms import get_artifact_transforms
+    from src.models.factory import build_model
+
+    spec = MODEL_REGISTRY[model_id]
+    ckpt_path, cfg_path = _checkpoint_for(spec["exp"])
+    cfg = yaml.safe_load(cfg_path.read_text(encoding="utf-8"))
+    model_cfg = copy.deepcopy(cfg)
+    if os.environ.get("A_EYE_RANDOM_INIT_BACKBONES", "").strip().lower() in {"1", "true", "yes"}:
+        model_cfg.setdefault("model", {})["pretrained"] = False
+    model = build_model(model_cfg)
+    checkpoint = torch.load(ckpt_path, map_location=DEVICE, weights_only=True)
+    state = checkpoint.get("model_state_dict", checkpoint)
+    model.load_state_dict(state)
+    model.to(DEVICE).eval()
+
+    transform = get_artifact_transforms(
+        "val",
+        image_size=int(cfg.get("data", {}).get("image_size", 224)),
+    )
+    threshold = _threshold_from(spec["exp"], checkpoint.get("metrics", {}))
+    return ModelState(
+        model_id=model_id,
+        exp_name=spec["exp"],
+        label=spec["label"],
+        role=spec["role"],
+        weight=float(spec["weight"]),
+        model=model,
+        transform=transform,
+        config=cfg,
+        checkpoint=ckpt_path,
+        threshold=threshold,
+        checkpoint_mtime=ckpt_path.stat().st_mtime,
+        loaded_at=datetime.now().isoformat(timespec="seconds"),
+    )
+
+
+def load_ensemble(force: bool = False) -> EnsembleState:
+    global STATE
+    with STATE_LOCK:
+        model_ids = _model_ids_from_env()
+        current_key = [(m.model_id, m.checkpoint_mtime) for m in STATE.models] if STATE else None
+        wanted_key = []
+        for model_id in model_ids:
+            spec = MODEL_REGISTRY[model_id]
+            ckpt, _cfg = _checkpoint_for(spec["exp"])
+            wanted_key.append((model_id, ckpt.stat().st_mtime))
+        if not force and STATE is not None and current_key == wanted_key:
+            return STATE
+
+        models = [_load_one(model_id) for model_id in model_ids]
+        total_weight = sum(m.weight for m in models) or 1.0
+        for model_state in models:
+            model_state.weight = model_state.weight / total_weight
+        STATE = EnsembleState(models=models, loaded_at=datetime.now().isoformat(timespec="seconds"))
+        loaded = ", ".join(f"{m.model_id}(thr={m.threshold:.3f})" for m in models)
+        print(f"[A-EYE production] loaded {loaded} on {DEVICE}", flush=True)
+        return STATE
+
+
+def _tta_batch(image: Image.Image, model_state: ModelState) -> torch.Tensor:
+    rgb = ImageOps.exif_transpose(image).convert("RGB")
+    variants = [rgb, ImageOps.mirror(rgb)]
+    return torch.stack([model_state.transform(variant) for variant in variants], dim=0).to(DEVICE)
+
+
+def _logits(model: torch.nn.Module, batch: torch.Tensor) -> torch.Tensor:
+    output = model(batch)
+    return output["logits"] if isinstance(output, dict) else output
+
+
+def _predict_one(image: Image.Image, model_state: ModelState) -> dict:
+    start = time.perf_counter()
+    batch = _tta_batch(image, model_state)
+    with torch.no_grad():
+        with torch.amp.autocast(device_type=DEVICE.type, enabled=DEVICE.type == "cuda"):
+            logits = _logits(model_state.model, batch)
+        probs = torch.softmax(logits.float(), dim=1).mean(dim=0)
+    fake_prob = float(probs[1].detach().cpu())
+    vote = "fake" if fake_prob >= model_state.threshold else "real"
+    return {
+        "id": model_state.model_id,
+        "exp_name": model_state.exp_name,
+        "label": model_state.label,
+        "role": model_state.role,
+        "weight": round(model_state.weight, 4),
+        "threshold": round(model_state.threshold, 4),
+        "fake_prob": round(fake_prob, 6),
+        "real_prob": round(1.0 - fake_prob, 6),
+        "vote": vote,
+        "margin_from_threshold": round(fake_prob - model_state.threshold, 6),
+        "latency_ms": round((time.perf_counter() - start) * 1000, 1),
+    }
+
+
+def _policy(mode: str, model_count: int) -> dict:
+    mode = mode if mode in {"production", "real_guard", "sensitive"} else "production"
+    strong_votes = max(2, int(round(model_count * 0.75)))
+    if mode == "real_guard":
+        return {
+            "mode": mode,
+            "fake_min": 0.72,
+            "real_max": 0.38,
+            "fake_votes": strong_votes,
+            "real_votes": max(2, strong_votes - 1),
+            "max_disagreement": 0.34,
+        }
+    if mode == "sensitive":
+        return {
+            "mode": mode,
+            "fake_min": 0.56,
+            "real_max": 0.24,
+            "fake_votes": max(2, strong_votes - 1),
+            "real_votes": strong_votes,
+            "max_disagreement": 0.46,
+        }
+    return {
+        "mode": mode,
+        "fake_min": 0.66,
+        "real_max": 0.34,
+        "fake_votes": strong_votes,
+        "real_votes": strong_votes,
+        "max_disagreement": 0.40,
+    }
+
+
+def _decide(rows: list[dict], mode: str) -> dict:
+    policy = _policy(mode, len(rows))
+    weighted_fake = sum(row["fake_prob"] * row["weight"] for row in rows)
+    fake_votes = sum(1 for row in rows if row["vote"] == "fake")
+    real_votes = len(rows) - fake_votes
+    probs = [row["fake_prob"] for row in rows]
+    disagreement = max(probs) - min(probs) if probs else 0.0
+
+    verdict = "review"
+    reasons = []
+    if fake_votes >= policy["fake_votes"] and weighted_fake >= policy["fake_min"]:
+        if disagreement <= policy["max_disagreement"] or weighted_fake >= 0.82:
+            verdict = "fake"
+            reasons.append("여러 모델이 AI 쪽으로 동시에 강하게 기울었습니다.")
+        else:
+            reasons.append("AI 가능성은 높지만 모델 간 차이가 커서 검토가 필요합니다.")
+    elif real_votes >= policy["real_votes"] and weighted_fake <= policy["real_max"]:
+        if disagreement <= policy["max_disagreement"] or weighted_fake <= 0.18:
+            verdict = "real"
+            reasons.append("여러 모델이 실제사진 쪽으로 안정적으로 일치했습니다.")
+        else:
+            reasons.append("실제사진 가능성은 높지만 일부 모델이 반대 신호를 냅니다.")
+    else:
+        reasons.append("유료 서비스 기준으로는 확신 판정을 내리기 부족합니다.")
+
+    if verdict == "review":
+        if 0.42 <= weighted_fake <= 0.58:
+            reasons.append("AI 확률이 중앙값 근처라 애매합니다.")
+        if fake_votes and real_votes:
+            reasons.append(f"모델 투표가 AI {fake_votes}개, 실제 {real_votes}개로 갈렸습니다.")
+        if disagreement > policy["max_disagreement"]:
+            reasons.append("모델 간 확률 차이가 큽니다.")
+
+    if verdict == "fake":
+        confidence = min(0.99, 0.50 + (weighted_fake - 0.50) * 1.55)
+        label_ko = "AI 생성 이미지"
+        reliability = "높음" if confidence >= 0.82 else "중간"
+    elif verdict == "real":
+        confidence = min(0.99, 0.50 + (0.50 - weighted_fake) * 1.55)
+        label_ko = "실제 사진"
+        reliability = "높음" if confidence >= 0.82 else "중간"
+    else:
+        confidence = max(0.50, 1.0 - abs(weighted_fake - 0.50) * 1.6 - min(disagreement, 0.5) * 0.45)
+        label_ko = "검토 필요"
+        reliability = "보류"
+
+    return {
+        "verdict": verdict,
+        "prediction": {"fake": "AI", "real": "REAL", "review": "REVIEW"}[verdict],
+        "label_ko": label_ko,
+        "weighted_fake_prob": round(weighted_fake, 6),
+        "fake_prob": round(weighted_fake, 6),
+        "real_prob": round(1.0 - weighted_fake, 6),
+        "confidence": round(float(confidence), 4),
+        "fake_votes": fake_votes,
+        "real_votes": real_votes,
+        "disagreement": round(float(disagreement), 6),
+        "mode": policy["mode"],
+        "policy": policy,
+        "reliability": reliability,
+        "reason_ko": " ".join(reasons),
+        "production_note_ko": (
+            "배포용 판정은 오판을 줄이기 위해 애매한 이미지를 검토 필요로 돌립니다. "
+            "무조건 real/fake로 찍는 데모 모드보다 사용자 신뢰에 유리합니다."
+        ),
+    }
+
+
+def predict_image(image: Image.Image, mode: str = "production") -> dict:
+    start = time.perf_counter()
+    state = load_ensemble()
+    rows = [_predict_one(image, model_state) for model_state in state.models]
+    decision = _decide(rows, mode)
+    return {
+        "ok": True,
+        **decision,
+        "models": rows,
+        "model_probs": rows,
+        "model": {
+            "kind": "ensemble",
+            "loaded_at": state.loaded_at,
+            "ids": [m.model_id for m in state.models],
+            "device": str(DEVICE),
+        },
+        "latency_ms": round((time.perf_counter() - start) * 1000, 1),
+        "api_version": "production-ensemble-1.0",
+    }
+
+
+def _xai_model(preferred: str | None = None) -> ModelState:
+    state = load_ensemble()
+    preferred = preferred or os.environ.get("A_EYE_XAI_MODEL", "32")
+    for model_state in state.models:
+        if model_state.model_id == preferred:
+            return model_state
+    return state.models[0]
+
+
+def explain_payload(image: Image.Image, preferred_model: str | None = None) -> dict:
+    from src.xai import explain_image, png_b64
+
+    model_state = _xai_model(preferred_model)
+    result = explain_image(
+        model_state.model,
+        model_state.transform,
+        DEVICE,
+        image,
+        target_class=1,
+        expansion=1.30,
+    )
+    overlay_b64 = png_b64(result.overlay)
+    heatmap_b64 = png_b64(result.heatmap)
+    return {
+        "ok": True,
+        "xai_model": model_state.model_id,
+        "xai_model_name": model_state.exp_name,
+        "xai_method": result.meta.get("method", "occlusion_vit_srm_inputgrad"),
+        "xai": result.meta,
+        "overlay_b64": overlay_b64,
+        "heatmap_b64": heatmap_b64,
+        "overlay_data_url": f"data:image/png;base64,{overlay_b64}",
+        "heatmap_data_url": f"data:image/png;base64,{heatmap_b64}",
+        "xai_note_ko": (
+            "히트맵은 모델이 AI 판정에 사용한 증거 영역입니다. "
+            "합성된 부분을 정확히 잘라내는 마스크가 아니라 판단 근거 지도입니다."
+        ),
+        "xai_limitation_ko": (
+            "고양이, 얼굴, 물체 전체를 정확히 칠하려면 객체 분할 모델과 조작 위치 라벨이 별도로 필요합니다."
+        ),
+    }
+
+
+def save_feedback(image_bytes: bytes, original_name: str, true_label: str, metadata: dict) -> dict:
+    label = true_label if true_label in {"real", "fake", "uncertain"} else "uncertain"
+    bucket = FEEDBACK_DIR / label
+    bucket.mkdir(parents=True, exist_ok=True)
+    digest = sha1(image_bytes).hexdigest()
+    suffix = Path(original_name).suffix.lower()
+    if suffix not in {".jpg", ".jpeg", ".png", ".webp", ".bmp"}:
+        suffix = ".jpg"
+    image_path = bucket / f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{digest[:12]}{suffix}"
+    image_path.write_bytes(image_bytes)
+    record = {
+        "saved_at": datetime.now().isoformat(timespec="seconds"),
+        "image": str(image_path),
+        "sha1": digest,
+        "true_label": label,
+        **metadata,
+    }
+    with (FEEDBACK_DIR / "feedback.jsonl").open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    return {"bucket": label, "path": str(image_path), "sha1": digest}
+
+
+def _status_payload() -> dict:
+    state = load_ensemble()
+    return {
+        "ok": True,
+        "version": "production-ensemble-1.0",
+        "api_version": "production-ensemble-1.0",
+        "device": str(DEVICE),
+        "xai": True,
+        "loaded_at": state.loaded_at,
+        "models": [
+            {
+                "id": m.model_id,
+                "exp_name": m.exp_name,
+                "label": m.label,
+                "role": m.role,
+                "weight": round(m.weight, 4),
+                "threshold": round(m.threshold, 4),
+                "checkpoint": str(m.checkpoint),
+            }
+            for m in state.models
+        ],
+        "default_mode": "production",
+        "modes": ["production", "real_guard", "sensitive"],
+    }
+
+
+@app.after_request
+def add_cors(response):
+    response.headers["Access-Control-Allow-Origin"] = "*"
+    response.headers["Access-Control-Allow-Methods"] = "GET,POST,OPTIONS"
+    response.headers["Access-Control-Allow-Headers"] = "Content-Type,Authorization"
+    return response
+
+
+HTML = """
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>A-EYE Production Ensemble</title>
+  <style>
+    :root { color-scheme: dark; --bg:#08111f; --panel:#101b2c; --line:#24344d; --text:#e8f0ff; --muted:#8fa3bf; --blue:#63a7ff; --red:#ff6b6b; --green:#48d597; --yellow:#f3c969; }
+    * { box-sizing:border-box; }
+    body { margin:0; font-family:system-ui,-apple-system,Segoe UI,sans-serif; background:var(--bg); color:var(--text); }
+    main { max-width:1120px; margin:0 auto; padding:28px 18px 48px; }
+    header { display:flex; justify-content:space-between; gap:16px; align-items:flex-start; margin-bottom:22px; }
+    h1 { margin:0; font-size:26px; letter-spacing:0; }
+    .sub { color:var(--muted); margin-top:8px; line-height:1.5; }
+    .grid { display:grid; grid-template-columns:360px 1fr; gap:18px; align-items:start; }
+    .panel { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:16px; }
+    label { display:block; color:var(--muted); font-size:13px; margin-bottom:8px; }
+    input, select, button { width:100%; border-radius:8px; border:1px solid var(--line); background:#07101d; color:var(--text); padding:11px 12px; font-size:15px; }
+    button { cursor:pointer; background:#12345d; border-color:#2e5f99; font-weight:700; }
+    button:disabled { opacity:.55; cursor:not-allowed; }
+    .preview { width:100%; aspect-ratio:1/1; object-fit:contain; background:#050b13; border:1px solid var(--line); border-radius:8px; margin-top:12px; }
+    .verdict { font-size:32px; font-weight:800; margin:0 0 8px; }
+    .fake { color:var(--red); } .real { color:var(--green); } .review { color:var(--yellow); }
+    .metrics { display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:10px; margin:14px 0; }
+    .metric { border:1px solid var(--line); border-radius:8px; padding:10px; background:#07101d; }
+    .metric b { display:block; font-size:20px; margin-top:4px; }
+    table { width:100%; border-collapse:collapse; margin-top:12px; font-size:14px; }
+    th, td { border-bottom:1px solid var(--line); padding:9px 6px; text-align:left; }
+    th { color:var(--muted); font-weight:600; }
+    .xai { display:grid; grid-template-columns:1fr 1fr; gap:12px; margin-top:14px; }
+    .xai img { width:100%; border:1px solid var(--line); border-radius:8px; background:#050b13; }
+    .note { color:var(--muted); line-height:1.55; }
+    @media (max-width:860px) { .grid { grid-template-columns:1fr; } .metrics { grid-template-columns:1fr 1fr; } header { display:block; } }
+  </style>
+</head>
+<body>
+<main>
+  <header>
+    <div>
+      <h1>A-EYE 실서비스 판정 서버</h1>
+      <div class="sub">32/37/34/36 모델 앙상블로 실제사진 오탐과 AI 미탐을 동시에 줄이고, 애매한 이미지는 검토 필요로 분리합니다.</div>
+    </div>
+    <div class="sub" id="status">서버 상태 확인 중</div>
+  </header>
+  <div class="grid">
+    <section class="panel">
+      <label>이미지 업로드</label>
+      <input id="file" type="file" accept="image/*">
+      <img id="preview" class="preview" alt="">
+      <label style="margin-top:14px;">판정 모드</label>
+      <select id="mode">
+        <option value="production">실서비스 균형</option>
+        <option value="real_guard">실제사진 보호 우선</option>
+        <option value="sensitive">AI 탐지 민감</option>
+      </select>
+      <button id="run" style="margin-top:14px;">분석하기</button>
+      <div class="sub" style="margin-top:12px;">앱에서는 /api/predict, /api/health, /api/version을 사용하면 됩니다.</div>
+    </section>
+    <section class="panel">
+      <p id="label" class="verdict review">대기 중</p>
+      <div id="reason" class="note">이미지를 넣으면 앙상블 판정과 XAI가 표시됩니다.</div>
+      <div class="metrics">
+        <div class="metric"><span class="note">AI 확률</span><b id="fakeProb">-</b></div>
+        <div class="metric"><span class="note">실제 확률</span><b id="realProb">-</b></div>
+        <div class="metric"><span class="note">신뢰도</span><b id="conf">-</b></div>
+        <div class="metric"><span class="note">모델 차이</span><b id="disagree">-</b></div>
+      </div>
+      <table>
+        <thead><tr><th>모델</th><th>역할</th><th>AI 확률</th><th>투표</th></tr></thead>
+        <tbody id="modelRows"></tbody>
+      </table>
+      <div class="xai" id="xaiBox" style="display:none;">
+        <div><div class="note">원본 위 의심 영역</div><img id="overlay" alt=""></div>
+        <div><div class="note">히트맵</div><img id="heatmap" alt=""></div>
+      </div>
+      <div class="note" id="xaiNote" style="margin-top:10px;"></div>
+    </section>
+  </div>
+</main>
+<script>
+const file = document.getElementById("file");
+const preview = document.getElementById("preview");
+const run = document.getElementById("run");
+let selected = null;
+const pct = v => `${(Number(v || 0) * 100).toFixed(2)}%`;
+file.addEventListener("change", () => {
+  selected = file.files[0] || null;
+  preview.src = selected ? URL.createObjectURL(selected) : "";
+});
+async function loadStatus() {
+  const res = await fetch("/api/health");
+  const data = await res.json();
+  document.getElementById("status").textContent = data.ok ? `${data.device} · ${data.models.map(m => m.id).join("+")}` : data.error;
+}
+run.addEventListener("click", async () => {
+  if (!selected) return;
+  run.disabled = true;
+  const form = new FormData();
+  form.append("image", selected);
+  form.append("mode", document.getElementById("mode").value);
+  form.append("xai", "1");
+  try {
+    const res = await fetch("/api/predict", { method:"POST", body:form });
+    const data = await res.json();
+    if (!res.ok || !data.ok) throw new Error(data.error || "분석 실패");
+    const label = document.getElementById("label");
+    label.textContent = data.label_ko;
+    label.className = `verdict ${data.verdict}`;
+    document.getElementById("reason").textContent = data.reason_ko;
+    document.getElementById("fakeProb").textContent = pct(data.fake_prob);
+    document.getElementById("realProb").textContent = pct(data.real_prob);
+    document.getElementById("conf").textContent = pct(data.confidence);
+    document.getElementById("disagree").textContent = pct(data.disagreement);
+    document.getElementById("modelRows").innerHTML = data.models.map(m => `<tr><td>${m.id}</td><td>${m.role}</td><td>${pct(m.fake_prob)}</td><td>${m.vote === "fake" ? "AI" : "실제"}</td></tr>`).join("");
+    if (data.overlay_data_url) {
+      document.getElementById("overlay").src = data.overlay_data_url;
+      document.getElementById("heatmap").src = data.heatmap_data_url;
+      document.getElementById("xaiBox").style.display = "grid";
+      document.getElementById("xaiNote").textContent = data.xai_note_ko || "";
+    }
+  } catch (err) {
+    document.getElementById("label").textContent = "오류";
+    document.getElementById("reason").textContent = err.message;
+  } finally {
+    run.disabled = false;
+  }
+});
+loadStatus().catch(err => document.getElementById("status").textContent = err.message);
+</script>
+</body>
+</html>
+"""
+
+
+@app.get("/")
+def index():
+    return render_template_string(HTML)
+
+
+@app.get("/health")
+@app.get("/api/health")
+@app.get("/status")
+@app.get("/api/status")
+def health_route():
+    try:
+        return jsonify(_status_payload())
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+@app.get("/version")
+@app.get("/api/version")
+def version_route():
+    try:
+        return jsonify(_status_payload())
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+@app.post("/reload")
+@app.post("/api/reload")
+def reload_route():
+    try:
+        load_ensemble(force=True)
+        return jsonify(_status_payload())
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+@app.route("/predict", methods=["POST", "OPTIONS"])
+@app.route("/api/predict", methods=["POST", "OPTIONS"])
+@app.route("/analyze", methods=["POST", "OPTIONS"])
+@app.route("/api/analyze", methods=["POST", "OPTIONS"])
+@app.route("/classify", methods=["POST", "OPTIONS"])
+@app.route("/api/classify", methods=["POST", "OPTIONS"])
+@app.route("/detect", methods=["POST", "OPTIONS"])
+@app.route("/api/detect", methods=["POST", "OPTIONS"])
+def predict_route():
+    if request.method == "OPTIONS":
+        return ("", 204)
+    upload = request.files.get("image") or request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"ok": False, "error": "image file is required"}), 400
+    raw = upload.read()
+    if not raw:
+        return jsonify({"ok": False, "error": "empty image"}), 400
+    try:
+        image = Image.open(io.BytesIO(raw))
+        payload = predict_image(image, mode=request.form.get("mode", "production"))
+        include_xai = request.form.get("xai", request.args.get("xai", "1")).strip().lower()
+        if include_xai not in {"0", "false", "no"}:
+            payload.update(explain_payload(image, request.form.get("xai_model")))
+        return jsonify(payload)
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+@app.route("/xai", methods=["POST", "OPTIONS"])
+@app.route("/api/xai", methods=["POST", "OPTIONS"])
+@app.route("/explain", methods=["POST", "OPTIONS"])
+@app.route("/api/explain", methods=["POST", "OPTIONS"])
+def xai_route():
+    if request.method == "OPTIONS":
+        return ("", 204)
+    upload = request.files.get("image") or request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"ok": False, "error": "image file is required"}), 400
+    raw = upload.read()
+    if not raw:
+        return jsonify({"ok": False, "error": "empty image"}), 400
+    try:
+        return jsonify(explain_payload(Image.open(io.BytesIO(raw)), request.form.get("xai_model")))
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+@app.route("/feedback", methods=["POST", "OPTIONS"])
+@app.route("/api/feedback", methods=["POST", "OPTIONS"])
+def feedback_route():
+    if request.method == "OPTIONS":
+        return ("", 204)
+    upload = request.files.get("image") or request.files.get("file")
+    if upload is None or not upload.filename:
+        return jsonify({"ok": False, "error": "image file is required"}), 400
+    image_bytes = upload.read()
+    if not image_bytes:
+        return jsonify({"ok": False, "error": "empty image"}), 400
+    metadata = {
+        "predicted_label": request.form.get("predicted_label"),
+        "fake_prob": request.form.get("fake_prob"),
+        "real_prob": request.form.get("real_prob"),
+        "mode": request.form.get("mode"),
+        "models": request.form.get("models"),
+    }
+    try:
+        saved = save_feedback(image_bytes, upload.filename, request.form.get("true_label", "uncertain"), metadata)
+        return jsonify({"ok": True, **saved})
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+
+def main() -> None:
+    host = os.environ.get("A_EYE_HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT") or os.environ.get("A_EYE_PORT", "8097"))
+    load_ensemble()
+    print(f"[A-EYE production] open http://127.0.0.1:{port}", flush=True)
+    app.run(host=host, port=port, debug=False, use_reloader=False)
+
+
+if __name__ == "__main__":
+    main()

src/api/__init__.py

@@ -0,0 +1 @@
+# TODO: API 구현 완료 후 export 추가

src/data/__init__.py

@@ -0,0 +1,2 @@
+from .dataset import AEyeDataset, build_dataloaders, LABEL_MAP, SUPPORTED_EXTS
+from .transforms import get_transforms, IMAGENET_MEAN, IMAGENET_STD, CLIP_MEAN, CLIP_STD

src/data/all_sources_dataset.py

@@ -0,0 +1,321 @@
+"""Dataset utilities for training on every labeled local image source."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from collections import Counter, defaultdict
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Callable, Iterable
+
+from PIL import Image, UnidentifiedImageError
+import torch
+from torch.utils.data import Dataset, WeightedRandomSampler
+
+
+SUPPORTED_EXTS = {".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff"}
+LABEL_NAMES = {0: "real", 1: "fake"}
+FOLDER_LABELS = {"real": 0, "REAL": 0, "fake": 1, "FAKE": 1, "ai": 1, "AI": 1}
+
+
+@dataclass(frozen=True)
+class ImageRecord:
+    path: str
+    label: int
+    source: str
+    is_hard: bool = False
+    sample_weight: float = 1.0
+    hard_weight_override: float | None = None
+
+
+def _iter_images(folder: Path) -> Iterable[Path]:
+    for path in folder.rglob("*"):
+        if path.is_file() and path.suffix.lower() in SUPPORTED_EXTS:
+            yield path
+
+
+def _scan_source(source: dict | str | Path) -> list[ImageRecord]:
+    if isinstance(source, (str, Path)):
+        source_cfg = {"path": str(source)}
+    else:
+        source_cfg = dict(source)
+
+    root = Path(source_cfg["path"]).resolve()
+    source_name = source_cfg.get("name", root.name)
+    is_hard = bool(source_cfg.get("hard", False))
+    sample_weight = float(source_cfg.get("sample_weight", source_cfg.get("weight", 1.0)))
+    hard_weight_override = source_cfg.get("hard_weight")
+    if hard_weight_override is not None:
+        hard_weight_override = float(hard_weight_override)
+    if not root.exists():
+        return []
+
+    records: list[ImageRecord] = []
+    root_label = FOLDER_LABELS.get(root.name)
+    if root_label is not None:
+        for image_path in _iter_images(root):
+            records.append(ImageRecord(
+                str(image_path),
+                root_label,
+                source_name,
+                is_hard,
+                sample_weight,
+                hard_weight_override,
+            ))
+        return records
+
+    for child in sorted(root.iterdir()):
+        if not child.is_dir():
+            continue
+        label = FOLDER_LABELS.get(child.name)
+        if label is None:
+            continue
+        for image_path in _iter_images(child):
+            records.append(ImageRecord(
+                str(image_path),
+                label,
+                source_name,
+                is_hard,
+                sample_weight,
+                hard_weight_override,
+            ))
+    return records
+
+
+def collect_labeled_records(sources: list[dict | str | Path]) -> list[ImageRecord]:
+    records: list[ImageRecord] = []
+    for source in sources:
+        records.extend(_scan_source(source))
+    return records
+
+
+def _sha1(path: str, chunk_size: int = 1024 * 1024) -> str:
+    h = hashlib.sha1()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(chunk_size)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def dedupe_records(
+    records: list[ImageRecord],
+    full_sha1: bool = False,
+) -> tuple[list[ImageRecord], dict]:
+    """Remove duplicate image files and drop label conflicts.
+
+    By default this hashes only files that share the same filename and size. It
+    is much faster for a 600k-image local pool while catching the common duplicate
+    and UI-feedback conflict cases. Set full_sha1=True for a slower exact pass.
+    """
+    if full_sha1:
+        rough_groups: dict[tuple[str, int], list[ImageRecord]] = {("all", 0): records}
+    else:
+        rough_groups = defaultdict(list)
+        for record in records:
+            try:
+                stat = Path(record.path).stat()
+                key = (Path(record.path).name.lower(), stat.st_size)
+            except OSError:
+                key = (Path(record.path).name.lower(), -1)
+            rough_groups[key].append(record)
+
+    kept: list[ImageRecord] = []
+    conflicts: list[dict] = []
+    duplicate_count = 0
+    hashed_files = 0
+    total_to_hash = len(records) if full_sha1 else sum(
+        len(group) for group in rough_groups.values() if len(group) > 1
+    )
+
+    for group in rough_groups.values():
+        if len(group) == 1 and not full_sha1:
+            kept.append(group[0])
+            continue
+
+        by_hash: dict[str, list[ImageRecord]] = defaultdict(list)
+        for record in group:
+            try:
+                digest = _sha1(record.path)
+                hashed_files += 1
+                if total_to_hash and hashed_files % 10000 == 0:
+                    print(
+                        f"[data] sha1 dedupe hashed {hashed_files:,}/{total_to_hash:,} files",
+                        flush=True,
+                    )
+            except OSError:
+                digest = f"missing::{record.path}"
+            by_hash[digest].append(record)
+
+        for digest, same_files in by_hash.items():
+            labels = {item.label for item in same_files}
+            if len(labels) > 1:
+                conflicts.append({
+                    "sha1": digest,
+                    "labels": sorted(labels),
+                    "paths": [item.path for item in same_files[:8]],
+                    "count": len(same_files),
+                })
+                duplicate_count += len(same_files)
+                continue
+            kept.append(same_files[0])
+            duplicate_count += max(0, len(same_files) - 1)
+
+    report = {
+        "input_count": len(records),
+        "kept_count": len(kept),
+        "duplicate_or_conflict_removed": duplicate_count,
+        "conflict_count": len(conflicts),
+        "conflicts_preview": conflicts[:20],
+        "hashed_files": hashed_files,
+        "full_sha1": full_sha1,
+    }
+    return kept, report
+
+
+def split_records(
+    records: list[ImageRecord],
+    val_ratio: float = 0.08,
+    seed: int = 42,
+    force_hard_to_train: bool = True,
+) -> tuple[list[ImageRecord], list[ImageRecord], dict]:
+    rng = random.Random(seed)
+    train: list[ImageRecord] = []
+    val: list[ImageRecord] = []
+    per_class: dict[int, list[ImageRecord]] = defaultdict(list)
+
+    for record in records:
+        if force_hard_to_train and record.is_hard:
+            train.append(record)
+        else:
+            per_class[record.label].append(record)
+
+    for label_records in per_class.values():
+        rng.shuffle(label_records)
+        n_val = max(1, int(len(label_records) * val_ratio))
+        val.extend(label_records[:n_val])
+        train.extend(label_records[n_val:])
+
+    rng.shuffle(train)
+    rng.shuffle(val)
+
+    report = {
+        "train_count": len(train),
+        "val_count": len(val),
+        "force_hard_to_train": force_hard_to_train,
+        "train_counts": _count_records(train),
+        "val_counts": _count_records(val),
+    }
+    return train, val, report
+
+
+def _count_records(records: list[ImageRecord]) -> dict:
+    labels = Counter(record.label for record in records)
+    sources = Counter(record.source for record in records)
+    hard = Counter(record.label for record in records if record.is_hard)
+    weighted_sources = {
+        source: sorted({
+            float(record.hard_weight_override)
+            for record in records
+            if record.source == source and record.hard_weight_override is not None
+        })
+        for source in sources
+    }
+    return {
+        "real": labels.get(0, 0),
+        "fake": labels.get(1, 0),
+        "hard_real": hard.get(0, 0),
+        "hard_fake": hard.get(1, 0),
+        "sources": dict(sorted(sources.items())),
+        "hard_weight_overrides": {
+            source: values for source, values in sorted(weighted_sources.items()) if values
+        },
+    }
+
+
+class AllSourcesDataset(Dataset):
+    def __init__(
+        self,
+        records: list[ImageRecord],
+        transform: Callable | None = None,
+        return_group: bool = False,
+    ):
+        if not records:
+            raise RuntimeError("No image records were found.")
+        self.records = records
+        self.transform = transform
+        self.return_group = bool(return_group)
+        self.group_to_id = {
+            source: idx for idx, source in enumerate(sorted({record.source for record in records}))
+        }
+
+    def __len__(self) -> int:
+        return len(self.records)
+
+    def __getitem__(self, idx: int):
+        last_error: Exception | None = None
+        for offset in range(12):
+            record = self.records[(idx + offset) % len(self.records)]
+            try:
+                image = Image.open(record.path).convert("RGB")
+                if self.transform is not None:
+                    image = self.transform(image)
+                if self.return_group:
+                    return image, record.label, self.group_to_id.get(record.source, 0)
+                return image, record.label
+            except (UnidentifiedImageError, OSError, RuntimeError) as exc:
+                last_error = exc
+        raise RuntimeError(f"Could not load image near index {idx}") from last_error
+
+
+def make_weighted_sampler(
+    records: list[ImageRecord],
+    hard_weight: float = 500.0,
+    source_balance_alpha: float = 0.0,
+    max_source_weight: float = 8.0,
+    num_samples: int | None = None,
+) -> WeightedRandomSampler:
+    counts = Counter(record.label for record in records)
+    source_label_counts = Counter((record.source, record.label) for record in records)
+    total = len(records)
+    source_groups = max(1, len(source_label_counts))
+    weights = []
+    for record in records:
+        class_weight = total / max(1, 2 * counts[record.label])
+        source_weight = 1.0
+        if source_balance_alpha > 0:
+            source_count = source_label_counts[(record.source, record.label)]
+            raw_source_weight = total / max(1, source_groups * source_count)
+            source_weight = min(max_source_weight, raw_source_weight ** source_balance_alpha)
+        hard_multiplier = 1.0
+        if record.is_hard:
+            hard_multiplier = (
+                record.hard_weight_override
+                if record.hard_weight_override is not None
+                else hard_weight
+            )
+        weight = class_weight * source_weight * hard_multiplier * max(0.0, record.sample_weight)
+        weights.append(weight)
+    return WeightedRandomSampler(
+        weights=torch.DoubleTensor(weights),
+        num_samples=num_samples or len(records),
+        replacement=True,
+    )
+
+
+def save_records(path: str | Path, records: list[ImageRecord]) -> None:
+    Path(path).write_text(
+        json.dumps([asdict(record) for record in records], ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def save_split_report(path: str | Path, report: dict) -> None:
+    Path(path).write_text(
+        json.dumps(report, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )

src/data/artifact_transforms.py

@@ -0,0 +1,294 @@
+"""Robust train/eval transforms for practical AI-image detection."""
+
+from __future__ import annotations
+
+import random
+
+import torch
+from PIL import Image, ImageEnhance, ImageFilter
+from torchvision import transforms
+from torchvision.transforms import InterpolationMode
+
+from .transforms import CLIP_MEAN, CLIP_STD, DownsampleUpsample, GaussianNoise, JPEGCompression
+
+
+class RandomUnsharpMask:
+    """Mild sharpening to mimic phone/editor export pipelines."""
+
+    def __init__(self, radius_range=(0.8, 1.4), percent_range=(80, 160), threshold=3):
+        self.radius_range = radius_range
+        self.percent_range = percent_range
+        self.threshold = threshold
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        radius = random.uniform(*self.radius_range)
+        percent = random.randint(*self.percent_range)
+        return img.filter(ImageFilter.UnsharpMask(radius=radius, percent=percent, threshold=self.threshold))
+
+
+class RandomGamma:
+    """Small gamma shift on tensor images in [0, 1]."""
+
+    def __init__(self, gamma_range=(0.88, 1.14)):
+        self.gamma_range = gamma_range
+
+    def __call__(self, tensor: torch.Tensor) -> torch.Tensor:
+        gamma = random.uniform(*self.gamma_range)
+        return torch.clamp(tensor, 0.0, 1.0).pow(gamma)
+
+
+class RandomExposureDown:
+    """Low-light exposure drop to reduce dark-real false positives."""
+
+    def __init__(self, factor_range=(0.24, 0.85)):
+        self.factor_range = factor_range
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        factor = random.uniform(*self.factor_range)
+        return ImageEnhance.Brightness(img).enhance(factor)
+
+
+class RandomColorTemperature:
+    """Warm/cool indoor lighting shift."""
+
+    def __init__(self, strength_range=(0.04, 0.18)):
+        self.strength_range = strength_range
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        strength = random.uniform(*self.strength_range)
+        if random.random() < 0.5:
+            gains = (1.0 + strength, 1.0, 1.0 - strength * 0.55)
+        else:
+            gains = (1.0 - strength * 0.55, 1.0, 1.0 + strength)
+        channels = img.convert("RGB").split()
+        adjusted = [
+            channel.point(lambda value, gain=gain: max(0, min(255, int(value * gain))))
+            for channel, gain in zip(channels, gains)
+        ]
+        return Image.merge("RGB", adjusted)
+
+
+class RandomMotionBlur:
+    """Small horizontal/vertical blur common in phone low-light images."""
+
+    def __init__(self, sizes=(3, 5)):
+        self.sizes = sizes
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        size = random.choice(self.sizes)
+        weights = [0.0] * (size * size)
+        if random.random() < 0.5:
+            row = size // 2
+            for col in range(size):
+                weights[row * size + col] = 1.0 / size
+        else:
+            col = size // 2
+            for row in range(size):
+                weights[row * size + col] = 1.0 / size
+        return img.filter(ImageFilter.Kernel((size, size), weights, scale=1.0))
+
+
+class RandomShadowCrush:
+    """Crush dark tones while preserving highlights."""
+
+    def __init__(self, lift_range=(0.00, 0.08), gamma_range=(1.25, 2.10)):
+        self.lift_range = lift_range
+        self.gamma_range = gamma_range
+
+    def __call__(self, tensor: torch.Tensor) -> torch.Tensor:
+        lift = random.uniform(*self.lift_range)
+        gamma = random.uniform(*self.gamma_range)
+        x = torch.clamp(tensor - lift, 0.0, 1.0) / max(1e-6, 1.0 - lift)
+        return torch.clamp(x.pow(gamma), 0.0, 1.0)
+
+
+class HighISONoise:
+    """Signal-dependent low-light sensor noise."""
+
+    def __init__(self, std_range=(0.008, 0.065), chroma_range=(0.004, 0.030)):
+        self.std_range = std_range
+        self.chroma_range = chroma_range
+
+    def __call__(self, tensor: torch.Tensor) -> torch.Tensor:
+        luminance = tensor.mean(dim=0, keepdim=True).clamp(0.0, 1.0)
+        shot_scale = (1.0 - luminance).sqrt()
+        gray_noise = torch.randn_like(luminance) * random.uniform(*self.std_range) * shot_scale
+        chroma_noise = torch.randn_like(tensor) * random.uniform(*self.chroma_range)
+        return torch.clamp(tensor + gray_noise + chroma_noise, 0.0, 1.0)
+
+
+class RandomProjectorMoire:
+    """Weak stripe pattern from projectors/screens photographed by phones."""
+
+    def __init__(self, amplitude_range=(0.006, 0.026), period_range=(5.0, 18.0)):
+        self.amplitude_range = amplitude_range
+        self.period_range = period_range
+
+    def __call__(self, tensor: torch.Tensor) -> torch.Tensor:
+        _, height, width = tensor.shape
+        device = tensor.device
+        amp = random.uniform(*self.amplitude_range)
+        period = random.uniform(*self.period_range)
+        phase = random.uniform(0.0, 6.2831853)
+        if random.random() < 0.5:
+            axis = torch.arange(width, dtype=tensor.dtype, device=device).view(1, 1, width)
+        else:
+            axis = torch.arange(height, dtype=tensor.dtype, device=device).view(1, height, 1)
+        pattern = torch.sin(axis / period + phase) * amp
+        return torch.clamp(tensor + pattern, 0.0, 1.0)
+
+
+def get_artifact_transforms(
+    mode: str,
+    image_size: int = 224,
+    mean: list[float] | None = None,
+    std: list[float] | None = None,
+    profile: str = "default",
+) -> transforms.Compose:
+    mean = mean or CLIP_MEAN
+    std = std or CLIP_STD
+    normalize = transforms.Normalize(mean=mean, std=std)
+    interpolation = InterpolationMode.BICUBIC
+    resize_size = int(round(image_size / 0.875))
+
+    if mode == "train" and profile == "jpeg_invariance":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.72, 1.0),
+                ratio=(0.80, 1.25),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.12, contrast=0.12, saturation=0.08, hue=0.012),
+            transforms.RandomApply([RandomExposureDown(factor_range=(0.34, 0.92))], p=0.22),
+            transforms.RandomApply([RandomColorTemperature(strength_range=(0.03, 0.14))], p=0.22),
+            transforms.RandomApply([JPEGCompression(quality_range=(70, 95))], p=1.0),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.55, 0.98))], p=0.24),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.08, 0.80))], p=0.16),
+            transforms.RandomApply([RandomMotionBlur(sizes=(3,))], p=0.08),
+            transforms.RandomApply([RandomUnsharpMask()], p=0.10),
+            transforms.ToTensor(),
+            transforms.RandomApply([RandomGamma(gamma_range=(0.70, 1.40))], p=0.42),
+            transforms.RandomApply([HighISONoise(std_range=(0.006, 0.045), chroma_range=(0.003, 0.022))], p=0.20),
+            transforms.RandomApply([RandomProjectorMoire(amplitude_range=(0.004, 0.018))], p=0.06),
+            transforms.RandomApply([GaussianNoise(std_range=(0.002, 0.016))], p=0.18),
+            normalize,
+        ])
+
+    if mode == "train" and profile == "practical_balanced":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.78, 1.0),
+                ratio=(0.85, 1.18),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.10, contrast=0.10, saturation=0.06, hue=0.010),
+            transforms.RandomApply([RandomExposureDown(factor_range=(0.42, 0.95))], p=0.18),
+            transforms.RandomApply([RandomColorTemperature(strength_range=(0.03, 0.12))], p=0.18),
+            transforms.RandomApply([JPEGCompression(quality_range=(65, 96))], p=0.72),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.65, 0.99))], p=0.18),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.08, 0.65))], p=0.10),
+            transforms.RandomApply([RandomMotionBlur(sizes=(3,))], p=0.05),
+            transforms.RandomApply([RandomUnsharpMask()], p=0.08),
+            transforms.ToTensor(),
+            transforms.RandomApply([RandomGamma(gamma_range=(0.78, 1.28))], p=0.22),
+            transforms.RandomApply([HighISONoise(std_range=(0.004, 0.035), chroma_range=(0.002, 0.018))], p=0.16),
+            transforms.RandomApply([RandomProjectorMoire(amplitude_range=(0.004, 0.016))], p=0.05),
+            transforms.RandomApply([GaussianNoise(std_range=(0.002, 0.014))], p=0.12),
+            normalize,
+        ])
+
+    if mode == "train" and profile == "web_real_guard":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.76, 1.0),
+                ratio=(0.82, 1.20),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.12, contrast=0.12, saturation=0.08, hue=0.012),
+            transforms.RandomApply([RandomExposureDown(factor_range=(0.34, 0.94))], p=0.30),
+            transforms.RandomApply([RandomColorTemperature(strength_range=(0.03, 0.16))], p=0.24),
+            transforms.RandomApply([JPEGCompression(quality_range=(55, 96))], p=0.86),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.56, 0.99))], p=0.26),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.08, 0.90))], p=0.14),
+            transforms.RandomApply([RandomMotionBlur(sizes=(3,))], p=0.08),
+            transforms.RandomApply([RandomUnsharpMask()], p=0.12),
+            transforms.ToTensor(),
+            transforms.RandomApply([RandomGamma(gamma_range=(0.72, 1.34))], p=0.30),
+            transforms.RandomApply([HighISONoise(std_range=(0.006, 0.048), chroma_range=(0.003, 0.024))], p=0.24),
+            transforms.RandomApply([RandomProjectorMoire(amplitude_range=(0.004, 0.020))], p=0.07),
+            transforms.RandomApply([GaussianNoise(std_range=(0.002, 0.018))], p=0.16),
+            normalize,
+        ])
+
+    if mode == "train" and profile == "realworld_guard_v2":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.80, 1.0),
+                ratio=(0.86, 1.16),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.09, contrast=0.10, saturation=0.06, hue=0.010),
+            transforms.RandomApply([RandomExposureDown(factor_range=(0.38, 0.96))], p=0.24),
+            transforms.RandomApply([RandomColorTemperature(strength_range=(0.025, 0.13))], p=0.20),
+            transforms.RandomApply([JPEGCompression(quality_range=(60, 96))], p=0.78),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.62, 0.99))], p=0.22),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.08, 0.76))], p=0.12),
+            transforms.RandomApply([RandomMotionBlur(sizes=(3,))], p=0.06),
+            transforms.RandomApply([RandomUnsharpMask()], p=0.10),
+            transforms.ToTensor(),
+            transforms.RandomApply([RandomGamma(gamma_range=(0.76, 1.30))], p=0.28),
+            transforms.RandomApply([HighISONoise(std_range=(0.005, 0.040), chroma_range=(0.002, 0.020))], p=0.20),
+            transforms.RandomApply([RandomProjectorMoire(amplitude_range=(0.003, 0.017))], p=0.06),
+            transforms.RandomApply([GaussianNoise(std_range=(0.002, 0.015))], p=0.14),
+            normalize,
+        ])
+
+    if mode == "train":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.72, 1.0),
+                ratio=(0.80, 1.25),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.16, contrast=0.16, saturation=0.10, hue=0.018),
+            transforms.RandomApply([transforms.RandomGrayscale(p=1.0)], p=0.035),
+            transforms.RandomApply([RandomExposureDown()], p=0.30),
+            transforms.RandomApply([RandomColorTemperature()], p=0.20),
+            transforms.RandomApply([JPEGCompression(quality_range=(40, 95))], p=0.50),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.45, 0.96))], p=0.35),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.08, 1.10))], p=0.22),
+            transforms.RandomApply([RandomMotionBlur()], p=0.10),
+            transforms.RandomApply([RandomUnsharpMask()], p=0.14),
+            transforms.ToTensor(),
+            transforms.RandomApply([RandomShadowCrush()], p=0.12),
+            transforms.RandomApply([RandomGamma()], p=0.14),
+            transforms.RandomApply([HighISONoise()], p=0.26),
+            transforms.RandomApply([RandomProjectorMoire()], p=0.08),
+            transforms.RandomApply([GaussianNoise(std_range=(0.002, 0.020))], p=0.20),
+            normalize,
+        ])
+
+    if mode in ("val", "test"):
+        return transforms.Compose([
+            transforms.Resize(resize_size, interpolation=interpolation, antialias=True),
+            transforms.CenterCrop(image_size),
+            transforms.ToTensor(),
+            normalize,
+        ])
+
+    raise ValueError(f"mode must be train, val, or test; got {mode}")

src/data/dataset.py

@@ -0,0 +1,359 @@
+"""
+A-EYE 데이터셋 로더.
+
+지원하는 폴더 구조 2가지:
+
+[구조 A] flat - 직접 수집한 데이터, random split 사용
+    data/raw/
+        real/   ← 실제 이미지 (label=0)
+        fake/   ← AI 생성 이미지 (label=1)
+
+[구조 B] pre-split - CIFAKE 등 이미 분할된 공개 데이터셋
+    data/raw/
+        train/
+            REAL/  (또는 real/)
+            FAKE/  (또는 fake/)
+        val/
+            REAL/
+            FAKE/
+        test/
+            REAL/
+            FAKE/
+
+라벨 매핑: real / REAL → 0 | fake / FAKE → 1
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import sys
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+from PIL import Image, UnidentifiedImageError
+import torch
+from torch.utils.data import DataLoader, Dataset, WeightedRandomSampler
+
+from .transforms import get_transforms
+
+
+# ──────────────────────────────────────────────
+# DataLoader 워커 자동 감지
+# ──────────────────────────────────────────────
+
+def _auto_workers(requested: int) -> int:
+    """
+    안전한 num_workers 값을 반환한다.
+
+    - requested >= 0: 그대로 반환 (사용자 지정값 존중)
+    - requested < 0:  플랫폼·CUDA 환경을 감지해 자동 결정
+
+    자동 결정 기준:
+        Windows + CUDA : 4  (멀티프로세싱 안정성과 속도 균형)
+        Windows + CPU  : 0  (Windows DataLoader 멀티프로세싱 이슈)
+        Linux/Mac      : min(8, cpu_count // 2)
+    """
+    if requested >= 0:
+        return requested
+
+    is_windows = sys.platform == "win32"
+    has_cuda   = torch.cuda.is_available()
+
+    if is_windows:
+        # Windows 는 spawn 방식 → CPU-only 는 오버헤드 > 이득
+        # CUDA 환경: 4 workers (안정성·속도 균형, 실측 NOT RESPONDING 없음)
+        return 4 if has_cuda else 0
+    else:
+        cpu_count = os.cpu_count() or 1
+        return min(8, max(1, cpu_count // 2))
+
+
+# ──────────────────────────────────────────────
+# 상수
+# ──────────────────────────────────────────────
+
+LABEL_MAP: dict[str, int] = {"real": 0, "fake": 1}
+SUPPORTED_EXTS: set[str] = {".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tiff"}
+
+# 폴더명 → 라벨 (대소문자 무시)
+# "ai" 는 AI 생성 이미지 (fake 와 동일하게 label=1)
+_FOLDER_TO_LABEL: dict[str, int] = {
+    "real": 0, "REAL": 0,
+    "fake": 1, "FAKE": 1,
+    "ai":   1, "AI":   1,
+}
+
+
+# ──────────────────────────────────────────────
+# 내부 유틸: 샘플 수집
+# ──────────────────────────────────────────────
+
+def _scan_class_dirs(root: Path) -> List[Tuple[Path, int]]:
+    """
+    root 하위에서 real/fake (대소문자 무시) 폴더를 찾아
+    (이미지 경로, 라벨) 리스트를 반환한다.
+    """
+    samples: List[Tuple[Path, int]] = []
+    for folder in sorted(root.iterdir()):
+        if not folder.is_dir():
+            continue
+        label = _FOLDER_TO_LABEL.get(folder.name)
+        if label is None:
+            continue
+        imgs = sorted(
+            p for p in folder.iterdir()
+            if p.suffix.lower() in SUPPORTED_EXTS
+        )
+        for p in imgs:
+            samples.append((p, label))
+    return samples
+
+
+def _split_samples(
+    samples: List[Tuple[Path, int]],
+    train_ratio: float,
+    val_ratio: float,
+    seed: int,
+) -> Tuple[List, List, List]:
+    """
+    샘플 리스트를 train / val / test로 분할한다.
+    클래스별로 따로 섞은 뒤 합쳐서 비율을 맞춘다 (간단한 stratified).
+    """
+    rng = random.Random(seed)
+
+    per_class: dict[int, list] = {}
+    for item in samples:
+        per_class.setdefault(item[1], []).append(item)
+    for v in per_class.values():
+        rng.shuffle(v)
+
+    train_all, val_all, test_all = [], [], []
+    for v in per_class.values():
+        n = len(v)
+        n_train = int(n * train_ratio)
+        n_val = int(n * val_ratio)
+        train_all.extend(v[:n_train])
+        val_all.extend(v[n_train:n_train + n_val])
+        test_all.extend(v[n_train + n_val:])
+
+    return train_all, val_all, test_all
+
+
+# ──────────────────────────────────────────────
+# 핵심 Dataset 클래스
+# ──────────────────────────────────────────────
+
+class AEyeDataset(Dataset):
+    """
+    A-EYE 이진 분류 데이터셋.
+
+    samples 리스트를 직접 받아 동작한다. transform은 외부에서 주입한다.
+    build_dataloaders() 또는 from_folder() 팩토리 메서드를 통해 생성하는 것을 권장한다.
+
+    Args:
+        samples:   [(Path, label), ...] 형식의 (이미지 경로, 라벨) 리스트
+        transform: torchvision transform (None이면 PIL Image 그대로 반환)
+        label_map: 라벨 번호 → 클래스명 역매핑 (통계용)
+    """
+
+    def __init__(
+        self,
+        samples: List[Tuple[Path, int]],
+        transform: Optional[Callable] = None,
+        label_map: Optional[dict[int, str]] = None,
+    ):
+        if len(samples) == 0:
+            raise RuntimeError("samples가 비어있습니다. 데이터 경로를 확인하세요.")
+        self.samples = samples
+        self.transform = transform
+        self._label_to_name: dict[int, str] = label_map or {v: k for k, v in LABEL_MAP.items()}
+
+    # ── 팩토리 메서드 ────────────────────────────
+
+    @classmethod
+    def from_folder(
+        cls,
+        root_dir: str | Path,
+        transform: Optional[Callable] = None,
+    ) -> "AEyeDataset":
+        """
+        단일 폴더(real/, fake/)에서 데이터셋을 생성한다. (구조 A)
+        """
+        samples = _scan_class_dirs(Path(root_dir))
+        return cls(samples, transform)
+
+    # ── Dataset 인터페이스 ──────────────────────
+
+    def __len__(self) -> int:
+        return len(self.samples)
+
+    def __getitem__(self, idx: int) -> Tuple[torch.Tensor, int]:
+        filepath, label = self.samples[idx]
+        try:
+            image = Image.open(filepath).convert("RGB")
+        except (UnidentifiedImageError, OSError) as e:
+            # TODO: 손상 이미지 발생 시 인근 샘플로 대체하는 전략 결정
+            raise RuntimeError(f"이미지 로드 실패: {filepath}") from e
+
+        if self.transform is not None:
+            image = self.transform(image)
+
+        return image, label
+
+    # ── 통계 ─────────────────────────────────────
+
+    def class_counts(self) -> dict[str, int]:
+        """클래스별 샘플 수 반환 (클래스 불균형 확인용)."""
+        counts: dict[str, int] = {name: 0 for name in LABEL_MAP}
+        for _, label in self.samples:
+            counts[self._label_to_name[label]] += 1
+        return counts
+
+    def summary(self, tag: str = "") -> str:
+        counts = self.class_counts()
+        total = len(self)
+        prefix = f"[{tag}] " if tag else ""
+        lines = [
+            f"{prefix}총 {total}장",
+            f"  real(0): {counts['real']}장",
+            f"  fake(1): {counts['fake']}장",
+        ]
+        imbalance = counts["real"] / max(counts["fake"], 1)
+        if not (0.5 <= imbalance <= 2.0):
+            lines.append(f"  ** 클래스 불균형 주의 (real/fake = {imbalance:.2f})")
+        return "\n".join(lines)
+
+
+# ──────────────────────────────────────────────
+# DataLoader 빌더
+# ──────────────────────────────────────────────
+
+def build_dataloaders(
+    root_dir: str,
+    image_size: int = 224,
+    batch_size: int = 32,
+    num_workers: int = -1,
+    pin_memory: Optional[bool] = None,
+    persistent_workers: Optional[bool] = None,
+    prefetch_factor: Optional[int] = None,
+    train_ratio: float = 0.7,
+    val_ratio: float = 0.15,
+    seed: int = 42,
+    mean: Optional[list] = None,
+    std: Optional[list] = None,
+    balanced_sampler: bool = False,
+) -> Tuple[DataLoader, DataLoader, DataLoader]:
+    """
+    데이터 로더를 생성하고 반환한다.
+
+    폴더 구조를 자동 감지:
+      - 구조 B (pre-split): root_dir/train/, root_dir/val/, root_dir/test/ 가 있으면 사용
+      - 구조 A (flat):      root_dir/real/, root_dir/fake/ 에서 직접 split
+
+    Args:
+        root_dir:    데이터 루트 경로
+        image_size:  리사이즈 크기
+        batch_size:  배치 크기
+        num_workers: 워커 수. -1이면 플랫폼·CUDA 환경에 따라 자동 결정
+                     (Windows+CUDA=4, Windows+CPU=0, Linux=min(8, cpu//2))
+        pin_memory:  None이면 CUDA 유무에 따라 자동 결정
+        persistent_workers: epoch 사이에 worker 프로세스를 유지할지 여부
+        prefetch_factor: worker당 미리 준비할 batch 수 (None → 기본값 2)
+        train_ratio: flat 구조일 때 train 비율
+        val_ratio:   flat 구조일 때 val 비율
+        seed:        재현성 시드
+        mean / std:  정규화 파라미터
+
+    Returns:
+        (train_loader, val_loader, test_loader)
+    """
+    # ── 리소스 자동 결정 ──���─────────────────────
+    num_workers = _auto_workers(num_workers)
+    if pin_memory is None:
+        pin_memory = torch.cuda.is_available()
+    root = Path(root_dir)
+
+    train_transform = get_transforms("train", image_size, mean, std)
+    eval_transform = get_transforms("val", image_size, mean, std)
+
+    # ── 구조 B: pre-split ─────────────────────
+    if (root / "train").exists() and (root / "test").exists():
+        train_samples = _scan_class_dirs(root / "train")
+        test_samples = _scan_class_dirs(root / "test")
+
+        # val 폴더가 없으면 test에서 절반 분리
+        if (root / "val").exists():
+            val_samples = _scan_class_dirs(root / "val")
+        else:
+            mid = len(test_samples) // 2
+            val_samples = test_samples[:mid]
+            test_samples = test_samples[mid:]
+
+        train_ds = AEyeDataset(train_samples, train_transform)
+        val_ds = AEyeDataset(val_samples, eval_transform)
+        test_ds = AEyeDataset(test_samples, eval_transform)
+        mode = "pre-split"
+
+    # ── 구조 A: flat + random split ───────────
+    else:
+        all_samples = _scan_class_dirs(root)
+        if len(all_samples) == 0:
+            raise RuntimeError(
+                f"이미지를 찾을 수 없습니다: {root}\n"
+                "  구조 A: root/real/, root/fake/\n"
+                "  구조 B: root/train/REAL/, root/test/FAKE/ 등"
+            )
+        train_samples, val_samples, test_samples = _split_samples(
+            all_samples, train_ratio, val_ratio, seed
+        )
+        train_ds = AEyeDataset(train_samples, train_transform)
+        val_ds = AEyeDataset(val_samples, eval_transform)
+        test_ds = AEyeDataset(test_samples, eval_transform)
+        mode = "flat+split"
+
+    # ── 출력 ──────────────────────────────────
+    _pw = persistent_workers if persistent_workers is not None else (True if num_workers > 0 else False)
+    _pf = prefetch_factor if prefetch_factor is not None else (2 if num_workers > 0 else None)
+    print(f"[DataLoader] 구조: {mode}")
+    print(f"[DataLoader] workers={num_workers}  pin_memory={pin_memory}  "
+          f"persistent_workers={_pw}  prefetch_factor={_pf}  batch={batch_size}")
+    print(train_ds.summary("train"))
+    print(val_ds.summary("val"))
+    print(test_ds.summary("test"))
+
+    def _make(ds: AEyeDataset, shuffle: bool, balanced: bool = False) -> DataLoader:
+        loader_kwargs: dict = dict(
+            batch_size=batch_size,
+            num_workers=num_workers,
+            pin_memory=pin_memory,
+        )
+        if balanced:
+            counts: dict[int, int] = {}
+            for _, label in ds.samples:
+                counts[label] = counts.get(label, 0) + 1
+            sample_weights = torch.DoubleTensor([
+                1.0 / counts[label] for _, label in ds.samples
+            ])
+            loader_kwargs["sampler"] = WeightedRandomSampler(
+                sample_weights,
+                num_samples=len(sample_weights),
+                replacement=True,
+            )
+            print("[DataLoader] balanced_sampler=True")
+        else:
+            loader_kwargs["shuffle"] = shuffle
+        if num_workers > 0:
+            loader_kwargs["persistent_workers"] = (
+                persistent_workers if persistent_workers is not None else True
+            )
+            loader_kwargs["prefetch_factor"] = (
+                prefetch_factor if prefetch_factor is not None else 2
+            )
+        return DataLoader(ds, **loader_kwargs)
+
+    return (
+        _make(train_ds, shuffle=True, balanced=balanced_sampler),
+        _make(val_ds, shuffle=False),
+        _make(test_ds, shuffle=False),
+    )

src/data/transforms.py

@@ -0,0 +1,109 @@
+"""Image preprocessing and augmentation for real/fake classification."""
+
+from __future__ import annotations
+
+import io
+import random
+
+import torch
+from PIL import Image
+from torchvision import transforms
+from torchvision.transforms import InterpolationMode
+
+
+IMAGENET_MEAN = [0.485, 0.456, 0.406]
+IMAGENET_STD = [0.229, 0.224, 0.225]
+
+CLIP_MEAN = [0.48145466, 0.4578275, 0.40821073]
+CLIP_STD = [0.26862954, 0.26130258, 0.27577711]
+
+_NORM_PRESETS: dict[str, tuple[list[float], list[float]]] = {
+    "imagenet": (IMAGENET_MEAN, IMAGENET_STD),
+    "clip": (CLIP_MEAN, CLIP_STD),
+}
+
+
+class JPEGCompression:
+    """Random JPEG round-trip augmentation."""
+
+    def __init__(self, quality_range: tuple[int, int] = (70, 100)):
+        self.quality_range = quality_range
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        quality = random.randint(*self.quality_range)
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=quality)
+        buf.seek(0)
+        return Image.open(buf).copy()
+
+
+class DownsampleUpsample:
+    """Resolution loss augmentation that preserves the original canvas size."""
+
+    def __init__(self, scale_range: tuple[float, float] = (0.65, 0.95)):
+        self.scale_range = scale_range
+
+    def __call__(self, img: Image.Image) -> Image.Image:
+        w, h = img.size
+        scale = random.uniform(*self.scale_range)
+        small_w = max(1, int(w * scale))
+        small_h = max(1, int(h * scale))
+        small = img.resize((small_w, small_h), Image.Resampling.BILINEAR)
+        return small.resize((w, h), Image.Resampling.BILINEAR)
+
+
+class GaussianNoise:
+    """Small sensor-like noise on tensor images in [0, 1]."""
+
+    def __init__(self, std_range: tuple[float, float] = (0.003, 0.015)):
+        self.std_range = std_range
+
+    def __call__(self, tensor: torch.Tensor) -> torch.Tensor:
+        std = random.uniform(*self.std_range)
+        return torch.clamp(tensor + torch.randn_like(tensor) * std, 0.0, 1.0)
+
+
+def get_transforms(
+    mode: str,
+    image_size: int = 224,
+    mean: list | None = None,
+    std: list | None = None,
+    norm_preset: str = "imagenet",
+) -> transforms.Compose:
+    if mean is None or std is None:
+        preset_mean, preset_std = _NORM_PRESETS.get(norm_preset, (IMAGENET_MEAN, IMAGENET_STD))
+        mean = mean or preset_mean
+        std = std or preset_std
+
+    normalize = transforms.Normalize(mean=mean, std=std)
+    resize_size = int(round(image_size / 0.875))
+    interpolation = InterpolationMode.BICUBIC
+
+    if mode == "train":
+        return transforms.Compose([
+            transforms.RandomResizedCrop(
+                image_size,
+                scale=(0.80, 1.0),
+                ratio=(0.85, 1.18),
+                interpolation=interpolation,
+                antialias=True,
+            ),
+            transforms.RandomHorizontalFlip(p=0.5),
+            transforms.ColorJitter(brightness=0.12, contrast=0.12, saturation=0.08, hue=0.02),
+            transforms.RandomApply([JPEGCompression(quality_range=(70, 100))], p=0.35),
+            transforms.RandomApply([DownsampleUpsample(scale_range=(0.65, 0.95))], p=0.15),
+            transforms.RandomApply([transforms.GaussianBlur(kernel_size=3, sigma=(0.1, 0.8))], p=0.15),
+            transforms.ToTensor(),
+            transforms.RandomApply([GaussianNoise(std_range=(0.003, 0.015))], p=0.15),
+            normalize,
+        ])
+
+    if mode in ("val", "test"):
+        return transforms.Compose([
+            transforms.Resize(resize_size, interpolation=interpolation, antialias=True),
+            transforms.CenterCrop(image_size),
+            transforms.ToTensor(),
+            normalize,
+        ])
+
+    raise ValueError(f"mode must be one of 'train', 'val', or 'test', got '{mode}'")

src/inference/__init__.py

@@ -0,0 +1 @@
+# TODO: 추론 파이프라인 구현 완료 후 export 추가

src/models/__init__.py

@@ -0,0 +1,5 @@
+from .vit_classifier import ViTClassifier, AVAILABLE_BACKBONES
+from .clip_classifier import CLIPClassifier, AVAILABLE_CLIP_BACKBONES, DEFAULT_PROMPTS
+from .hybrid import HybridClassifier
+from .artifact_hybrid import ArtifactAwareLoRAHybridClassifier
+from .factory import build_model

src/models/artifact_gated_hybrid.py

@@ -0,0 +1,143 @@
+"""Gated artifact-aware ViT + CLIP + LoRA classifier.
+
+This variant keeps the exp26 backbone names intact for partial checkpoint
+loading, then adds branch gates and auxiliary branch heads. The gate helps the
+model reduce over-reliance on FFT/SRM when real low-light noise looks synthetic.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from .artifact_hybrid import ArtifactAwareLoRAHybridClassifier, _build_deep_head
+
+
+class ArtifactAwareGatedLoRAHybridClassifier(ArtifactAwareLoRAHybridClassifier):
+    """Artifact hybrid with learnable branch reliability gates."""
+
+    def __init__(
+        self,
+        gate_dim: int = 384,
+        gate_dropout: float = 0.12,
+        gate_semantic_only: bool = False,
+        gate_init_bias_semantic: float | None = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.gate_dim = gate_dim
+        self.gate_semantic_only = bool(gate_semantic_only)
+        self.gate_init_bias_semantic = gate_init_bias_semantic
+        branch_dims = {
+            "vit": self.vit_dim,
+            "clip": self.clip_dim,
+            "fft": self.fft_dim,
+            "srm": self.srm_dim,
+        }
+        gate_input_dim = (
+            branch_dims["vit"] + branch_dims["clip"]
+            if self.gate_semantic_only
+            else sum(branch_dims.values())
+        )
+        self.branch_order = ("vit", "clip", "fft", "srm")
+        self.branch_proj = nn.ModuleDict({
+            name: nn.Sequential(
+                nn.LayerNorm(dim),
+                nn.Linear(dim, gate_dim),
+                nn.GELU(),
+                nn.Dropout(p=gate_dropout),
+            )
+            for name, dim in branch_dims.items()
+        })
+        self.gate_net = nn.Sequential(
+            nn.LayerNorm(gate_input_dim),
+            nn.Linear(gate_input_dim, 256),
+            nn.GELU(),
+            nn.Dropout(p=gate_dropout),
+            nn.Linear(256, len(self.branch_order)),
+        )
+        self.aux_heads = nn.ModuleDict({
+            name: nn.Sequential(
+                nn.LayerNorm(dim),
+                nn.Dropout(p=gate_dropout),
+                nn.Linear(dim, self.num_classes),
+            )
+            for name, dim in branch_dims.items()
+        })
+        fused_dim = gate_dim * len(self.branch_order) + len(self.branch_order)
+        self.head = _build_deep_head(fused_dim, self.num_classes, kwargs.get("dropout", 0.3))
+        self.fused_dim = fused_dim
+        self._init_new_layers()
+
+    def _init_new_layers(self) -> None:
+        for module in (self.branch_proj, self.gate_net, self.aux_heads):
+            for layer in module.modules():
+                if isinstance(layer, nn.Linear):
+                    nn.init.trunc_normal_(layer.weight, std=0.02)
+                    if layer.bias is not None:
+                        nn.init.zeros_(layer.bias)
+        if self.gate_init_bias_semantic is not None:
+            gate_final = self.gate_net[-1]
+            if isinstance(gate_final, nn.Linear) and gate_final.bias is not None:
+                bias = torch.empty_like(gate_final.bias)
+                value = float(self.gate_init_bias_semantic)
+                for idx, name in enumerate(self.branch_order):
+                    bias[idx] = value if name in ("vit", "clip") else -value
+                with torch.no_grad():
+                    gate_final.bias.copy_(bias)
+
+    def _branch_features(self, x: torch.Tensor) -> dict[str, torch.Tensor]:
+        vit_feat = self.vit_encoder.forward_features(x)
+        clip_feat = self.clip_encoder.forward_features(x)
+        raw = self._to_raw_rgb(x)
+        fft_feat = self.fft_branch(raw)
+        srm_feat = self.srm_branch(x)
+        return {
+            "vit": vit_feat,
+            "clip": clip_feat,
+            "fft": fft_feat,
+            "srm": srm_feat,
+        }
+
+    def _gated_features(
+        self,
+        branches: dict[str, torch.Tensor],
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        if self.gate_semantic_only:
+            gate_input = torch.cat([branches["vit"], branches["clip"]], dim=-1)
+        else:
+            gate_input = torch.cat([branches[name] for name in self.branch_order], dim=-1)
+        gates = torch.softmax(self.gate_net(gate_input), dim=-1)
+        projected = []
+        for idx, name in enumerate(self.branch_order):
+            projected.append(self.branch_proj[name](branches[name]) * gates[:, idx : idx + 1])
+        return torch.cat([*projected, gates], dim=-1), gates
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        branches = self._branch_features(x)
+        fused, _ = self._gated_features(branches)
+        return fused
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.forward_features(x))
+
+    def forward_with_aux(self, x: torch.Tensor) -> dict[str, torch.Tensor | dict[str, torch.Tensor]]:
+        branches = self._branch_features(x)
+        fused, gates = self._gated_features(branches)
+        aux_logits = {name: self.aux_heads[name](branches[name]) for name in self.branch_order}
+        return {
+            "logits": self.head(fused),
+            "aux_logits": aux_logits,
+            "gates": gates,
+        }
+
+    def param_summary(self) -> str:
+        total = sum(p.numel() for p in self.parameters())
+        trainable = sum(p.numel() for p in self.parameters() if p.requires_grad)
+        return (
+            f"[ArtifactGatedLoRAHybrid: {self.vit_backbone_name} + {self.clip_backbone_name} "
+            f"r={self.lora_r} alpha={self.lora_alpha} gate_dim={self.gate_dim} "
+            f"gate={'semantic' if self.gate_semantic_only else 'all'} "
+            f"gate_bias={self.gate_init_bias_semantic}] "
+            f"total={total:,} trainable={trainable:,} ({100 * trainable / total:.2f}%)"
+        )

src/models/artifact_hybrid.py

@@ -0,0 +1,151 @@
+"""Artifact-aware ViT + CLIP + LoRA classifier.
+
+This model keeps the proven experiment-17 backbone, then adds lightweight
+forensic branches for frequency and high-pass residual evidence.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from .fft_branch import FFTBranch
+from .lora_hybrid import LoRAHybridClassifier
+from .srm_branch import CLIP_MEAN, CLIP_STD, SRMBranch
+
+
+def _build_deep_head(in_dim: int, num_classes: int, dropout: float) -> nn.Sequential:
+    hidden = max(512, in_dim // 2)
+    bottleneck = max(256, hidden // 2)
+    head = nn.Sequential(
+        nn.LayerNorm(in_dim),
+        nn.Linear(in_dim, hidden),
+        nn.GELU(),
+        nn.Dropout(p=dropout),
+        nn.Linear(hidden, bottleneck),
+        nn.GELU(),
+        nn.Dropout(p=dropout * 0.75),
+        nn.Linear(bottleneck, num_classes),
+    )
+    for module in head:
+        if isinstance(module, nn.Linear):
+            nn.init.trunc_normal_(module.weight, std=0.02)
+            if module.bias is not None:
+                nn.init.zeros_(module.bias)
+    return head
+
+
+class ArtifactAwareLoRAHybridClassifier(LoRAHybridClassifier):
+    """ViT+CLIP LoRA fused with raw-FFT and SRM residual branches."""
+
+    def __init__(
+        self,
+        fft_dim: int = 256,
+        fft_dropout: float = 0.1,
+        srm_dim: int = 128,
+        srm_dropout: float = 0.1,
+        lora_r: int = 32,
+        lora_alpha: int = 64,
+        lora_dropout: float = 0.1,
+        lora_vit: bool = True,
+        vit_backbone: str = "vit_b_16",
+        clip_backbone: str = "clip-vit-b-32",
+        fusion: str = "concat",
+        num_classes: int = 2,
+        freeze_vit: bool = True,
+        freeze_clip: bool = True,
+        vit_pretrained: bool = True,
+        dropout: float = 0.3,
+    ):
+        super().__init__(
+            lora_r=lora_r,
+            lora_alpha=lora_alpha,
+            lora_dropout=lora_dropout,
+            lora_vit=lora_vit,
+            vit_backbone=vit_backbone,
+            clip_backbone=clip_backbone,
+            fusion=fusion,
+            num_classes=num_classes,
+            freeze_vit=freeze_vit,
+            freeze_clip=freeze_clip,
+            vit_pretrained=vit_pretrained,
+            dropout=dropout,
+        )
+
+        self.fft_dim = fft_dim
+        self.srm_dim = srm_dim
+        self.register_buffer("clip_mean", torch.tensor(CLIP_MEAN).view(1, 3, 1, 1))
+        self.register_buffer("clip_std", torch.tensor(CLIP_STD).view(1, 3, 1, 1))
+
+        self.fft_branch = FFTBranch(out_dim=fft_dim, dropout=fft_dropout)
+        self.srm_branch = SRMBranch(out_dim=srm_dim, dropout=srm_dropout)
+
+        fused_dim = self.fused_dim + fft_dim + srm_dim
+        self.head = _build_deep_head(fused_dim, num_classes, dropout)
+        self.fused_dim = fused_dim
+
+    def _to_raw_rgb(self, x: torch.Tensor) -> torch.Tensor:
+        return (x * self.clip_std + self.clip_mean).clamp(0.0, 1.0)
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        vit_feat = self.vit_encoder.forward_features(x)
+        clip_feat = self.clip_encoder.forward_features(x)
+        raw = self._to_raw_rgb(x)
+        fft_feat = self.fft_branch(raw)
+        srm_feat = self.srm_branch(x)
+        return torch.cat([vit_feat, clip_feat, fft_feat, srm_feat], dim=-1)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.forward_features(x))
+
+    def freeze_lora(self) -> None:
+        for name, param in self.named_parameters():
+            if "lora_" in name:
+                param.requires_grad_(False)
+        for module in (self.fft_branch, self.srm_branch, self.head):
+            for param in module.parameters():
+                param.requires_grad_(True)
+
+    def unfreeze_lora(self) -> None:
+        for name, param in self.named_parameters():
+            if "lora_" in name:
+                param.requires_grad_(True)
+
+    def load_partial_checkpoint(self, checkpoint_path: str, device: str = "cpu") -> dict:
+        """Load matching 17-style weights and skip new or shape-mismatched layers."""
+        ckpt = torch.load(checkpoint_path, map_location=device, weights_only=True)
+        state = ckpt.get("model_state_dict", ckpt)
+        own_state = self.state_dict()
+
+        loaded, skipped = 0, 0
+        loaded_keys, skipped_keys = [], []
+        for key, value in state.items():
+            if key in own_state and own_state[key].shape == value.shape:
+                own_state[key] = value
+                loaded += 1
+                if len(loaded_keys) < 20:
+                    loaded_keys.append(key)
+            else:
+                skipped += 1
+                if len(skipped_keys) < 20:
+                    skipped_keys.append(key)
+
+        self.load_state_dict(own_state, strict=False)
+        return {
+            "loaded": loaded,
+            "skipped": skipped,
+            "loaded_keys_preview": loaded_keys,
+            "skipped_keys_preview": skipped_keys,
+        }
+
+    def param_summary(self) -> str:
+        total = sum(p.numel() for p in self.parameters())
+        trainable = sum(p.numel() for p in self.parameters() if p.requires_grad)
+        srm_params = sum(p.numel() for p in self.srm_branch.parameters())
+        fft_params = sum(p.numel() for p in self.fft_branch.parameters())
+        return (
+            f"[ArtifactLoRAHybrid: {self.vit_backbone_name} + {self.clip_backbone_name} "
+            f"r={self.lora_r} alpha={self.lora_alpha}] "
+            f"total={total:,} trainable={trainable:,} ({100 * trainable / total:.2f}%) "
+            f"fft={fft_params:,} srm={srm_params:,}"
+        )

src/models/clip_classifier.py

@@ -0,0 +1,403 @@
+"""
+CLIP 기반 real/fake 이진 분류기.
+
+지원 모드:
+    zeroshot  텍스트 프롬프트와 코사인 유사도만으로 분류 (학습 불필요)
+    linear    CLIP vision encoder 동결, 선형 헤드만 학습
+    finetune  vision encoder + 선형 헤드 전체 fine-tuning
+
+지원 백본:
+    clip-vit-b-32  openai/clip-vit-base-patch32   embed_dim=512
+    clip-vit-b-16  openai/clip-vit-base-patch16   embed_dim=512
+    clip-vit-l-14  openai/clip-vit-large-patch14  embed_dim=768
+
+설계 원칙:
+    - forward_features(x) 가 (B, embed_dim) L2-정규화 벡터를 반환
+      → Hybrid 모델에서 ViT 특징과 바로 결합 가능
+    - forward(x) 가 logits (B, num_classes) 를 반환
+      → 기존 Trainer, CrossEntropyLoss 와 완전 호환
+    - image_only=True 시 text encoder/tokenizer 초기화 생략
+      → HybridClassifier 에서 불필요한 비용 제거
+
+오프라인 사용:
+    캐시 우선 로딩: 로컬 캐시가 있으면 네트워크 없이 즉시 로드.
+    환경 변수 HF_HUB_OFFLINE=1 또는 TRANSFORMERS_OFFLINE=1 로
+    오프라인 전용 모드 강제 가능.
+
+텍스트 임베딩은 __init__ 시점에 1회 계산 후 buffer로 등록됨.
+학습 중에는 이미지만 인코딩하므로 overhead 없음.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+logger = logging.getLogger(__name__)
+
+# transformers 없이도 import 는 허용
+try:
+    from transformers import (
+        CLIPVisionModelWithProjection,
+        CLIPVisionConfig,
+        CLIPTextModelWithProjection,
+        CLIPTokenizer,
+    )
+    _TRANSFORMERS_AVAILABLE = True
+except ImportError:
+    _TRANSFORMERS_AVAILABLE = False
+
+
+# ──────────────────────────────────────────────
+# 오프라인 친화적 로드 헬퍼
+# ──────────────────────────────────────────────
+
+def _is_offline_mode() -> bool:
+    """HF_HUB_OFFLINE 또는 TRANSFORMERS_OFFLINE 환경변수가 설정됐는지 확인."""
+    return (
+        os.environ.get("HF_HUB_OFFLINE", "0") == "1"
+        or os.environ.get("TRANSFORMERS_OFFLINE", "0") == "1"
+    )
+
+
+def _load_pretrained(cls, hf_name: str, **kwargs):
+    """
+    캐시 우선 로딩 전략 — 불필요한 네트워크 요청 없이 동작.
+
+    전략:
+        1차: 로컬 캐시 시도 (local_files_only=True) → 캐시 있으면 즉시 반환
+        2차: 캐시 없고 오프라인 모드면 → 명확한 에러
+        3차: 캐시 없고 온라인이면 → 다운로드 시도
+
+    오프라인 강제:
+        HF_HUB_OFFLINE=1 또는 TRANSFORMERS_OFFLINE=1 설정 시
+        2차(다운로드)를 건너뛰고 즉시 에러 발생.
+
+    Args:
+        cls:     transformers 모델/토크나이저 클래스
+        hf_name: HuggingFace 모델 ID
+        kwargs:  from_pretrained 에 전달할 추가 인자
+    """
+    # 1차: 로컬 캐시 우선 시도
+    try:
+        return cls.from_pretrained(hf_name, local_files_only=True, **kwargs)
+    except Exception:
+        pass  # 캐시 없음 → 2/3차로 진행
+
+    # 오프라인 모드이면 다운로드 없이 실패
+    if _is_offline_mode():
+        raise RuntimeError(
+            f"오프라인 모드에서 '{hf_name}' 캐시를 찾을 수 없습니다.\n"
+            f"  해결: 네트워크 연결 후 한 번 실행해서 캐시를 만드세요:\n"
+            f"    python -c \"from transformers import {cls.__name__}; "
+            f"{cls.__name__}.from_pretrained('{hf_name}')\""
+        )
+
+    # 2차: 다운로드 시도
+    try:
+        return cls.from_pretrained(hf_name, **kwargs)
+    except Exception as e:
+        raise RuntimeError(
+            f"'{hf_name}' 로드 실패 (캐시 없음 + 다운로드 실패).\n"
+            f"  원인: {e}\n"
+            f"  해결: 네트워크 연결 상태를 확인하거나,\n"
+            f"    TRANSFORMERS_OFFLINE=1 설정 후 캐시 경로를 확인하세요."
+        ) from e
+
+
+def _build_random_clip_vision(hf_name: str) -> nn.Module:
+    """Build the CLIP vision architecture without downloading base weights."""
+    if hf_name == "openai/clip-vit-base-patch32":
+        config = CLIPVisionConfig(
+            hidden_size=768,
+            intermediate_size=3072,
+            projection_dim=512,
+            num_hidden_layers=12,
+            num_attention_heads=12,
+            image_size=224,
+            patch_size=32,
+        )
+    elif hf_name == "openai/clip-vit-base-patch16":
+        config = CLIPVisionConfig(
+            hidden_size=768,
+            intermediate_size=3072,
+            projection_dim=512,
+            num_hidden_layers=12,
+            num_attention_heads=12,
+            image_size=224,
+            patch_size=16,
+        )
+    elif hf_name == "openai/clip-vit-large-patch14":
+        config = CLIPVisionConfig(
+            hidden_size=1024,
+            intermediate_size=4096,
+            projection_dim=768,
+            num_hidden_layers=24,
+            num_attention_heads=16,
+            image_size=224,
+            patch_size=14,
+        )
+    else:
+        raise ValueError(f"Unsupported CLIP backbone for random init: {hf_name}")
+    return CLIPVisionModelWithProjection(config)
+
+
+# ──────────────────────────────────────────────
+# 백본 레지스트리
+# ──────────────────────────────────────────────
+
+@dataclass
+class _CLIPSpec:
+    hf_name:   str   # HuggingFace 모델 ID
+    embed_dim: int   # projection_dim (최종 임베딩 차원)
+
+
+_CLIP_REGISTRY: Dict[str, _CLIPSpec] = {
+    "clip-vit-b-32": _CLIPSpec("openai/clip-vit-base-patch32",  512),
+    "clip-vit-b-16": _CLIPSpec("openai/clip-vit-base-patch16",  512),
+    "clip-vit-l-14": _CLIPSpec("openai/clip-vit-large-patch14", 768),
+}
+
+AVAILABLE_CLIP_BACKBONES = list(_CLIP_REGISTRY.keys())
+
+# ──────────────────────────────────────────────
+# 기본 텍스트 프롬프트
+# ──────────────────────────────────────────────
+# label 0 = real, label 1 = fake
+# 클래스당 여러 프롬프트를 평균해 더 안정적인 임베딩을 얻는다.
+
+DEFAULT_PROMPTS: Dict[int, List[str]] = {
+    0: [
+        "a real photograph",
+        "a genuine photo taken by a camera",
+        "a real image captured by a human",
+    ],
+    1: [
+        "an AI-generated image",
+        "a fake image created by artificial intelligence",
+        "a synthetic image generated by a neural network",
+    ],
+}
+
+
+# ──────────────────────────────────────────────
+# 분류기
+# ──────────────────────────────────────────────
+
+class CLIPClassifier(nn.Module):
+    """
+    CLIP 기반 real/fake 이진 분류기.
+
+    Args:
+        backbone_name:  백본 키 (clip-vit-b-32 | clip-vit-b-16 | clip-vit-l-14)
+        mode:           분류 방식 (zeroshot | linear | finetune)
+        num_classes:    출력 클래스 수 (기본 2)
+        prompts:        {label_int: [str, ...]} 프롬프트 딕셔너리
+                        None이면 DEFAULT_PROMPTS 사용
+        dropout:        linear / finetune 헤드 dropout 비율
+        temperature:    zeroshot 코사인 유사도 스케일 (CLIP logit_scale 사용 권장)
+        image_only:     True 면 text encoder / tokenizer / text_embeddings 초기화 생략.
+                        HybridClassifier 등 image feature 만 필요한 경우에 사용.
+                        zeroshot 모드와 함께 쓸 수 없음.
+    """
+
+    VALID_MODES = ("zeroshot", "linear", "finetune")
+
+    def __init__(
+        self,
+        backbone_name: str = "clip-vit-b-32",
+        mode: str = "linear",
+        num_classes: int = 2,
+        prompts: Optional[Dict[int, List[str]]] = None,
+        dropout: float = 0.1,
+        temperature: float = 1.0,
+        image_only: bool = False,
+    ):
+        super().__init__()
+
+        if not _TRANSFORMERS_AVAILABLE:
+            raise ImportError(
+                "CLIP 모델은 transformers 라이브러리가 필요합니다.\n"
+                "  pip install transformers"
+            )
+
+        if backbone_name not in _CLIP_REGISTRY:
+            raise ValueError(
+                f"지원하지 않는 CLIP 백본: '{backbone_name}'\n"
+                f"사용 가능: {AVAILABLE_CLIP_BACKBONES}"
+            )
+        if mode not in self.VALID_MODES:
+            raise ValueError(
+                f"지원하지 않는 mode: '{mode}'\n"
+                f"사용 가능: {self.VALID_MODES}"
+            )
+        if image_only and mode == "zeroshot":
+            raise ValueError(
+                "image_only=True 와 mode='zeroshot' 은 함께 쓸 수 없습니다.\n"
+                "zeroshot 은 text encoder 가 필요합니다."
+            )
+
+        self.backbone_name = backbone_name
+        self.mode = mode
+        self.num_classes = num_classes
+        self.temperature = temperature
+        self.image_only = image_only
+
+        spec = _CLIP_REGISTRY[backbone_name]
+        self.embed_dim = spec.embed_dim
+        hf_name = spec.hf_name
+
+        # ── Vision encoder ───────────────────────
+        if os.environ.get("A_EYE_RANDOM_INIT_BACKBONES", "").strip().lower() in {"1", "true", "yes"}:
+            self.vision_model = _build_random_clip_vision(hf_name)
+        else:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                self.vision_model = _load_pretrained(CLIPVisionModelWithProjection, hf_name)
+
+        if mode in ("zeroshot", "linear"):
+            # vision encoder 파라미터 동결
+            for param in self.vision_model.parameters():
+                param.requires_grad = False
+
+        # ── Text encoder + 프롬프트 임베딩 사전계산 ──
+        # image_only=True 면 text branch 전체를 건너뜀 (Hybrid 전용 경로)
+        if not image_only:
+            self._prompts: Dict[int, List[str]] = prompts or DEFAULT_PROMPTS
+            self._register_text_embeddings(hf_name, num_classes)
+        else:
+            self._prompts = {}
+
+        # ── 분류 헤드 (linear / finetune 에만 사용) ──
+        if mode in ("linear", "finetune"):
+            self.head = nn.Sequential(
+                nn.LayerNorm(self.embed_dim),
+                nn.Dropout(p=dropout),
+                nn.Linear(self.embed_dim, num_classes),
+            )
+            nn.init.trunc_normal_(self.head[-1].weight, std=0.02)
+            nn.init.zeros_(self.head[-1].bias)
+        else:
+            self.head = None  # zeroshot은 head 없음
+
+    # ──────────────────────────────────────────
+    # 텍스트 임베딩 사전계산
+    # ──────────────────────────────────────────
+
+    @torch.no_grad()
+    def _register_text_embeddings(self, hf_name: str, num_classes: int):
+        """
+        각 클래스의 프롬프트를 인코딩하고 buffer로 등록.
+        device 이동 시 자동으로 따라온다.
+        프롬프트가 여럿이면 평균을 L2 정규화해 사용한다.
+        """
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            text_model = _load_pretrained(CLIPTextModelWithProjection, hf_name)
+            tokenizer  = _load_pretrained(CLIPTokenizer, hf_name)
+        text_model.eval()
+
+        class_embeds = []
+        for label in range(num_classes):
+            label_prompts = self._prompts.get(label, [f"class {label}"])
+            tokens = tokenizer(
+                label_prompts,
+                return_tensors="pt",
+                padding=True,
+                truncation=True,
+                max_length=77,
+            )
+            text_out = text_model(**tokens)
+            # (num_prompts, embed_dim) → 평균 → (embed_dim,)
+            embeds = text_out.text_embeds          # (P, D)
+            embeds = F.normalize(embeds, dim=-1)   # 정규화
+            embed  = embeds.mean(dim=0)            # 프롬프트 앙상블
+            embed  = F.normalize(embed, dim=-1)    # 재정규화
+            class_embeds.append(embed)
+
+        # (num_classes, embed_dim)
+        text_matrix = torch.stack(class_embeds, dim=0)
+        # buffer: 학습 파라미터는 아니지만 state_dict에 저장되고 device 이동도 자동
+        self.register_buffer("text_embeddings", text_matrix)
+
+        del text_model, tokenizer
+
+    # ──────────────────────────────────────────
+    # Forward
+    # ──────────────────────────────────────────
+
+    def encode_image(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        이미지 배치 → L2 정규화된 이미지 임베딩 (B, embed_dim).
+
+        Hybrid 모델에서 이 메서드를 직접 호출해 특징벡터를 사용한다.
+        """
+        vision_out = self.vision_model(pixel_values=x)
+        embeds = vision_out.image_embeds           # (B, embed_dim)
+        return F.normalize(embeds, dim=-1)
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """encode_image 의 별칭. ViTClassifier 와 인터페이스 통일."""
+        return self.encode_image(x)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Returns:
+            logits (B, num_classes)
+              zeroshot: 코사인 유사도 기반 logit
+              linear/finetune: 선형 헤드 출력
+        """
+        img_embeds = self.encode_image(x)   # (B, D), L2-normalized
+
+        if self.mode == "zeroshot":
+            # image_only=True 로 생성한 경우 text_embeddings 없음
+            if self.image_only or not hasattr(self, "text_embeddings"):
+                raise RuntimeError(
+                    "image_only=True 로 초기화된 CLIPClassifier 는 "
+                    "zeroshot forward 를 지원하지 않습니다."
+                )
+            logits = (img_embeds @ self.text_embeddings.T) / self.temperature
+            return logits
+
+        # linear / finetune
+        return self.head(img_embeds)
+
+    @torch.no_grad()
+    def predict_proba(self, x: torch.Tensor) -> torch.Tensor:
+        """Softmax 확률 (B, num_classes). 추론 전용."""
+        self.eval()
+        return torch.softmax(self(x), dim=-1)
+
+    # ──────────────────────────────────────────
+    # 유틸
+    # ──────────────────────────────────────────
+
+    def trainable_params(self) -> int:
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)
+
+    def total_params(self) -> int:
+        return sum(p.numel() for p in self.parameters())
+
+    def param_summary(self) -> str:
+        trainable = self.trainable_params()
+        total = self.total_params()
+        return (
+            f"[{self.backbone_name} / {self.mode}] "
+            f"전체 {total:,} | 학습 가능 {trainable:,} "
+            f"({100 * trainable / total:.1f}%)"
+        )
+
+    def get_prompt_summary(self) -> str:
+        """등록된 프롬프트를 출력한다."""
+        lines = ["[등록된 프롬프트]"]
+        for label, prm_list in self._prompts.items():
+            for p in prm_list:
+                lines.append(f"  label={label}: '{p}'")
+        return "\n".join(lines)

src/models/factory.py

@@ -0,0 +1,187 @@
+"""
+config 기반 모델 팩토리.
+
+사용:
+    with open("configs/config.yaml") as f:
+        cfg = yaml.safe_load(f)
+    model = build_model(cfg)
+
+config.yaml 예시:
+    model:
+      type: "vit"
+      backbone: "vit_b_16"
+      num_classes: 2
+      pretrained: true
+      freeze_backbone: false
+      dropout: 0.1
+"""
+
+from __future__ import annotations
+
+import torch.nn as nn
+
+from .vit_classifier import ViTClassifier, AVAILABLE_BACKBONES
+from .clip_classifier import CLIPClassifier, AVAILABLE_CLIP_BACKBONES
+from .hybrid import HybridClassifier
+from .lora_hybrid import LoRAHybridClassifier
+from .lora_hybrid_fft import LoRAHybridFFTClassifier
+from .artifact_hybrid import ArtifactAwareLoRAHybridClassifier
+from .artifact_gated_hybrid import ArtifactAwareGatedLoRAHybridClassifier
+
+
+def build_model(cfg: dict) -> nn.Module:
+    """
+    config 딕셔너리로부터 모델을 생성한다.
+
+    지원:
+        type = "vit"          →  ViTClassifier
+        type = "clip"         →  CLIPClassifier
+        type = "hybrid"       →  HybridClassifier (ViT + CLIP concat)
+        type = "hybrid_lora"  →  LoRAHybridClassifier (CLIP에 LoRA 적용)
+
+    Args:
+        cfg: config.yaml 전체를 파싱한 딕셔너리
+
+    Returns:
+        nn.Module
+    """
+    model_cfg = cfg.get("model", {})
+    model_type = model_cfg.get("type", "vit").lower()
+
+    if model_type == "vit":
+        backbone = model_cfg.get("backbone", "vit_b_16")
+        if backbone not in AVAILABLE_BACKBONES:
+            raise ValueError(
+                f"model.backbone '{backbone}' 은 지원하지 않습니다.\n"
+                f"사용 가능: {AVAILABLE_BACKBONES}"
+            )
+        return ViTClassifier(
+            backbone_name=backbone,
+            num_classes=model_cfg.get("num_classes", 2),
+            pretrained=model_cfg.get("pretrained", True),
+            freeze_backbone=model_cfg.get("freeze_backbone", False),
+            dropout=model_cfg.get("dropout", 0.1),
+        )
+
+    elif model_type == "clip":
+        backbone = model_cfg.get("backbone", "clip-vit-b-32")
+        if backbone not in AVAILABLE_CLIP_BACKBONES:
+            raise ValueError(
+                f"model.backbone '{backbone}' 은 지원하지 않습니다.\n"
+                f"사용 가능: {AVAILABLE_CLIP_BACKBONES}"
+            )
+        return CLIPClassifier(
+            backbone_name=backbone,
+            mode=model_cfg.get("clip_mode", "linear"),
+            num_classes=model_cfg.get("num_classes", 2),
+            prompts=model_cfg.get("prompts", None),
+            dropout=model_cfg.get("dropout", 0.1),
+            temperature=model_cfg.get("temperature", 1.0),
+        )
+
+    elif model_type == "hybrid":
+        return HybridClassifier(
+            vit_backbone=model_cfg.get("backbone",      "vit_b_16"),
+            clip_backbone=model_cfg.get("clip_backbone", "clip-vit-b-32"),
+            fusion=model_cfg.get("fusion", "concat"),
+            num_classes=model_cfg.get("num_classes", 2),
+            freeze_vit=model_cfg.get("freeze_vit",   True),
+            freeze_clip=model_cfg.get("freeze_clip",  True),
+            vit_pretrained=model_cfg.get("pretrained", True),
+            dropout=model_cfg.get("dropout", 0.1),
+        )
+
+    elif model_type == "hybrid_lora":
+        lora_cfg = model_cfg.get("lora", {})
+        return LoRAHybridClassifier(
+            lora_r=lora_cfg.get("r", 16),
+            lora_alpha=lora_cfg.get("alpha", 32),
+            lora_dropout=lora_cfg.get("dropout", 0.05),
+            lora_vit=lora_cfg.get("vit", True),
+            vit_backbone=model_cfg.get("backbone",       "vit_b_16"),
+            clip_backbone=model_cfg.get("clip_backbone",  "clip-vit-b-32"),
+            fusion=model_cfg.get("fusion",               "concat"),
+            num_classes=model_cfg.get("num_classes",     2),
+            freeze_vit=model_cfg.get("freeze_vit",       True),
+            freeze_clip=model_cfg.get("freeze_clip",     True),
+            vit_pretrained=model_cfg.get("pretrained",   True),
+            dropout=model_cfg.get("dropout",             0.1),
+        )
+
+    elif model_type == "hybrid_lora_fft":
+        lora_cfg = model_cfg.get("lora", {})
+        fft_cfg  = model_cfg.get("fft", {})
+        return LoRAHybridFFTClassifier(
+            fft_dim=fft_cfg.get("dim", 256),
+            fft_dropout=fft_cfg.get("dropout", 0.1),
+            lora_r=lora_cfg.get("r", 32),
+            lora_alpha=lora_cfg.get("alpha", 64),
+            lora_dropout=lora_cfg.get("dropout", 0.1),
+            lora_vit=lora_cfg.get("vit", True),
+            vit_backbone=model_cfg.get("backbone",      "vit_b_16"),
+            clip_backbone=model_cfg.get("clip_backbone", "clip-vit-b-32"),
+            fusion=model_cfg.get("fusion",              "concat"),
+            num_classes=model_cfg.get("num_classes",    2),
+            freeze_vit=model_cfg.get("freeze_vit",      True),
+            freeze_clip=model_cfg.get("freeze_clip",    True),
+            vit_pretrained=model_cfg.get("pretrained",  True),
+            dropout=model_cfg.get("dropout",            0.3),
+        )
+
+    elif model_type == "artifact_lora_hybrid":
+        lora_cfg = model_cfg.get("lora", {})
+        fft_cfg = model_cfg.get("fft", {})
+        srm_cfg = model_cfg.get("srm", {})
+        return ArtifactAwareLoRAHybridClassifier(
+            fft_dim=fft_cfg.get("dim", 256),
+            fft_dropout=fft_cfg.get("dropout", 0.1),
+            srm_dim=srm_cfg.get("dim", 128),
+            srm_dropout=srm_cfg.get("dropout", 0.1),
+            lora_r=lora_cfg.get("r", 32),
+            lora_alpha=lora_cfg.get("alpha", 64),
+            lora_dropout=lora_cfg.get("dropout", 0.1),
+            lora_vit=lora_cfg.get("vit", True),
+            vit_backbone=model_cfg.get("backbone", "vit_b_16"),
+            clip_backbone=model_cfg.get("clip_backbone", "clip-vit-b-32"),
+            fusion=model_cfg.get("fusion", "concat"),
+            num_classes=model_cfg.get("num_classes", 2),
+            freeze_vit=model_cfg.get("freeze_vit", True),
+            freeze_clip=model_cfg.get("freeze_clip", True),
+            vit_pretrained=model_cfg.get("pretrained", True),
+            dropout=model_cfg.get("dropout", 0.3),
+        )
+
+    elif model_type == "artifact_lora_hybrid_gated":
+        lora_cfg = model_cfg.get("lora", {})
+        fft_cfg = model_cfg.get("fft", {})
+        srm_cfg = model_cfg.get("srm", {})
+        gate_cfg = model_cfg.get("gate", {})
+        return ArtifactAwareGatedLoRAHybridClassifier(
+            fft_dim=fft_cfg.get("dim", 256),
+            fft_dropout=fft_cfg.get("dropout", 0.1),
+            srm_dim=srm_cfg.get("dim", 128),
+            srm_dropout=srm_cfg.get("dropout", 0.1),
+            gate_dim=gate_cfg.get("dim", 384),
+            gate_dropout=gate_cfg.get("dropout", 0.12),
+            gate_semantic_only=gate_cfg.get("semantic_only", False),
+            gate_init_bias_semantic=gate_cfg.get("init_bias_semantic"),
+            lora_r=lora_cfg.get("r", 32),
+            lora_alpha=lora_cfg.get("alpha", 64),
+            lora_dropout=lora_cfg.get("dropout", 0.1),
+            lora_vit=lora_cfg.get("vit", True),
+            vit_backbone=model_cfg.get("backbone", "vit_b_16"),
+            clip_backbone=model_cfg.get("clip_backbone", "clip-vit-b-32"),
+            fusion=model_cfg.get("fusion", "concat"),
+            num_classes=model_cfg.get("num_classes", 2),
+            freeze_vit=model_cfg.get("freeze_vit", True),
+            freeze_clip=model_cfg.get("freeze_clip", True),
+            vit_pretrained=model_cfg.get("pretrained", True),
+            dropout=model_cfg.get("dropout", 0.3),
+        )
+
+    else:
+        raise ValueError(
+            f"지원하지 않는 model.type: '{model_type}'\n"
+            f"사용 가능: 'vit', 'clip', 'hybrid', 'hybrid_lora', "
+            f"'hybrid_lora_fft', 'artifact_lora_hybrid', 'artifact_lora_hybrid_gated'"
+        )

src/models/fft_branch.py

@@ -0,0 +1,145 @@
+"""
+FFT(주파수 도메인) 특징 추출기.
+
+AI 생성 이미지는 픽셀 도메인과 달리 주파수 도메인에서 독특한 패턴을 남긴다:
+  - 업샘플링(bilinear/nearest) → 특정 주파수 대역에 격자 아티팩트
+  - Attention 패턴 → 주기적인 고주파 패턴
+  - GAN/Diffusion 디코더 → 고주파 성분 분포 이상
+
+FFTBranch 설계:
+    1. 입력 이미지를 채널별 2D FFT → log-magnitude 스펙트럼
+    2. 중심 이동(fftshift) → DC 성분이 중앙에 위치
+    3. 소형 CNN(3 conv) → Global Average Pooling → 256-dim 벡터
+
+학습 파라미터 수: ~300K (기존 모델 대비 매우 작음)
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class FFTBranch(nn.Module):
+    """
+    이미지 → 주파수 도메인 특징 벡터 (B, out_dim).
+
+    Args:
+        out_dim:    출력 특징 차원 (기본 256)
+        image_size: 입력 이미지 크기 (기본 224)
+        dropout:    드롭아웃 비율
+    """
+
+    def __init__(
+        self,
+        out_dim: int = 256,
+        image_size: int = 224,
+        dropout: float = 0.1,
+    ):
+        super().__init__()
+        self.out_dim = out_dim
+        self.image_size = image_size
+
+        # ── 소형 CNN (주파수 맵 처리) ──────────────────────────
+        # 입력: (B, 3, H, W) log-magnitude 스펙트럼
+        # 수용 영역이 넓게 (7x7 → 5x5 → 3x3)
+        self.conv = nn.Sequential(
+            # Block 1: 3 → 32
+            nn.Conv2d(3, 32, kernel_size=7, stride=2, padding=3, bias=False),
+            nn.BatchNorm2d(32),
+            nn.GELU(),
+
+            # Block 2: 32 → 64
+            nn.Conv2d(32, 64, kernel_size=5, stride=2, padding=2, bias=False),
+            nn.BatchNorm2d(64),
+            nn.GELU(),
+
+            # Block 3: 64 → 128
+            nn.Conv2d(64, 128, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(128),
+            nn.GELU(),
+
+            # Block 4: 128 → 128
+            nn.Conv2d(128, 128, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(128),
+            nn.GELU(),
+        )
+
+        # Global Average Pooling → Flatten
+        self.gap = nn.AdaptiveAvgPool2d(1)
+
+        # 투영 레이어: 128 → out_dim
+        self.proj = nn.Sequential(
+            nn.Dropout(p=dropout),
+            nn.Linear(128, out_dim),
+            nn.LayerNorm(out_dim),
+        )
+
+        self._init_weights()
+
+    def _init_weights(self):
+        for m in self.modules():
+            if isinstance(m, nn.Conv2d):
+                nn.init.kaiming_normal_(m.weight, mode="fan_out", nonlinearity="relu")
+            elif isinstance(m, nn.BatchNorm2d):
+                nn.init.ones_(m.weight)
+                nn.init.zeros_(m.bias)
+            elif isinstance(m, nn.Linear):
+                nn.init.trunc_normal_(m.weight, std=0.02)
+                if m.bias is not None:
+                    nn.init.zeros_(m.bias)
+
+    @staticmethod
+    def compute_fft_spectrum(x: torch.Tensor) -> torch.Tensor:
+        """
+        이미지 → 채널별 log-magnitude FFT 스펙트럼.
+
+        Args:
+            x: (B, C, H, W) float tensor, 정규화된 이미지
+
+        Returns:
+            spectrum: (B, C, H, W) float tensor, 정규화된 log-magnitude
+        """
+        # 2D FFT 적용 (채널별)
+        # x: (B, C, H, W) → complex
+        f = torch.fft.fft2(x, norm="ortho")
+
+        # DC 성분을 중앙으로 이동
+        f = torch.fft.fftshift(f, dim=(-2, -1))
+
+        # Log magnitude (수치 안정성: +1e-8)
+        magnitude = torch.abs(f)
+        log_magnitude = torch.log1p(magnitude)
+
+        # [0, 1]로 정규화 (배치 내 각 이미지별)
+        B, C, H, W = log_magnitude.shape
+        flat = log_magnitude.view(B, -1)
+        min_val = flat.min(dim=1, keepdim=True)[0].view(B, 1, 1, 1)
+        max_val = flat.max(dim=1, keepdim=True)[0].view(B, 1, 1, 1)
+        spectrum = (log_magnitude - min_val) / (max_val - min_val + 1e-8)
+
+        return spectrum
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: (B, 3, H, W) 정규화된 이미지
+
+        Returns:
+            feat: (B, out_dim) 주파수 도메인 특징 벡터
+        """
+        # 1. FFT 스펙트럼 계산
+        spectrum = self.compute_fft_spectrum(x)  # (B, 3, H, W)
+
+        # 2. CNN 통과
+        feat = self.conv(spectrum)    # (B, 128, H', W')
+
+        # 3. Global Average Pooling
+        feat = self.gap(feat)         # (B, 128, 1, 1)
+        feat = feat.flatten(1)        # (B, 128)
+
+        # 4. 투영
+        feat = self.proj(feat)        # (B, out_dim)
+
+        return feat

src/models/hybrid.py

@@ -0,0 +1,238 @@
+"""
+ViT + CLIP Hybrid 분류기.
+
+기본 fusion: concat → MLP classifier
+    ViT  forward_features → (B, vit_dim)    [예: 768]
+    CLIP forward_features → (B, clip_dim)   [예: 512]
+    concat               → (B, vit_dim + clip_dim)  [예: 1280]
+    MLP head             → (B, num_classes)
+
+설계 원칙:
+    - 두 인코더의 forward_features() 를 재사용 (기존 코드 변경 없음)
+    - fusion 방식을 문자열로 선택 가능 → 추후 확장 대비
+    - freeze_vit / freeze_clip 으로 인코더별 동결 제어
+    - 헤드의 LayerNorm 이 ViT(비정규화) / CLIP(L2 정규화) 스케일 차이를 흡수
+
+추후 fusion 확장 위치:
+    forward_features() 내의 _fuse() 메서드에 새 방식 추가
+    현재: "concat"
+    TODO: "weighted" (학습 가능한 가중치 합)
+    TODO: "attention" (cross-attention 기반 융합)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Literal
+
+import torch
+import torch.nn as nn
+
+from .vit_classifier import ViTClassifier, AVAILABLE_BACKBONES
+from .clip_classifier import CLIPClassifier, AVAILABLE_CLIP_BACKBONES
+
+
+# 지원하는 fusion 방식
+FUSION_TYPES = Literal["concat"]   # 추후: "weighted", "attention"
+
+
+def _build_mlp_head(in_dim: int, num_classes: int, dropout: float) -> nn.Sequential:
+    """
+    2-layer MLP 분류 헤드.
+
+    구조: LayerNorm → Linear(in → in//2) → GELU → Dropout → Linear(in//2 → C)
+
+    LayerNorm 을 첫 번째에 두어 ViT / CLIP 의 스케일 차이(~27 vs ~1)를 정규화한다.
+    """
+    hidden = in_dim // 2
+    head = nn.Sequential(
+        nn.LayerNorm(in_dim),
+        nn.Linear(in_dim, hidden),
+        nn.GELU(),
+        nn.Dropout(p=dropout),
+        nn.Linear(hidden, num_classes),
+    )
+    # 마지막 레이어 초기화
+    nn.init.trunc_normal_(head[-1].weight, std=0.02)
+    nn.init.zeros_(head[-1].bias)
+    return head
+
+
+class HybridClassifier(nn.Module):
+    """
+    ViT + CLIP Hybrid 이진 분류기.
+
+    Args:
+        vit_backbone:   ViT 백본 이름 (vit_b_16 | vit_b_32 | vit_l_16)
+        clip_backbone:  CLIP 백본 이름 (clip-vit-b-32 | clip-vit-b-16 | clip-vit-l-14)
+        fusion:         특징 결합 방식 ("concat")
+        num_classes:    출력 클래스 수 (기본 2)
+        freeze_vit:     True면 ViT backbone 동결 (헤드는 항상 학습)
+        freeze_clip:    True면 CLIP vision encoder 동결
+        vit_pretrained: ViT ImageNet 사전학습 가중치 사용
+        dropout:        MLP 헤드 드롭아웃 비율
+    """
+
+    def __init__(
+        self,
+        vit_backbone:  str = "vit_b_16",
+        clip_backbone: str = "clip-vit-b-32",
+        fusion:        str = "concat",
+        num_classes:   int = 2,
+        freeze_vit:    bool = True,
+        freeze_clip:   bool = True,
+        vit_pretrained: bool = True,
+        dropout:       float = 0.1,
+    ):
+        super().__init__()
+
+        # ── 입력 검증 ─────────────────────────────
+        if vit_backbone not in AVAILABLE_BACKBONES:
+            raise ValueError(
+                f"지원하지 않는 ViT 백본: '{vit_backbone}'\n"
+                f"사용 가능: {AVAILABLE_BACKBONES}"
+            )
+        if clip_backbone not in AVAILABLE_CLIP_BACKBONES:
+            raise ValueError(
+                f"지원하지 않는 CLIP 백본: '{clip_backbone}'\n"
+                f"사용 가능: {AVAILABLE_CLIP_BACKBONES}"
+            )
+        if fusion != "concat":
+            raise ValueError(
+                f"지원하지 않는 fusion 방식: '{fusion}'\n"
+                f"현재 지원: 'concat'  (TODO: 'weighted', 'attention')"
+            )
+
+        self.vit_backbone_name  = vit_backbone
+        self.clip_backbone_name = clip_backbone
+        self.fusion      = fusion
+        self.num_classes = num_classes
+
+        # ── ViT 인코더 ────────────────────────────
+        # freeze_backbone=False 로 생성 후 HybridClassifier가 직접 제어
+        self.vit_encoder = ViTClassifier(
+            backbone_name=vit_backbone,
+            num_classes=num_classes,
+            pretrained=vit_pretrained,
+            freeze_backbone=False,
+            dropout=dropout,
+        )
+        self.vit_dim = self.vit_encoder.hidden_dim  # 예: 768
+
+        # ViT backbone: freeze_vit 값에 따라 명시적으로 설정
+        for param in self.vit_encoder.backbone.parameters():
+            param.requires_grad = not freeze_vit
+        # ViT 자체 헤드는 Hybrid에서 사용 안 함 → 항상 동결
+        for param in self.vit_encoder.head.parameters():
+            param.requires_grad = False
+
+        # ── CLIP 인코더 ───────────────────────────
+        # image_only=True: Hybrid 는 CLIP image feature 만 사용하므로
+        # text encoder / tokenizer / text_embeddings 초기화를 생략한다.
+        # mode="linear" 로 생성. CLIPClassifier 내부에서 vision_model을 동결하지만,
+        # HybridClassifier 가 freeze_clip 값에 따라 명시적으로 재설정한다.
+        self.clip_encoder = CLIPClassifier(
+            backbone_name=clip_backbone,
+            mode="linear",
+            num_classes=num_classes,
+            dropout=dropout,
+            image_only=True,
+        )
+        self.clip_dim = self.clip_encoder.embed_dim  # 예: 512
+
+        # CLIP vision encoder: freeze_clip 값에 따라 명시적으로 설정
+        # (CLIPClassifier.__init__에서 mode="linear"가 freeze한 것을 재정의)
+        for param in self.clip_encoder.vision_model.parameters():
+            param.requires_grad = not freeze_clip
+        # CLIP 자체 헤드도 Hybrid에서 사용 안 함 → 항상 동결
+        if self.clip_encoder.head is not None:
+            for param in self.clip_encoder.head.parameters():
+                param.requires_grad = False
+
+        # ── Fusion 헤드 ───────────────────────────
+        self.fused_dim = self.vit_dim + self.clip_dim  # 예: 1280
+        self.head = _build_mlp_head(self.fused_dim, num_classes, dropout)
+
+    # ──────────────────────────────────────────
+    # Fusion 로직
+    # ──────────────────────────────────────────
+
+    def _fuse(
+        self,
+        vit_feat: torch.Tensor,   # (B, vit_dim)
+        clip_feat: torch.Tensor,  # (B, clip_dim)
+    ) -> torch.Tensor:
+        """
+        두 특징벡터를 fusion 방식에 따라 결합한다.
+
+        Returns:
+            fused (B, fused_dim)
+
+        추후 새 fusion 방식 추가 위치:
+            elif self.fusion == "weighted":
+                ...
+            elif self.fusion == "attention":
+                ...
+        """
+        if self.fusion == "concat":
+            return torch.cat([vit_feat, clip_feat], dim=-1)  # (B, 1280)
+
+        # 이 라인에 도달하면 버그 → 생성자에서 검증했으므로 발생하지 않음
+        raise RuntimeError(f"알 수 없는 fusion: {self.fusion}")
+
+    # ──────────────────────────────────────────
+    # Forward
+    # ──────────────────────────────────────────
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        이미지 → 결합된 특징벡터 (B, fused_dim).
+
+        XAI, 임베딩 시각화, Hybrid-of-Hybrid 확장 등에 사용.
+        """
+        vit_feat  = self.vit_encoder.forward_features(x)   # (B, 768)
+        clip_feat = self.clip_encoder.forward_features(x)  # (B, 512)
+        return self._fuse(vit_feat, clip_feat)              # (B, 1280)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """logits (B, num_classes) 반환."""
+        return self.head(self.forward_features(x))
+
+    @torch.no_grad()
+    def predict_proba(self, x: torch.Tensor) -> torch.Tensor:
+        """Softmax 확률 (B, num_classes). 추론 전용."""
+        self.eval()
+        return torch.softmax(self(x), dim=-1)
+
+    # ──────────────────────────────────────────
+    # 유틸
+    # ──────────────────────────────────────────
+
+    def trainable_params(self) -> int:
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)
+
+    def total_params(self) -> int:
+        return sum(p.numel() for p in self.parameters())
+
+    def param_summary(self) -> str:
+        trainable = self.trainable_params()
+        total = self.total_params()
+        return (
+            f"[Hybrid: {self.vit_backbone_name} + {self.clip_backbone_name} / {self.fusion}] "
+            f"전체 {total:,} | 학습 가능 {trainable:,} "
+            f"({100 * trainable / total:.1f}%)"
+        )
+
+    def encoder_summary(self) -> str:
+        """각 인코더의 학습 가능 파라미터 수를 출력한다."""
+        vit_total   = sum(p.numel() for p in self.vit_encoder.parameters())
+        vit_train   = sum(p.numel() for p in self.vit_encoder.parameters() if p.requires_grad)
+        clip_total  = sum(p.numel() for p in self.clip_encoder.parameters())
+        clip_train  = sum(p.numel() for p in self.clip_encoder.parameters() if p.requires_grad)
+        head_params = sum(p.numel() for p in self.head.parameters())
+        return (
+            f"  ViT  ({self.vit_backbone_name}): {vit_total:>12,} 전체 | {vit_train:>12,} 학습 가능\n"
+            f"  CLIP ({self.clip_backbone_name}): {clip_total:>12,} 전체 | {clip_train:>12,} 학습 가능\n"
+            f"  Fusion head:        {head_params:>12,} (항상 학습)\n"
+            f"  fused_dim: {self.vit_dim} + {self.clip_dim} = {self.fused_dim}"
+        )

src/models/lora_hybrid.py

@@ -0,0 +1,172 @@
+"""
+LoRA 적용 Hybrid 분류기.
+
+HybridClassifier를 기반으로 CLIP vision encoder와 ViT encoder에
+LoRA 어댑터를 주입한다.
+
+설계 원칙:
+    - PEFT 없이 직접 LoRALinear 구현 (peft/transformers 버전 충돌 회피)
+    - CLIP: q_proj / v_proj 에 LoRA 적용
+    - ViT:  out_proj (attention) + MLP 레이어에 LoRA 적용
+    - Trainer / factory 와 완전 호환 (forward, param_summary 동일 인터페이스)
+
+LoRA 수식:
+    W' = W + (lora_alpha / r) * BA
+    A: (r, in_dim)  B: (out_dim, r)  → 추가 학습 파라미터 수 ≈ 2*r*d
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+import torch.nn as nn
+
+from .hybrid import HybridClassifier
+
+
+class LoRALinear(nn.Module):
+    """
+    기존 nn.Linear를 감싸서 LoRA 어댑터를 추가하는 레이어.
+
+    forward:  y = x @ W^T + b  +  (alpha/r) * x @ A^T @ B^T
+    학습 파라미터: lora_A (r × in), lora_B (out × r) 만 requires_grad=True
+    기존 weight/bias: requires_grad=False (동결 유지)
+    """
+
+    def __init__(self, linear: nn.Linear, r: int, alpha: int, dropout: float = 0.0):
+        super().__init__()
+        self.base = linear
+        self.base.weight.requires_grad_(False)
+        if self.base.bias is not None:
+            self.base.bias.requires_grad_(False)
+
+        in_dim  = linear.in_features
+        out_dim = linear.out_features
+        self.r     = r
+        self.scale = alpha / r
+
+        self.lora_A = nn.Parameter(torch.empty(r, in_dim))
+        self.lora_B = nn.Parameter(torch.zeros(out_dim, r))
+        nn.init.kaiming_uniform_(self.lora_A, a=math.sqrt(5))
+
+        self.lora_dropout = nn.Dropout(p=dropout) if dropout > 0.0 else nn.Identity()
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        base_out = self.base(x)
+        lora_out = self.lora_dropout(x) @ self.lora_A.T @ self.lora_B.T
+        return base_out + self.scale * lora_out
+
+
+def _apply_lora_to_clip(
+    clip_encoder: nn.Module,
+    lora_r: int,
+    lora_alpha: int,
+    lora_dropout: float,
+) -> nn.Module:
+    """
+    CLIPClassifier.vision_model 의 모든 encoder layer에서
+    q_proj / v_proj 를 LoRALinear 로 교체한다 (in-place).
+
+    구조: clip_encoder.vision_model.vision_model.encoder.layers
+    """
+    encoder_layers = clip_encoder.vision_model.vision_model.encoder.layers
+    for layer in encoder_layers:
+        attn = layer.self_attn
+        attn.q_proj = LoRALinear(attn.q_proj, r=lora_r, alpha=lora_alpha, dropout=lora_dropout)
+        attn.v_proj = LoRALinear(attn.v_proj, r=lora_r, alpha=lora_alpha, dropout=lora_dropout)
+    return clip_encoder
+
+
+def _apply_lora_to_vit(
+    vit_encoder: nn.Module,
+    lora_r: int,
+    lora_alpha: int,
+    lora_dropout: float,
+) -> nn.Module:
+    """
+    ViTClassifier.backbone 의 모든 encoder layer에서
+    MLP 레이어를 LoRALinear 로 교체한다 (in-place).
+
+    torchvision ViT 구조:
+        backbone.encoder.layers.encoder_layer_N.mlp[0]  (768→3072)
+        backbone.encoder.layers.encoder_layer_N.mlp[3]  (3072→768)
+
+    Note: torchvision ViT의 MultiheadAttention은 out_proj.weight를 직접 접근
+    (F.multi_head_attention_forward)하므로 out_proj는 교체 불가 — MLP에만 적용.
+    """
+    for layer in vit_encoder.backbone.encoder.layers:
+        mlp = layer.mlp
+        mlp[0] = LoRALinear(mlp[0], r=lora_r, alpha=lora_alpha, dropout=lora_dropout)
+        mlp[3] = LoRALinear(mlp[3], r=lora_r, alpha=lora_alpha, dropout=lora_dropout)
+    return vit_encoder
+
+
+class LoRAHybridClassifier(HybridClassifier):
+    """
+    CLIP + ViT 양쪽에 LoRA를 적용한 HybridClassifier.
+
+    Args:
+        lora_r:        LoRA rank (기본 16)
+        lora_alpha:    LoRA scaling factor (기본 32)
+        lora_dropout:  LoRA dropout (기본 0.05)
+        lora_vit:      ViT에도 LoRA 적용 여부 (기본 True)
+        + HybridClassifier 의 모든 인자
+    """
+
+    def __init__(
+        self,
+        lora_r: int = 16,
+        lora_alpha: int = 32,
+        lora_dropout: float = 0.05,
+        lora_vit: bool = True,
+        # HybridClassifier 기본 인자
+        vit_backbone:   str   = "vit_b_16",
+        clip_backbone:  str   = "clip-vit-b-32",
+        fusion:         str   = "concat",
+        num_classes:    int   = 2,
+        freeze_vit:     bool  = True,
+        freeze_clip:    bool  = True,
+        vit_pretrained: bool  = True,
+        dropout:        float = 0.1,
+    ):
+        super().__init__(
+            vit_backbone=vit_backbone,
+            clip_backbone=clip_backbone,
+            fusion=fusion,
+            num_classes=num_classes,
+            freeze_vit=freeze_vit,
+            freeze_clip=freeze_clip,
+            vit_pretrained=vit_pretrained,
+            dropout=dropout,
+        )
+
+        self.lora_r = lora_r
+        self.lora_alpha = lora_alpha
+        self.lora_vit = lora_vit
+
+        # CLIP에 LoRA 주입
+        _apply_lora_to_clip(self.clip_encoder, lora_r, lora_alpha, lora_dropout)
+
+        # ViT에도 LoRA 주입 (base 가중치는 이미 동결됨)
+        if lora_vit:
+            _apply_lora_to_vit(self.vit_encoder, lora_r, lora_alpha, lora_dropout)
+
+    def param_summary(self) -> str:
+        trainable = self.trainable_params()
+        total = self.total_params()
+        vit_tag = "+ViT" if self.lora_vit else ""
+        return (
+            f"[Hybrid+LoRA{vit_tag}: {self.vit_backbone_name} + {self.clip_backbone_name} "
+            f"r={self.lora_r} α={self.lora_alpha}] "
+            f"전체 {total:,} | 학습 가능 {trainable:,} "
+            f"({100 * trainable / total:.1f}%)"
+        )
+
+    def lora_param_count(self) -> int:
+        """LoRA 어댑터 가중치만의 파라미터 수."""
+        count = 0
+        for name, p in self.named_parameters():
+            if "lora_" in name and p.requires_grad:
+                count += p.numel()
+        return count

src/models/lora_hybrid_fft.py

@@ -0,0 +1,166 @@
+"""
+LoRA Hybrid + FFT Branch 분류기.
+
+기존 LoRAHybridClassifier에 주파수 도메인 분기(FFTBranch)를 추가.
+
+구조:
+    ViT-B/16  (768)  LoRA 동결 or 미세조정
+    CLIP ViT-B/32 (512)  LoRA 동결 or 미세조정
+    FFT branch (256)  새로 학습
+    ──────────────────────────────────────────
+    concat → (1536) → MLP head → 2 classes
+
+학습 전략 (2단계):
+    Stage 1: FFT branch + 새 head만 학습 (LoRA 동결)
+             → 기존 ViT/CLIP 표현 손상 없이 FFT 수렴
+    Stage 2: 전체 LoRA + FFT + head 학습 (lr 낮게)
+             → 통합 최적화
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from .lora_hybrid import LoRAHybridClassifier
+from .fft_branch import FFTBranch
+
+
+def _build_mlp_head(in_dim: int, num_classes: int, dropout: float) -> nn.Sequential:
+    hidden = in_dim // 2
+    head = nn.Sequential(
+        nn.LayerNorm(in_dim),
+        nn.Linear(in_dim, hidden),
+        nn.GELU(),
+        nn.Dropout(p=dropout),
+        nn.Linear(hidden, num_classes),
+    )
+    nn.init.trunc_normal_(head[-1].weight, std=0.02)
+    nn.init.zeros_(head[-1].bias)
+    return head
+
+
+class LoRAHybridFFTClassifier(LoRAHybridClassifier):
+    """
+    ViT(LoRA) + CLIP(LoRA) + FFT Branch 삼중 분류기.
+
+    Args:
+        fft_dim:       FFT branch 출력 차원 (기본 256)
+        fft_dropout:   FFT branch 드롭아웃
+        + LoRAHybridClassifier 의 모든 인자
+    """
+
+    def __init__(
+        self,
+        fft_dim: int = 256,
+        fft_dropout: float = 0.1,
+        # LoRA 인자
+        lora_r: int = 32,
+        lora_alpha: int = 64,
+        lora_dropout: float = 0.1,
+        lora_vit: bool = True,
+        # Hybrid 인자
+        vit_backbone:   str   = "vit_b_16",
+        clip_backbone:  str   = "clip-vit-b-32",
+        fusion:         str   = "concat",
+        num_classes:    int   = 2,
+        freeze_vit:     bool  = True,
+        freeze_clip:    bool  = True,
+        vit_pretrained: bool  = True,
+        dropout:        float = 0.3,
+    ):
+        super().__init__(
+            lora_r=lora_r,
+            lora_alpha=lora_alpha,
+            lora_dropout=lora_dropout,
+            lora_vit=lora_vit,
+            vit_backbone=vit_backbone,
+            clip_backbone=clip_backbone,
+            fusion=fusion,
+            num_classes=num_classes,
+            freeze_vit=freeze_vit,
+            freeze_clip=freeze_clip,
+            vit_pretrained=vit_pretrained,
+            dropout=dropout,
+        )
+
+        self.fft_dim = fft_dim
+
+        # FFT branch 추가 (새로 학습할 파라미터)
+        self.fft_branch = FFTBranch(
+            out_dim=fft_dim,
+            dropout=fft_dropout,
+        )
+
+        # 기존 head(1280 → 2)를 새 head(1280+256=1536 → 2)로 교체
+        new_fused_dim = self.fused_dim + fft_dim   # 1280 + 256 = 1536
+        self.head = _build_mlp_head(new_fused_dim, num_classes, dropout)
+        self.fused_dim = new_fused_dim
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        ViT + CLIP + FFT 특징을 concat.
+
+        Returns:
+            (B, 1536)
+        """
+        vit_feat  = self.vit_encoder.forward_features(x)    # (B, 768)
+        clip_feat = self.clip_encoder.forward_features(x)   # (B, 512)
+        fft_feat  = self.fft_branch(x)                       # (B, 256)
+        return torch.cat([vit_feat, clip_feat, fft_feat], dim=-1)  # (B, 1536)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.forward_features(x))
+
+    def freeze_lora(self):
+        """Stage 1: LoRA 가중치 동결, FFT branch + head만 학습."""
+        for name, param in self.named_parameters():
+            if "lora_" in name:
+                param.requires_grad_(False)
+        # FFT branch와 head는 항상 학습
+        for param in self.fft_branch.parameters():
+            param.requires_grad_(True)
+        for param in self.head.parameters():
+            param.requires_grad_(True)
+
+    def unfreeze_lora(self):
+        """Stage 2: LoRA 가중치 해제, 전체 학습."""
+        for name, param in self.named_parameters():
+            if "lora_" in name:
+                param.requires_grad_(True)
+
+    def load_lora_weights(self, checkpoint_path: str, device: str = "cpu"):
+        """
+        기존 LoRAHybridClassifier 체크포인트에서 ViT/CLIP/LoRA 가중치만 로드.
+        FFT branch와 새 head는 랜덤 초기화 유지.
+        """
+        import torch
+        ckpt = torch.load(checkpoint_path, map_location=device, weights_only=True)
+        state = ckpt.get("model_state_dict", ckpt)
+
+        # FFT branch / head 키 제외하고 로드
+        own_state = self.state_dict()
+        loaded, skipped = 0, 0
+        for k, v in state.items():
+            if k.startswith("fft_branch.") or k.startswith("head."):
+                skipped += 1
+                continue
+            if k in own_state and own_state[k].shape == v.shape:
+                own_state[k] = v
+                loaded += 1
+            else:
+                skipped += 1
+
+        self.load_state_dict(own_state, strict=False)
+        print(f"  [FFT모델 로드] {loaded}개 키 로드, {skipped}개 skip (fft/head 제외)")
+
+    def param_summary(self) -> str:
+        trainable = self.trainable_params()
+        total = self.total_params()
+        fft_params = sum(p.numel() for p in self.fft_branch.parameters())
+        return (
+            f"[Hybrid+LoRA+FFT: {self.vit_backbone_name} + {self.clip_backbone_name} "
+            f"r={self.lora_r} α={self.lora_alpha}] "
+            f"전체 {total:,} | 학습 가능 {trainable:,} ({100*trainable/total:.1f}%) "
+            f"| FFT branch {fft_params:,}"
+        )

src/models/srm_branch.py

@@ -0,0 +1,149 @@
+"""High-pass residual branch for AI-image forensic cues.
+
+The branch uses a small fixed SRM-style high-pass filter bank, then learns a
+compact CNN over the residual maps. It is intentionally light so it can be
+added to the existing ViT+CLIP+LoRA hybrid within 8GB VRAM.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+CLIP_MEAN = (0.48145466, 0.4578275, 0.40821073)
+CLIP_STD = (0.26862954, 0.26130258, 0.27577711)
+
+
+def _make_highpass_bank() -> torch.Tensor:
+    """Return fixed 5x5 high-pass kernels repeated per RGB channel."""
+    filters = []
+
+    laplace_3 = torch.tensor(
+        [
+            [0, 0, 0, 0, 0],
+            [0, -1, -1, -1, 0],
+            [0, -1, 8, -1, 0],
+            [0, -1, -1, -1, 0],
+            [0, 0, 0, 0, 0],
+        ],
+        dtype=torch.float32,
+    ) / 8.0
+
+    laplace_5 = torch.tensor(
+        [
+            [-1, 2, -2, 2, -1],
+            [2, -6, 8, -6, 2],
+            [-2, 8, -12, 8, -2],
+            [2, -6, 8, -6, 2],
+            [-1, 2, -2, 2, -1],
+        ],
+        dtype=torch.float32,
+    ) / 12.0
+
+    horizontal = torch.tensor(
+        [
+            [0, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0],
+            [0, -1, 2, -1, 0],
+            [0, 0, 0, 0, 0],
+            [0, 0, 0, 0, 0],
+        ],
+        dtype=torch.float32,
+    ) / 2.0
+
+    vertical = horizontal.t().contiguous()
+
+    diagonal = torch.tensor(
+        [
+            [-1, 0, 0, 0, 1],
+            [0, -1, 0, 1, 0],
+            [0, 0, 0, 0, 0],
+            [0, 1, 0, -1, 0],
+            [1, 0, 0, 0, -1],
+        ],
+        dtype=torch.float32,
+    ) / 4.0
+
+    anti_diagonal = torch.flip(diagonal, dims=[1])
+    base_filters = [laplace_3, laplace_5, horizontal, vertical, diagonal, anti_diagonal]
+
+    weight = torch.zeros(len(base_filters) * 3, 3, 5, 5, dtype=torch.float32)
+    out_idx = 0
+    for channel in range(3):
+        for kernel in base_filters:
+            weight[out_idx, channel] = kernel
+            out_idx += 1
+    return weight
+
+
+class SRMBranch(nn.Module):
+    """Fixed high-pass residual filters followed by a compact trainable CNN."""
+
+    def __init__(self, out_dim: int = 128, dropout: float = 0.1):
+        super().__init__()
+        self.out_dim = out_dim
+
+        self.register_buffer("clip_mean", torch.tensor(CLIP_MEAN).view(1, 3, 1, 1))
+        self.register_buffer("clip_std", torch.tensor(CLIP_STD).view(1, 3, 1, 1))
+
+        self.highpass = nn.Conv2d(
+            in_channels=3,
+            out_channels=18,
+            kernel_size=5,
+            padding=2,
+            bias=False,
+        )
+        with torch.no_grad():
+            self.highpass.weight.copy_(_make_highpass_bank())
+        self.highpass.weight.requires_grad_(False)
+
+        self.encoder = nn.Sequential(
+            nn.Conv2d(18, 48, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(48),
+            nn.GELU(),
+            nn.Conv2d(48, 96, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(96),
+            nn.GELU(),
+            nn.Conv2d(96, 128, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(128),
+            nn.GELU(),
+            nn.Conv2d(128, 128, kernel_size=3, stride=2, padding=1, bias=False),
+            nn.BatchNorm2d(128),
+            nn.GELU(),
+        )
+        self.pool = nn.AdaptiveAvgPool2d(1)
+        self.proj = nn.Sequential(
+            nn.Dropout(p=dropout),
+            nn.Linear(128, out_dim),
+            nn.LayerNorm(out_dim),
+        )
+
+        self._init_trainable_weights()
+
+    def _init_trainable_weights(self) -> None:
+        for module in self.modules():
+            if module is self.highpass:
+                continue
+            if isinstance(module, nn.Conv2d):
+                nn.init.kaiming_normal_(module.weight, mode="fan_out", nonlinearity="relu")
+            elif isinstance(module, nn.BatchNorm2d):
+                nn.init.ones_(module.weight)
+                nn.init.zeros_(module.bias)
+            elif isinstance(module, nn.Linear):
+                nn.init.trunc_normal_(module.weight, std=0.02)
+                if module.bias is not None:
+                    nn.init.zeros_(module.bias)
+
+    def _to_raw_rgb(self, x: torch.Tensor) -> torch.Tensor:
+        # Training inputs are CLIP-normalized. For residual filters, use the
+        # image-like range so filters see sensor/compression residue rather than
+        # normalization offsets.
+        return (x * self.clip_std + self.clip_mean).clamp(0.0, 1.0)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        raw = self._to_raw_rgb(x)
+        residual = self.highpass(raw)
+        feat = self.encoder(residual)
+        feat = self.pool(feat).flatten(1)
+        return self.proj(feat)

src/models/vit_classifier.py

@@ -0,0 +1,165 @@
+"""
+ViT 기반 이진 분류기.
+
+지원 백본 (torchvision):
+    vit_b_16  ViT-Base  / patch16 / hidden 768   (~86M params)
+    vit_b_32  ViT-Base  / patch32 / hidden 768   (~88M params)
+    vit_l_16  ViT-Large / patch16 / hidden 1024  (~307M params)
+
+핵심 설계:
+    - torchvision 백본의 heads 레이어를 Identity로 교체
+    - backbone(x) 가 CLS 토큰 특징벡터 (B, hidden_dim) 를 반환하게 만듦
+    - 그 위에 커스텀 분류 헤드 추가
+    - forward_features() 로 특징벡터를 별도 추출 가능 (XAI 연결 준비)
+
+사용:
+    model = ViTClassifier("vit_b_16", pretrained=True)
+    logits = model(images)                    # (B, 2)
+    feats  = model.forward_features(images)   # (B, 768)
+    probs  = model.predict_proba(images)      # (B, 2)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+import torch
+import torch.nn as nn
+from torchvision.models import (
+    vit_b_16, ViT_B_16_Weights,
+    vit_b_32, ViT_B_32_Weights,
+    vit_l_16, ViT_L_16_Weights,
+)
+
+
+# ──────────────────────────────────────────────
+# 백본 레지스트리
+# ──────────────────────────────────────────────
+
+@dataclass
+class _BackboneSpec:
+    builder:    Callable        # torchvision 모델 생성 함수
+    weights:    object          # ImageNet 사전학습 가중치
+    hidden_dim: int             # CLS 토큰 차원
+
+
+_BACKBONE_REGISTRY: dict[str, _BackboneSpec] = {
+    "vit_b_16": _BackboneSpec(vit_b_16, ViT_B_16_Weights.IMAGENET1K_V1, 768),
+    "vit_b_32": _BackboneSpec(vit_b_32, ViT_B_32_Weights.IMAGENET1K_V1, 768),
+    "vit_l_16": _BackboneSpec(vit_l_16, ViT_L_16_Weights.IMAGENET1K_V1, 1024),
+}
+
+AVAILABLE_BACKBONES = list(_BACKBONE_REGISTRY.keys())
+
+
+def _build_backbone(name: str, pretrained: bool) -> tuple[nn.Module, int]:
+    """
+    백본을 생성하고 heads를 Identity로 교체한다.
+
+    Returns:
+        (backbone, hidden_dim)
+        backbone(x) 는 CLS 특징벡터 (B, hidden_dim) 를 반환한다.
+    """
+    if name not in _BACKBONE_REGISTRY:
+        raise ValueError(
+            f"지원하지 않는 백본: '{name}'\n"
+            f"사용 가능: {AVAILABLE_BACKBONES}"
+        )
+    spec = _BACKBONE_REGISTRY[name]
+    weights = spec.weights if pretrained else None
+    backbone = spec.builder(weights=weights)
+
+    # 원본 heads(1000-class linear)를 Identity로 교체
+    # → backbone.forward() 가 x[:, 0] (CLS 토큰) 을 그대로 반환하게 됨
+    backbone.heads = nn.Identity()
+
+    return backbone, spec.hidden_dim
+
+
+# ──────────────────────────────────────────────
+# 분류기
+# ──────────────────────────────────────────────
+
+class ViTClassifier(nn.Module):
+    """
+    ViT 기반 real/fake 이진 분류기.
+
+    Args:
+        backbone_name:   백본 이름 (vit_b_16 | vit_b_32 | vit_l_16)
+        num_classes:     출력 클래스 수 (기본 2)
+        pretrained:      ImageNet 사전학습 가중치 사용
+        freeze_backbone: True면 백본 동결, 헤드만 학습
+        dropout:         분류 헤드 Dropout 비율
+    """
+
+    def __init__(
+        self,
+        backbone_name: str = "vit_b_16",
+        num_classes: int = 2,
+        pretrained: bool = True,
+        freeze_backbone: bool = False,
+        dropout: float = 0.1,
+    ):
+        super().__init__()
+
+        self.backbone_name = backbone_name
+        self.num_classes = num_classes
+
+        self.backbone, self.hidden_dim = _build_backbone(backbone_name, pretrained)
+
+        if freeze_backbone:
+            for param in self.backbone.parameters():
+                param.requires_grad = False
+
+        # 분류 헤드: LayerNorm → Dropout → Linear
+        self.head = nn.Sequential(
+            nn.LayerNorm(self.hidden_dim),
+            nn.Dropout(p=dropout),
+            nn.Linear(self.hidden_dim, num_classes),
+        )
+        self._init_head()
+
+    def _init_head(self):
+        linear = self.head[-1]
+        nn.init.trunc_normal_(linear.weight, std=0.02)
+        nn.init.zeros_(linear.bias)
+
+    # ── Forward ──────────────────────────────────
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        이미지 배치 → CLS 토큰 특징벡터 (B, hidden_dim).
+
+        XAI, 특징 시각화, 임베딩 추출 등에 사용.
+        내부적으로 torchvision ViT의 원본 forward 경로를 그대로 사용:
+            patch_embed → pos_embed → encoder → CLS token
+        """
+        return self.backbone(x)   # Identity heads 덕분에 CLS 벡터 반��
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """logits (B, num_classes) 반환."""
+        return self.head(self.forward_features(x))
+
+    @torch.no_grad()
+    def predict_proba(self, x: torch.Tensor) -> torch.Tensor:
+        """Softmax 확률 (B, num_classes) 반환. 추론 전용."""
+        self.eval()
+        return torch.softmax(self(x), dim=-1)
+
+    # ── 파라미터 정보 ─────────────────────────────
+
+    def trainable_params(self) -> int:
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)
+
+    def total_params(self) -> int:
+        return sum(p.numel() for p in self.parameters())
+
+    def param_summary(self) -> str:
+        trainable = self.trainable_params()
+        total = self.total_params()
+        return (
+            f"[{self.backbone_name}] "
+            f"전체 {total:,} | 학습 가능 {trainable:,} "
+            f"({100 * trainable / total:.1f}%)"
+        )

src/training/__init__.py

@@ -0,0 +1,2 @@
+from .trainer import Trainer, EarlyStopping
+from .metrics import compute_metrics, format_metrics

src/training/metrics.py

@@ -0,0 +1,180 @@
+"""
+분류 성능 지표 계산.
+
+출력 형식 (dict):
+    {
+        "loss":      float,
+        "accuracy":  float,
+        "precision": float,
+        "recall":    float,
+        "f1":        float,
+        "confusion_matrix": [[TP, FP], [FN, TN]] 형식 2x2 리스트
+    }
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import numpy as np
+from sklearn.metrics import (
+    accuracy_score,
+    precision_score,
+    recall_score,
+    f1_score,
+    confusion_matrix,
+)
+
+
+def compute_metrics(
+    preds: List[int] | np.ndarray,
+    labels: List[int] | np.ndarray,
+    loss: float = 0.0,
+    pos_label: int = 1,
+) -> dict:
+    """
+    예측값과 정답 라벨로 분류 지표를 계산한다.
+
+    Args:
+        preds:     모델 예측 클래스 (0 또는 1)
+        labels:    정답 라벨
+        loss:      해당 epoch/step의 평균 loss
+        pos_label: positive 클래스 번호 (fake=1)
+
+    Returns:
+        지표 딕셔너리
+    """
+    preds = np.array(preds)
+    labels = np.array(labels)
+
+    acc = accuracy_score(labels, preds)
+    prec = precision_score(labels, preds, pos_label=pos_label,
+                           zero_division=0, average="binary")
+    rec = recall_score(labels, preds, pos_label=pos_label,
+                       zero_division=0, average="binary")
+    f1 = f1_score(labels, preds, pos_label=pos_label,
+                  zero_division=0, average="binary")
+    cm = confusion_matrix(labels, preds, labels=[0, 1]).tolist()
+
+    return {
+        "loss":             round(loss, 6),
+        "accuracy":         round(acc, 6),
+        "precision":        round(prec, 6),
+        "recall":           round(rec, 6),
+        "f1":               round(f1, 6),
+        "confusion_matrix": cm,
+    }
+
+
+def compute_metrics_from_probs(
+    prob_fake: List[float] | np.ndarray,
+    labels: List[int] | np.ndarray,
+    threshold: float = 0.5,
+    loss: float = 0.0,
+) -> dict:
+    """
+    fake(1) probability and threshold based binary metrics.
+
+    This keeps the default 0.5 behavior available while allowing validation-set
+    calibration to reduce real->fake false positives or balance both classes.
+    """
+    prob_fake = np.asarray(prob_fake, dtype=np.float32)
+    labels = np.asarray(labels)
+    preds = (prob_fake >= threshold).astype(np.int64)
+
+    metrics = compute_metrics(preds, labels, loss=loss)
+    cm = np.asarray(metrics["confusion_matrix"], dtype=np.int64)
+    real_total = max(int(cm[0].sum()), 1)
+    fake_total = max(int(cm[1].sum()), 1)
+    real_acc = float(cm[0, 0] / real_total)
+    fake_acc = float(cm[1, 1] / fake_total)
+    fpr = float(cm[0, 1] / real_total)
+    fnr = float(cm[1, 0] / fake_total)
+    macro_f1 = float(f1_score(labels, preds, average="macro", zero_division=0))
+    balanced_accuracy = (real_acc + fake_acc) / 2.0
+    worst_class_accuracy = min(real_acc, fake_acc)
+    error_balance_penalty = abs(fpr - fnr)
+    deployment_score = (
+        0.45 * balanced_accuracy
+        + 0.35 * macro_f1
+        + 0.20 * worst_class_accuracy
+        - 0.20 * error_balance_penalty
+    )
+    real_guarded_score = (
+        0.40 * balanced_accuracy
+        + 0.25 * macro_f1
+        + 0.25 * real_acc
+        + 0.10 * worst_class_accuracy
+        - 0.25 * fpr
+        - 0.10 * error_balance_penalty
+    )
+
+    metrics.update({
+        "threshold": round(float(threshold), 6),
+        "real_accuracy": round(real_acc, 6),
+        "fake_accuracy": round(fake_acc, 6),
+        "balanced_accuracy": round(balanced_accuracy, 6),
+        "worst_class_accuracy": round(worst_class_accuracy, 6),
+        "macro_f1": round(macro_f1, 6),
+        "fpr": round(fpr, 6),
+        "fnr": round(fnr, 6),
+        "error_balance_gap": round(error_balance_penalty, 6),
+        "deployment_score": round(deployment_score, 6),
+        "real_guarded_score": round(real_guarded_score, 6),
+    })
+    return metrics
+
+
+def find_best_threshold(
+    prob_fake: List[float] | np.ndarray,
+    labels: List[int] | np.ndarray,
+    min_threshold: float = 0.05,
+    max_threshold: float = 0.95,
+    step: float = 0.005,
+    objective: str = "macro_f1",
+    max_fpr: float | None = None,
+) -> dict:
+    """Sweep thresholds and return the best metrics.
+
+    When max_fpr is provided, prefer candidates that satisfy the real->fake
+    false-positive constraint. If no threshold can satisfy it, fall back to the
+    unconstrained optimum and mark the result so the caller can see the miss.
+    """
+    best = None
+    best_unconstrained = None
+    for threshold in np.arange(min_threshold, max_threshold + 1e-12, step):
+        metrics = compute_metrics_from_probs(
+            prob_fake=prob_fake,
+            labels=labels,
+            threshold=float(threshold),
+        )
+        if objective not in metrics:
+            raise ValueError(
+                f"Unknown threshold objective '{objective}'. "
+                f"Available keys: {sorted(metrics.keys())}"
+            )
+        if best_unconstrained is None or metrics[objective] > best_unconstrained[objective]:
+            best_unconstrained = metrics
+        if max_fpr is not None and metrics["fpr"] > max_fpr:
+            continue
+        if best is None or metrics[objective] > best[objective]:
+            best = metrics
+    constraint_satisfied = best is not None
+    if best is None:
+        best = best_unconstrained
+    if best is not None:
+        best["threshold_max_fpr"] = None if max_fpr is None else round(float(max_fpr), 6)
+        best["threshold_fpr_constraint_satisfied"] = bool(constraint_satisfied)
+    return best
+
+
+def format_metrics(metrics: dict, prefix: str = "") -> str:
+    """지표를 한 줄 문자열로 포맷팅."""
+    p = f"{prefix} " if prefix else ""
+    return (
+        f"{p}loss={metrics['loss']:.4f}  "
+        f"acc={metrics['accuracy']:.4f}  "
+        f"prec={metrics['precision']:.4f}  "
+        f"rec={metrics['recall']:.4f}  "
+        f"f1={metrics['f1']:.4f}"
+    )

src/training/seed_utils.py

@@ -0,0 +1,51 @@
+"""
+cudnn 재현성 / 성능 모드 설정.
+
+두 모드:
+    reproducible (재현성 우선):
+        benchmark=False, deterministic=True
+        → 동일 seed + 동일 환경이면 결과가 완전히 재현됨
+        → 속도 약 10~30% 저하 (가변 알고리즘 비활성화)
+
+    performance (성능 우선, 기본값):
+        benchmark=True (CUDA), deterministic=False
+        → cuDNN 이 입력 크기에 맞는 최적 커널을 자동 선택
+        → 재현성 보장 안 됨 (비결정적 알고리즘 허용)
+
+Note:
+    benchmark=True + deterministic=True 조합은 PyTorch 에서 지원하지 않음.
+    (공식 권고: 두 옵션은 상호 배타적으로 사용)
+"""
+from __future__ import annotations
+
+import torch
+
+
+def configure_cudnn(reproducible: bool) -> dict:
+    """
+    cudnn 설정을 적용하고 실제 적용된 값을 반환한다.
+
+    Args:
+        reproducible: True → 재현성 우선 / False → 성능 우선
+
+    Returns:
+        {"benchmark": bool, "deterministic": bool, "cuda_available": bool}
+    """
+    has_cuda = torch.cuda.is_available()
+
+    if reproducible:
+        benchmark     = False
+        deterministic = True
+    else:
+        # CUDA 없으면 benchmark 옵션 자체가 무의미하므로 False
+        benchmark     = has_cuda
+        deterministic = False
+
+    torch.backends.cudnn.benchmark     = benchmark
+    torch.backends.cudnn.deterministic  = deterministic
+
+    return {
+        "benchmark":     benchmark,
+        "deterministic": deterministic,
+        "cuda_available": has_cuda,
+    }

src/training/trainer.py

@@ -0,0 +1,630 @@
+"""
+학습/평가 루프 + 체크포인트 저장/로드 + Early Stopping.
+
+사용 예:
+    trainer = Trainer(model, optimizer, scheduler, device, cfg)
+    for epoch in range(cfg["training"]["epochs"]):
+        train_m = trainer.train_one_epoch(train_loader, epoch)
+        val_m   = trainer.evaluate(val_loader, epoch)
+        if trainer.early_stopping(val_m["loss"], epoch):
+            break
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import DataLoader
+
+from .metrics import (
+    compute_metrics,
+    compute_metrics_from_probs,
+    find_best_threshold,
+    format_metrics,
+)
+
+
+class FocalCrossEntropyLoss(nn.Module):
+    """
+    Per-sample focal cross entropy for hard real/fake examples.
+
+    Returns a (B,) tensor so the existing OHEM and mean reduction paths keep
+    working exactly like CrossEntropyLoss(reduction="none").
+    """
+
+    def __init__(
+        self,
+        gamma: float = 1.5,
+        weight: Optional[torch.Tensor] = None,
+        label_smoothing: float = 0.0,
+    ):
+        super().__init__()
+        self.gamma = gamma
+        self.label_smoothing = label_smoothing
+        if weight is not None:
+            self.register_buffer("weight", weight)
+        else:
+            self.weight = None
+
+    def forward(self, logits: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+        log_probs = F.log_softmax(logits, dim=-1)
+        log_pt = log_probs.gather(1, targets[:, None]).squeeze(1)
+        pt = log_pt.exp().clamp(min=1e-6, max=1.0)
+        ce = F.cross_entropy(
+            logits,
+            targets,
+            weight=self.weight,
+            label_smoothing=self.label_smoothing,
+            reduction="none",
+        )
+        return ((1.0 - pt) ** self.gamma) * ce
+
+
+class EarlyStopping:
+    """
+    val_loss가 patience 에폭 동안 개선되지 않으면 학습 중단.
+
+    Args:
+        patience:  허용 에폭 수
+        min_delta: 개선으로 인정하는 최소 감소량
+    """
+
+    def __init__(self, patience: int = 5, min_delta: float = 1e-4):
+        self.patience = patience
+        self.min_delta = min_delta
+        self.best_loss = float("inf")
+        self.counter = 0
+        self.should_stop = False
+
+    def __call__(self, val_loss: float) -> bool:
+        if val_loss < self.best_loss - self.min_delta:
+            self.best_loss = val_loss
+            self.counter = 0
+        else:
+            self.counter += 1
+            if self.counter >= self.patience:
+                self.should_stop = True
+        return self.should_stop
+
+
+class Trainer:
+    """
+    ViTClassifier 학습/평가/저장을 담당하는 클래스.
+
+    Args:
+        model:        nn.Module (ViTClassifier 등)
+        optimizer:    torch optimizer
+        scheduler:    lr scheduler (None 허용)
+        device:       torch.device
+        checkpoint_dir: 체크포인트 저장 경로
+        mixed_precision: AMP 사용 여부
+        patience:     EarlyStopping patience
+    """
+
+    def __init__(
+        self,
+        model: nn.Module,
+        optimizer: torch.optim.Optimizer,
+        scheduler=None,
+        device: torch.device = torch.device("cpu"),
+        checkpoint_dir: str = "artifacts/checkpoints",
+        mixed_precision: bool = False,
+        patience: int = 5,
+        label_smoothing: float = 0.0,
+        class_weights: Optional[list] = None,
+        loss_type: str = "ce",
+        focal_gamma: float = 1.5,
+        ohem_ratio: float = 0.0,
+        monitor_metric: str = "loss",
+        monitor_mode: str = "min",
+        checkpoint_calibrated: bool = False,
+        threshold_objective: str = "macro_f1",
+        threshold_min: float = 0.05,
+        threshold_max: float = 0.95,
+        threshold_step: float = 0.005,
+        threshold_max_fpr: float | None = None,
+        max_epoch_checkpoints: int | None = None,
+        aux_loss_weight: float = 0.0,
+        aux_loss_branch_weights: Optional[dict] = None,
+        group_dro_weight: float = 0.0,
+    ):
+        self.model = model.to(device)
+        self.optimizer = optimizer
+        self.scheduler = scheduler
+        self.device = device
+        self.checkpoint_dir = Path(checkpoint_dir)
+        self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
+
+        weight_tensor = None
+        if class_weights is not None:
+            weight_tensor = torch.tensor(class_weights, dtype=torch.float32).to(device)
+            print(f"  [클래스 가중치] real={class_weights[0]:.4f}, fake={class_weights[1]:.4f}")
+        self.criterion = nn.CrossEntropyLoss(
+            label_smoothing=label_smoothing,
+            weight=weight_tensor,
+            reduction="none",   # OHEM을 위해 sample별 loss 필요
+        )
+        self.label_smoothing = label_smoothing
+        self.weight_tensor = weight_tensor
+        self.ohem_ratio = 0.0   # 0.0 = OHEM 비활성, 0.7 = 상위 70% hard sample만 사용
+        loss_type = loss_type.lower()
+        if loss_type == "focal":
+            self.criterion = FocalCrossEntropyLoss(
+                gamma=focal_gamma,
+                weight=weight_tensor,
+                label_smoothing=label_smoothing,
+            )
+            print(f"  [loss] focal cross entropy gamma={focal_gamma:.3f}")
+        elif loss_type == "ce":
+            print("  [loss] cross entropy")
+        else:
+            raise ValueError(f"Unsupported loss_type: {loss_type}")
+        self.ohem_ratio = ohem_ratio
+
+        self.scaler = torch.amp.GradScaler(enabled=mixed_precision)
+        self.mixed_precision = mixed_precision
+        self.early_stopping = EarlyStopping(patience=patience)
+
+        self.best_val_loss = float("inf")
+        self.monitor_metric = monitor_metric
+        self.monitor_mode = monitor_mode.lower()
+        self.checkpoint_calibrated = checkpoint_calibrated
+        self.threshold_objective = threshold_objective
+        self.threshold_min = threshold_min
+        self.threshold_max = threshold_max
+        self.threshold_step = threshold_step
+        self.threshold_max_fpr = threshold_max_fpr
+        self.max_epoch_checkpoints = max_epoch_checkpoints
+        self.aux_loss_weight = float(aux_loss_weight)
+        self.aux_loss_branch_weights = (
+            {str(name): float(weight) for name, weight in aux_loss_branch_weights.items()}
+            if aux_loss_branch_weights
+            else None
+        )
+        self.group_dro_weight = max(0.0, min(1.0, float(group_dro_weight)))
+        if self.group_dro_weight > 0:
+            print(f"  [loss] group DRO worst-source weight={self.group_dro_weight:.3f}")
+        self._last_eval_probs = []
+        self._last_eval_labels = []
+        if self.monitor_mode not in ("min", "max"):
+            raise ValueError(f"monitor_mode must be 'min' or 'max', got {monitor_mode}")
+        self.best_monitor_value = (
+            float("inf") if self.monitor_mode == "min" else -float("inf")
+        )
+        self.best_epoch = -1
+        # 대시보드용 실시간 진행 파일 (checkpoint_dir/../progress.json)
+        self._progress_file = self.checkpoint_dir.parent / "progress.json"
+
+    def _forward_model(self, images: torch.Tensor, want_aux: bool = False):
+        use_aux = self.aux_loss_weight > 0 or bool(self.aux_loss_branch_weights)
+        if want_aux and use_aux and hasattr(self.model, "forward_with_aux"):
+            return self.model.forward_with_aux(images)
+        return self.model(images)
+
+    @staticmethod
+    def _main_logits(output) -> torch.Tensor:
+        if isinstance(output, dict):
+            return output["logits"]
+        return output
+
+    @staticmethod
+    def _unpack_batch(batch):
+        if len(batch) == 3:
+            images, labels, groups = batch
+            return images, labels, groups
+        images, labels = batch
+        return images, labels, None
+
+    def _loss_from_output(
+        self,
+        output,
+        labels: torch.Tensor,
+        groups: torch.Tensor | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        logits = self._main_logits(output)
+        sample_loss = self.criterion(logits, labels)
+        if self.ohem_ratio > 0.0:
+            k = max(1, int(sample_loss.numel() * self.ohem_ratio))
+            primary_loss = sample_loss.topk(k).values.mean()
+        else:
+            primary_loss = sample_loss.mean()
+
+        loss = primary_loss
+        if self.group_dro_weight > 0 and groups is not None:
+            groups = groups.to(labels.device, non_blocking=True)
+            group_losses = []
+            for group_id in torch.unique(groups):
+                mask = groups == group_id
+                if bool(mask.any()):
+                    group_losses.append(sample_loss[mask].mean())
+            if group_losses:
+                worst_group_loss = torch.stack(group_losses).max()
+                loss = (
+                    (1.0 - self.group_dro_weight) * primary_loss
+                    + self.group_dro_weight * worst_group_loss
+                )
+
+        if isinstance(output, dict) and isinstance(output.get("aux_logits"), dict):
+            aux_losses = []
+            for name, aux_logits in output["aux_logits"].items():
+                branch_weight = 1.0
+                if self.aux_loss_branch_weights is not None:
+                    branch_weight = self.aux_loss_branch_weights.get(name, 0.0)
+                if branch_weight > 0:
+                    aux_losses.append(self.criterion(aux_logits, labels).mean() * branch_weight)
+            if aux_losses:
+                loss = loss + self.aux_loss_weight * torch.stack(aux_losses).mean()
+        return logits, loss
+
+    # ──────────────────────────────────────────
+    # 학습 루프
+    # ──────────────────────────────────────────
+
+    def train_one_epoch(self, loader: DataLoader, epoch: int) -> dict:
+        """
+        1 에폭 학습.
+
+        Returns:
+            train 지표 딕셔너리
+        """
+        self.model.train()
+        total_loss = 0.0
+        all_preds, all_labels = [], []
+        t0 = time.time()
+
+        _data_time = 0.0
+        _compute_time = 0.0
+        _t_batch_start = time.time()
+
+        for step, batch in enumerate(loader):
+            images, labels, groups = self._unpack_batch(batch)
+            _data_time += time.time() - _t_batch_start
+
+            _t_compute = time.time()
+            images = images.to(self.device, non_blocking=True)
+            labels = labels.to(self.device, non_blocking=True)
+
+            self.optimizer.zero_grad()
+
+            with torch.amp.autocast(
+                device_type=self.device.type,
+                enabled=self.mixed_precision,
+            ):
+                output = self._forward_model(images, want_aux=True)
+                logits, loss = self._loss_from_output(output, labels, groups=groups)
+
+            self.scaler.scale(loss).backward()
+            self.scaler.unscale_(self.optimizer)
+            torch.nn.utils.clip_grad_norm_(self.model.parameters(), max_norm=1.0)
+            self.scaler.step(self.optimizer)
+            self.scaler.update()
+            _compute_time += time.time() - _t_compute
+
+            total_loss += loss.item()
+            preds = logits.argmax(dim=-1)
+            all_preds.extend(preds.cpu().tolist())
+            all_labels.extend(labels.cpu().tolist())
+
+            if step % 10 == 0:
+                _avg_data = _data_time / (step + 1)
+                _avg_comp = _compute_time / (step + 1)
+                print(
+                    f"  [E{epoch+1}] step {step+1}/{len(loader)}  "
+                    f"loss={loss.item():.4f}  "
+                    f"data={_avg_data*1000:.0f}ms  compute={_avg_comp*1000:.0f}ms",
+                    end="\r",
+                )
+                # 대시보드용 실시간 progress 기록 (매 10 step)
+                try:
+                    import json as _json
+                    self._progress_file.write_text(_json.dumps({
+                        "epoch": epoch + 1,
+                        "step": step + 1,
+                        "total_steps": len(loader),
+                        "loss": round(loss.item(), 4),
+                        "phase": "train",
+                        "data_ms": round(_avg_data * 1000, 1),
+                        "compute_ms": round(_avg_comp * 1000, 1),
+                    }), encoding="utf-8")
+                except Exception:
+                    pass
+
+            _t_batch_start = time.time()
+
+        if self.scheduler is not None:
+            self.scheduler.step()
+
+        avg_loss = total_loss / len(loader)
+        metrics = compute_metrics(all_preds, all_labels, loss=avg_loss)
+        elapsed = time.time() - t0
+        print(f"\n  [E{epoch+1} TRAIN] {format_metrics(metrics)}  ({elapsed:.1f}s)")
+        return metrics
+
+    # ──────────────────────────────────────────
+    # 평가 루프
+    # ──────────────────────────────────────────
+
+    @torch.no_grad()
+    def evaluate(
+        self,
+        loader: DataLoader,
+        epoch: int,
+        tag: str = "VAL",
+        threshold: float = 0.5,
+    ) -> dict:
+        """
+        검증/테스트 평가.
+
+        Returns:
+            평가 지표 딕셔너리
+        """
+        self.model.eval()
+        total_loss = 0.0
+        all_probs, all_labels = [], []
+        all_groups = []
+
+        for batch in loader:
+            images, labels, _groups = self._unpack_batch(batch)
+            images = images.to(self.device, non_blocking=True)
+            labels = labels.to(self.device, non_blocking=True)
+
+            with torch.amp.autocast(
+                device_type=self.device.type,
+                enabled=self.mixed_precision,
+            ):
+                logits = self._main_logits(self._forward_model(images, want_aux=False))
+                loss = self.criterion(logits, labels).mean()
+
+            total_loss += loss.item()
+            prob_fake = torch.softmax(logits.float(), dim=-1)[:, 1]
+            all_probs.extend(prob_fake.cpu().tolist())
+            all_labels.extend(labels.cpu().tolist())
+            if _groups is not None:
+                all_groups.extend(_groups.cpu().tolist())
+
+        avg_loss = total_loss / len(loader)
+        self._last_eval_probs = all_probs
+        self._last_eval_labels = all_labels
+        metrics = compute_metrics_from_probs(
+            all_probs,
+            all_labels,
+            threshold=threshold,
+            loss=avg_loss,
+        )
+        if all_groups and len(all_groups) == len(all_labels):
+            reverse_group_map = {}
+            dataset = getattr(loader, "dataset", None)
+            group_to_id = getattr(dataset, "group_to_id", None)
+            if isinstance(group_to_id, dict):
+                reverse_group_map = {int(value): str(key) for key, value in group_to_id.items()}
+            source_metrics = {}
+            for group_id in sorted(set(int(group) for group in all_groups)):
+                indices = [idx for idx, group in enumerate(all_groups) if int(group) == group_id]
+                if not indices:
+                    continue
+                name = reverse_group_map.get(group_id, f"group_{group_id}")
+                source_metrics[name] = {
+                    "count": len(indices),
+                    **compute_metrics_from_probs(
+                        [all_probs[idx] for idx in indices],
+                        [all_labels[idx] for idx in indices],
+                        threshold=threshold,
+                    ),
+                }
+            metrics["source_metrics"] = source_metrics
+        print(f"  [E{epoch+1}  {tag} ] {format_metrics(metrics)}  thr={threshold:.3f}")
+        return metrics
+
+    @torch.no_grad()
+    def calibrate_threshold(
+        self,
+        loader: DataLoader,
+        objective: str = "macro_f1",
+        min_threshold: float = 0.05,
+        max_threshold: float = 0.95,
+        step: float = 0.005,
+    ) -> dict:
+        """Find the best fake-probability threshold on a validation loader."""
+        self.model.eval()
+        all_probs, all_labels = [], []
+
+        for batch in loader:
+            images, labels, _groups = self._unpack_batch(batch)
+            images = images.to(self.device, non_blocking=True)
+            with torch.amp.autocast(
+                device_type=self.device.type,
+                enabled=self.mixed_precision,
+            ):
+                logits = self._main_logits(self._forward_model(images, want_aux=False))
+            prob_fake = torch.softmax(logits.float(), dim=-1)[:, 1]
+            all_probs.extend(prob_fake.cpu().tolist())
+            all_labels.extend(labels.tolist())
+
+        metrics = find_best_threshold(
+            all_probs,
+            all_labels,
+            min_threshold=min_threshold,
+            max_threshold=max_threshold,
+            step=step,
+            objective=objective,
+            max_fpr=self.threshold_max_fpr,
+        )
+        print(
+            f"  [THRESHOLD] objective={objective} best={metrics['threshold']:.3f} "
+            f"macro_f1={metrics['macro_f1']:.4f} "
+            f"bal_acc={metrics['balanced_accuracy']:.4f} "
+            f"fpr={metrics['fpr']:.4f} fnr={metrics['fnr']:.4f}"
+        )
+        return metrics
+
+    # ──────────────────────────────────────────
+    # 체크포인트
+    # ──────────────────────────────────────────
+
+    def save_checkpoint(
+        self,
+        epoch: int,
+        metrics: dict,
+        filename: Optional[str] = None,
+    ) -> Path:
+        """
+        체크포인트 저장.
+
+        파일명이 없으면 "best.pt"를 덮어쓴다.
+        val_loss가 최고 기록을 갱신할 때 "best.pt"를 저장하는 용도로 설계됨.
+        """
+        if filename is None:
+            filename = "best.pt"
+        path = self.checkpoint_dir / filename
+
+        torch.save(
+            {
+                "epoch": epoch,
+                "model_state_dict": self.model.state_dict(),
+                "optimizer_state_dict": self.optimizer.state_dict(),
+                "scheduler_state_dict": (
+                    self.scheduler.state_dict() if self.scheduler else None
+                ),
+                "metrics": metrics,
+            },
+            path,
+        )
+        print(f"  [저장] {path}  (val_loss={metrics.get('loss', '?'):.4f})")
+        return path
+
+    def load_checkpoint(
+        self,
+        path: str,
+        load_optimizer: bool = True,
+        load_scheduler: bool = True,
+    ) -> dict:
+        """
+        체크포인트 로드. 저장된 metrics 딕셔너리를 반환한다.
+        """
+        ckpt = torch.load(path, map_location=self.device, weights_only=True)
+        self.model.load_state_dict(ckpt["model_state_dict"])
+        if load_optimizer and ckpt.get("optimizer_state_dict"):
+            self.optimizer.load_state_dict(ckpt["optimizer_state_dict"])
+        if load_scheduler and self.scheduler and ckpt.get("scheduler_state_dict"):
+            self.scheduler.load_state_dict(ckpt["scheduler_state_dict"])
+        epoch = ckpt.get("epoch", -1)
+        metrics = ckpt.get("metrics", {})
+        print(f"  [로드] {path}  epoch={epoch}  metrics={metrics}")
+        return metrics
+
+    def _prune_epoch_checkpoints(self) -> None:
+        if not self.max_epoch_checkpoints or self.max_epoch_checkpoints <= 0:
+            return
+        epoch_files = sorted(
+            self.checkpoint_dir.glob("epoch_*.pt"),
+            key=lambda path: path.stat().st_mtime,
+        )
+        excess = len(epoch_files) - self.max_epoch_checkpoints
+        if excess <= 0:
+            return
+        for path in epoch_files[:excess]:
+            try:
+                path.unlink()
+                print(f"  [prune] removed old checkpoint {path.name}")
+            except OSError as exc:
+                print(f"  [prune warning] could not remove {path.name}: {exc}")
+
+    # ──────────────────────────────────────────
+    # 통합 루프 헬퍼
+    # ──────────────────────────────────────────
+
+    def fit(
+        self,
+        train_loader: DataLoader,
+        val_loader: DataLoader,
+        epochs: int,
+    ) -> list[dict]:
+        """
+        전체 학습 루프.
+
+        Returns:
+            에폭별 {'train': {...}, 'val': {...}} 기록 리스트
+        """
+        history = []
+
+        for epoch in range(epochs):
+            print(f"\n{'─'*60}")
+            train_m = self.train_one_epoch(train_loader, epoch)
+            val_m = self.evaluate(val_loader, epoch, tag="VAL")
+
+            if self.checkpoint_calibrated:
+                calibrated_m = find_best_threshold(
+                    self._last_eval_probs,
+                    self._last_eval_labels,
+                    min_threshold=self.threshold_min,
+                    max_threshold=self.threshold_max,
+                    step=self.threshold_step,
+                    objective=self.threshold_objective,
+                    max_fpr=self.threshold_max_fpr,
+                )
+                for key, value in calibrated_m.items():
+                    val_m[f"calibrated_{key}"] = value
+                print(
+                    f"  [CAL VAL] best_thr={calibrated_m['threshold']:.3f} "
+                    f"deploy={calibrated_m['deployment_score']:.6f} "
+                    f"macro_f1={calibrated_m['macro_f1']:.6f} "
+                    f"real_acc={calibrated_m['real_accuracy']:.6f} "
+                    f"fake_acc={calibrated_m['fake_accuracy']:.6f}"
+                )
+
+            monitor_value = val_m.get(self.monitor_metric)
+            if monitor_value is None:
+                raise KeyError(
+                    f"monitor_metric '{self.monitor_metric}' not found in val metrics: "
+                    f"{sorted(val_m.keys())}"
+                )
+            is_best = (
+                monitor_value < self.best_monitor_value
+                if self.monitor_mode == "min"
+                else monitor_value > self.best_monitor_value
+            )
+            if is_best:
+                self.best_monitor_value = monitor_value
+                self.best_val_loss = val_m["loss"]
+                self.best_epoch = epoch
+                self.save_checkpoint(epoch, val_m, filename="best.pt")
+                print(
+                    f"  [best] {self.monitor_metric}={monitor_value:.6f} "
+                    f"mode={self.monitor_mode}"
+                )
+
+            # 에폭 체크포인트 (매 에폭)
+            self.save_checkpoint(epoch, val_m, filename=f"epoch_{epoch+1:03d}.pt")
+            self._prune_epoch_checkpoints()
+
+            history.append({"epoch": epoch + 1, "train": train_m, "val": val_m})
+            try:
+                import json as _json
+
+                history_path = self.checkpoint_dir.parent / "history.json"
+                history_path.write_text(
+                    _json.dumps(history, ensure_ascii=False, indent=2),
+                    encoding="utf-8",
+                )
+            except Exception:
+                pass
+
+            # Early stopping
+            if self.early_stopping(val_m["loss"]):
+                print(
+                    f"\n[Early Stopping] {self.early_stopping.patience} 에폭 개선 없음."
+                    f" best epoch={self.best_epoch+1}"
+                )
+                break
+
+        print(
+            f"\n학습 완료. best epoch={self.best_epoch+1}  "
+            f"best {self.monitor_metric}={self.best_monitor_value:.6f}  "
+            f"best val_loss={self.best_val_loss:.4f}"
+        )
+        return history

src/xai/__init__.py

@@ -0,0 +1,3 @@
+from .visual_explainer import ExplainResult, explain_image, png_b64
+
+__all__ = ["ExplainResult", "explain_image", "png_b64"]

src/xai/visual_explainer.py

@@ -0,0 +1,359 @@
+"""Visual explanations for A-EYE detector models.
+
+The maps produced here are class-discriminative evidence maps. They show which
+image regions increased the model's AI/fake logit; they are not pixel-perfect
+manipulation masks.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image, ImageFilter, ImageOps
+
+
+@dataclass
+class ExplainResult:
+    heatmap: Image.Image
+    overlay: Image.Image
+    meta: dict[str, Any]
+    raw_map: np.ndarray
+
+
+def png_b64(image: Image.Image) -> str:
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def _normalize_map(cam: np.ndarray) -> np.ndarray:
+    cam = np.nan_to_num(cam.astype(np.float32), nan=0.0, posinf=0.0, neginf=0.0)
+    cam -= float(cam.min())
+    peak = float(cam.max())
+    if peak <= 1e-7:
+        return np.zeros_like(cam, dtype=np.float32)
+    return np.clip(cam / peak, 0.0, 1.0)
+
+
+def _last_conv(module: nn.Module | None) -> nn.Conv2d | None:
+    if module is None:
+        return None
+    for child in reversed(list(module.modules())):
+        if isinstance(child, nn.Conv2d):
+            return child
+    return None
+
+
+def _vit_token_target(model: nn.Module) -> nn.Module | None:
+    vit = getattr(model, "vit_encoder", None)
+    backbone = getattr(vit, "backbone", None)
+    encoder = getattr(backbone, "encoder", None)
+    layers = getattr(encoder, "layers", None)
+    if layers is None:
+        return None
+    try:
+        return layers[-1]
+    except Exception:
+        children = list(layers.children())
+        return children[-1] if children else None
+
+
+def _xai_targets(model: nn.Module) -> list[tuple[str, str, nn.Module]]:
+    targets: list[tuple[str, str, nn.Module]] = []
+
+    vit_target = _vit_token_target(model)
+    if vit_target is not None:
+        targets.append(("vit_patch_gradcam", "tokens", vit_target))
+
+    srm = getattr(model, "srm_branch", None)
+    srm_target = _last_conv(getattr(srm, "encoder", None))
+    if srm_target is not None:
+        targets.append(("srm_residual_gradcam", "conv", srm_target))
+
+    return targets
+
+
+def _cam_from_conv(activation: torch.Tensor, gradient: torch.Tensor, size: tuple[int, int]) -> np.ndarray | None:
+    if activation.ndim != 4 or gradient.ndim != 4:
+        return None
+    weights = gradient.mean(dim=(2, 3), keepdim=True)
+    cam = F.relu((activation * weights).sum(dim=1, keepdim=True))
+    cam = F.interpolate(cam, size=size, mode="bilinear", align_corners=False)
+    return _normalize_map(cam[0, 0].detach().float().cpu().numpy())
+
+
+def _cam_from_tokens(activation: torch.Tensor, gradient: torch.Tensor, size: tuple[int, int]) -> np.ndarray | None:
+    if activation.ndim != 3 or gradient.ndim != 3 or activation.shape[1] < 2:
+        return None
+
+    tokens = activation[:, 1:, :]
+    grads = gradient[:, 1:, :]
+    patch_count = tokens.shape[1]
+    grid = int(round(patch_count ** 0.5))
+    if grid * grid != patch_count:
+        return None
+
+    # Grad x activation works better than pure attention rollout here because it
+    # is class-discriminative for the fake logit.
+    cam = F.relu((tokens * grads).sum(dim=-1)).view(activation.shape[0], 1, grid, grid)
+    cam = F.interpolate(cam, size=size, mode="bilinear", align_corners=False)
+    return _normalize_map(cam[0, 0].detach().float().cpu().numpy())
+
+
+def _input_gradient_map(tensor: torch.Tensor, size: tuple[int, int]) -> np.ndarray | None:
+    grad = tensor.grad
+    if grad is None or grad.ndim != 4:
+        return None
+    cam = grad.detach().float().abs().mean(dim=1, keepdim=True)
+    cam = F.interpolate(cam, size=size, mode="bilinear", align_corners=False)
+    return _normalize_map(cam[0, 0].cpu().numpy())
+
+
+def _forward_logits(model: nn.Module, batch: torch.Tensor) -> torch.Tensor:
+    output = model(batch)
+    return output["logits"] if isinstance(output, dict) else output
+
+
+def _class_margin(logits: torch.Tensor, target_class: int) -> torch.Tensor:
+    if logits.shape[-1] >= 2:
+        other = 1 - int(target_class)
+        return logits[:, int(target_class)] - logits[:, other]
+    return logits[:, int(target_class)]
+
+
+@torch.no_grad()
+def _occlusion_sensitivity_map(
+    model: nn.Module,
+    tensor: torch.Tensor,
+    size: tuple[int, int],
+    *,
+    target_class: int = 1,
+    grid: int = 7,
+    batch_size: int = 8,
+) -> np.ndarray | None:
+    """Patch-occlusion map: regions whose blur lowers the fake-class margin."""
+    if tensor.ndim != 4 or tensor.shape[0] != 1:
+        return None
+
+    was_training = model.training
+    model.eval()
+    try:
+        base_logits = _forward_logits(model, tensor)
+        base_score = _class_margin(base_logits.float(), target_class)
+        _, _, height, width = tensor.shape
+
+        kernel = max(7, int(round(min(height, width) * 0.11)))
+        if kernel % 2 == 0:
+            kernel += 1
+        pad = kernel // 2
+        blurred = F.avg_pool2d(
+            F.pad(tensor, (pad, pad, pad, pad), mode="reflect"),
+            kernel_size=kernel,
+            stride=1,
+        )
+
+        variants: list[torch.Tensor] = []
+        boxes: list[tuple[int, int, int, int]] = []
+        for gy in range(grid):
+            y0 = round(gy * height / grid)
+            y1 = round((gy + 1) * height / grid)
+            for gx in range(grid):
+                x0 = round(gx * width / grid)
+                x1 = round((gx + 1) * width / grid)
+                variant = tensor.detach().clone()
+                variant[:, :, y0:y1, x0:x1] = blurred[:, :, y0:y1, x0:x1]
+                variants.append(variant)
+                boxes.append((y0, y1, x0, x1))
+
+        drops: list[float] = []
+        for start in range(0, len(variants), batch_size):
+            batch = torch.cat(variants[start : start + batch_size], dim=0)
+            logits = _forward_logits(model, batch)
+            scores = _class_margin(logits.float(), target_class)
+            delta = (base_score - scores).detach().cpu().numpy()
+            drops.extend(float(v) for v in delta)
+
+        patch_map = torch.zeros((1, 1, height, width), device=tensor.device, dtype=torch.float32)
+        for drop, (y0, y1, x0, x1) in zip(drops, boxes):
+            if drop > 0:
+                patch_map[:, :, y0:y1, x0:x1] = max(
+                    float(drop),
+                    float(patch_map[:, :, y0:y1, x0:x1].max()),
+                )
+
+        patch_map = F.interpolate(patch_map, size=size, mode="bilinear", align_corners=False)
+        arr = patch_map[0, 0].detach().cpu().numpy()
+        if float(np.max(arr)) <= 1e-7:
+            return None
+        return _normalize_map(arr)
+    finally:
+        model.train(was_training)
+
+
+def _fallback_residual_map(rgb: Image.Image, size: tuple[int, int]) -> np.ndarray:
+    small = rgb.resize((size[1], size[0]), Image.Resampling.BICUBIC).convert("L")
+    blur = small.filter(ImageFilter.GaussianBlur(radius=2.4))
+    arr = np.asarray(small, dtype=np.float32) / 255.0
+    low = np.asarray(blur, dtype=np.float32) / 255.0
+    return _normalize_map(np.abs(arr - low))
+
+
+def _object_expand(cam: np.ndarray, expansion: float = 1.0) -> np.ndarray:
+    cam = _normalize_map(cam)
+    image = Image.fromarray(np.uint8(cam * 255), "L")
+    max_size = max(3, int(round(5 + expansion * 6)))
+    if max_size % 2 == 0:
+        max_size += 1
+    expanded = image.filter(ImageFilter.MaxFilter(max_size)).filter(
+        ImageFilter.GaussianBlur(radius=2.2 + 1.7 * expansion)
+    )
+    smooth = image.filter(ImageFilter.GaussianBlur(radius=1.3 + 0.8 * expansion))
+    arr = np.asarray(expanded, dtype=np.float32) / 255.0
+    sm = np.asarray(smooth, dtype=np.float32) / 255.0
+    return _normalize_map(arr * 0.58 + sm * 0.42)
+
+
+def _cam_to_heatmap(cam: np.ndarray, size: tuple[int, int]) -> Image.Image:
+    cam = _normalize_map(cam)
+    if cam.shape[::-1] != size:
+        image = Image.fromarray(np.uint8(cam * 255), "L").resize(size, Image.Resampling.BICUBIC)
+        cam = np.asarray(image, dtype=np.float32) / 255.0
+
+    anchors = np.array(
+        [
+            [4, 8, 18],
+            [22, 80, 190],
+            [30, 210, 220],
+            [255, 218, 54],
+            [255, 42, 24],
+        ],
+        dtype=np.float32,
+    )
+    positions = np.linspace(0.0, 1.0, len(anchors), dtype=np.float32)
+    rgb = np.zeros((*cam.shape, 3), dtype=np.float32)
+    for channel in range(3):
+        rgb[..., channel] = np.interp(cam, positions, anchors[:, channel])
+    return Image.fromarray(np.uint8(np.clip(rgb, 0, 255)), "RGB")
+
+
+def _overlay_heatmap(original: Image.Image, heatmap: Image.Image, alpha: float = 1.0) -> Image.Image:
+    base = original.convert("RGBA")
+    heat_rgb = heatmap.convert("RGB").resize(base.size)
+    heat_arr = np.asarray(heat_rgb, dtype=np.float32)
+    score = _normalize_map(np.maximum(heat_arr[..., 0], heat_arr[..., 1]) - heat_arr[..., 2] * 0.35)
+    focus = np.clip((score - 0.18) / 0.82, 0.0, 1.0) ** 1.35
+    alpha_arr = np.uint8(np.clip(focus * 218 * alpha, 0, 218))
+    heat = Image.fromarray(np.dstack([heat_arr.astype(np.uint8), alpha_arr]), "RGBA")
+    return Image.alpha_composite(base, heat).convert("RGB")
+
+
+def explain_image(
+    model: nn.Module,
+    transform,
+    device: torch.device | str,
+    image: Image.Image,
+    *,
+    target_class: int = 1,
+    expansion: float = 1.0,
+) -> ExplainResult:
+    rgb = ImageOps.exif_transpose(image).convert("RGB")
+    device = torch.device(device)
+    tensor = transform(rgb).unsqueeze(0).to(device)
+    targets = _xai_targets(model)
+
+    captured: dict[str, dict[str, torch.Tensor | str]] = {}
+    handles = []
+
+    def make_hook(name: str, kind: str):
+        def hook(_module, _inputs, output):
+            if isinstance(output, (tuple, list)):
+                output = output[0]
+            if not isinstance(output, torch.Tensor) or not output.requires_grad:
+                return
+            captured[name] = {"activation": output, "kind": kind}
+            output.register_hook(lambda grad, key=name: captured[key].__setitem__("gradient", grad))
+
+        return hook
+
+    for name, kind, module in targets:
+        handles.append(module.register_forward_hook(make_hook(name, kind)))
+
+    maps: dict[str, np.ndarray] = {}
+    logits = None
+    try:
+        model.zero_grad(set_to_none=True)
+        tensor = tensor.detach().clone().requires_grad_(True)
+        with torch.enable_grad():
+            output = model(tensor)
+            logits = output["logits"] if isinstance(output, dict) else output
+            target = logits[:, int(target_class)].sum()
+            target.backward()
+    finally:
+        for handle in handles:
+            handle.remove()
+
+    size = tuple(int(v) for v in tensor.shape[-2:])
+    for name, data in captured.items():
+        activation = data.get("activation")
+        gradient = data.get("gradient")
+        kind = data.get("kind")
+        if not isinstance(activation, torch.Tensor) or not isinstance(gradient, torch.Tensor):
+            continue
+        if kind == "tokens":
+            cam = _cam_from_tokens(activation, gradient, size)
+        elif kind == "conv":
+            cam = _cam_from_conv(activation, gradient, size)
+        else:
+            cam = None
+        if cam is not None:
+            maps[name] = cam
+
+    input_map = _input_gradient_map(tensor, size)
+    if input_map is not None:
+        maps["input_gradient"] = input_map
+
+    occlusion_map = _occlusion_sensitivity_map(model, tensor.detach(), size, target_class=target_class)
+    if occlusion_map is not None:
+        maps["occlusion_drop"] = occlusion_map
+
+    if not maps:
+        maps["image_highpass_residual"] = _fallback_residual_map(rgb, size)
+
+    weights = {
+        "occlusion_drop": 0.55,
+        "vit_patch_gradcam": 0.25,
+        "srm_residual_gradcam": 0.12,
+        "input_gradient": 0.08,
+        "image_highpass_residual": 0.30,
+    }
+    combined = np.zeros_like(next(iter(maps.values())), dtype=np.float32)
+    total_weight = 0.0
+    for name, cam in maps.items():
+        weight = weights.get(name, 0.15)
+        combined += cam * weight
+        total_weight += weight
+    combined = _normalize_map(combined / max(total_weight, 1e-6))
+    expanded = _object_expand(combined, expansion=expansion)
+
+    heatmap = _cam_to_heatmap(expanded, rgb.size)
+    overlay = _overlay_heatmap(rgb, heatmap)
+    probs = None
+    if isinstance(logits, torch.Tensor):
+        probs = torch.softmax(logits.detach().float(), dim=-1)[0].cpu().tolist()
+    meta = {
+        "method": "occlusion_vit_srm_inputgrad",
+        "target_class": "fake" if int(target_class) == 1 else "real",
+        "branches": list(maps.keys()),
+        "heatmap_policy": "occlusion-weighted expanded evidence map",
+        "fake_prob": None if probs is None or len(probs) < 2 else float(probs[1]),
+        "note_ko": "붉고 노란 부분은 해당 영역을 흐리게 가렸을 때 AI 판정 점수가 많이 떨어진 위치입니다.",
+        "limitation_ko": "이 히트맵은 모델 판단 근거이지 실제 합성/수정 픽셀 마스크는 아닙니다. 사람이나 고양이 전체를 정확히 칠하려면 별도 객체 분할 또는 위치 라벨 학습이 필요합니다.",
+    }
+    return ExplainResult(heatmap=heatmap, overlay=overlay, meta=meta, raw_map=expanded)