Add/Update backbone checkpoints (count=6)

manifest_20260210_111913.json

@@ -0,0 +1,41 @@
+{
+  "timestamp": "20260210_111913",
+  "device": "mps",
+  "repo_id": "dsaint31/bb_mlp_224",
+  "revision": "main",
+  "tag": null,
+  "num_labels": 3,
+  "count": 6,
+  "items": [
+    {
+      "backbone": "google/vit-base-patch16-224",
+      "subdir": "models/google__vit-base-patch16-224",
+      "dirname": "google__vit-base-patch16-224"
+    },
+    {
+      "backbone": "microsoft/swin-tiny-patch4-window7-224",
+      "subdir": "models/microsoft__swin-tiny-patch4-window7-224",
+      "dirname": "microsoft__swin-tiny-patch4-window7-224"
+    },
+    {
+      "backbone": "microsoft/resnet-50",
+      "subdir": "models/microsoft__resnet-50",
+      "dirname": "microsoft__resnet-50"
+    },
+    {
+      "backbone": "google/efficientnet-b0",
+      "subdir": "models/google__efficientnet-b0",
+      "dirname": "google__efficientnet-b0"
+    },
+    {
+      "backbone": "timm/densenet121.tv_in1k",
+      "subdir": "models/timm__densenet121.tv_in1k",
+      "dirname": "timm__densenet121.tv_in1k"
+    },
+    {
+      "backbone": "torchvision/densenet121",
+      "subdir": "models/torchvision__densenet121",
+      "dirname": "torchvision__densenet121"
+    }
+  ]
+}

models/google__efficientnet-b0/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/google__efficientnet-b0",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "google/efficientnet-b0",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/google__efficientnet-b0/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/google__efficientnet-b0/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/google__efficientnet-b0/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/google__efficientnet-b0/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:a67fc215d299f5fe53f61da21d454c40f414d1221ff57167797cc276ee5e2991
+oid sha256:01add885928661dde020c6cc5adaf1e6b8d6684a9effa7ef2903ac8d03fc9a5c
 size 17558436

models/google__efficientnet-b0/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "google/efficientnet-b0",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}

models/google__vit-base-patch16-224/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/google__vit-base-patch16-224",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "google/vit-base-patch16-224",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/google__vit-base-patch16-224/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/google__vit-base-patch16-224/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/google__vit-base-patch16-224/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/google__vit-base-patch16-224/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3d8f30959f7f4875a6e7792d2e5d27ec06ea99c166fbe9bdb9aab09173fa784d
+oid sha256:5ca403809fcb589b9b176f4712c6f6aa3c31d2cb7465aaaa6cd4391d46947e8e
 size 346372132

models/google__vit-base-patch16-224/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "google/vit-base-patch16-224",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}

models/microsoft__resnet-50/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/microsoft__resnet-50",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "microsoft/resnet-50",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/microsoft__resnet-50/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/microsoft__resnet-50/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/microsoft__resnet-50/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/microsoft__resnet-50/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:12f287e717506b8e251dddbc02e8471a753795da5c1ea503c3491817f61f8c63
+oid sha256:229f77319aec60efa8fff986455e304b9f4f2d46440550b69490da095a11d170
 size 96388660

models/microsoft__resnet-50/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "microsoft/resnet-50",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}

models/microsoft__swin-tiny-patch4-window7-224/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/microsoft__swin-tiny-patch4-window7-224",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "microsoft/swin-tiny-patch4-window7-224",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/microsoft__swin-tiny-patch4-window7-224/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/microsoft__swin-tiny-patch4-window7-224/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/microsoft__swin-tiny-patch4-window7-224/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/microsoft__swin-tiny-patch4-window7-224/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:045a8d82d86041b915ef92e1bfc62b1ff3dd85e034f87025c9e6e68d018c40ba
+oid sha256:61d4b000d39bc1301116050226ee05a3cc3851359f4dc38febbb5f397fbb844f
 size 111128348

models/microsoft__swin-tiny-patch4-window7-224/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "microsoft/swin-tiny-patch4-window7-224",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}

models/timm__densenet121.tv_in1k/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/timm__densenet121.tv_in1k",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "timm/densenet121.tv_in1k",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/timm__densenet121.tv_in1k/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/timm__densenet121.tv_in1k/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/timm__densenet121.tv_in1k/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/timm__densenet121.tv_in1k/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:5c7a629e31d700969130554fdfe93c8cd2f9344fb865b6903c3df151c0624ec6
+oid sha256:53c62717fc23ff4a775482d0f9ca8c730a2c04681a9eeefa01864847d713aa9f
 size 29293620

models/timm__densenet121.tv_in1k/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "timm/densenet121.tv_in1k",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}

models/torchvision__densenet121/config.json

@@ -24,10 +24,11 @@
   "num_labels": 3,
   "transformers_version": "5.1.0",
   "ds_provenance": {
-    "created_at": "20260210_050905",
+    "created_at": "20260210_111913",
     "repo_id": "dsaint31/bb_mlp_224",
     "subdir": "models/torchvision__densenet121",
     "wrapper_class": "BackboneWithMLPHeadForImageClassification",
+    "processor_class": "BackboneMLPHead224ImageProcessor",
     "backbone_id": "torchvision/densenet121",
     "pretrained_injected": true,
     "policy_init_pretrained_forbidden": true,

models/torchvision__densenet121/ds_cfg.py

@@ -1,84 +1,175 @@
-from typing import Literal, Union
-
-from transformers import AutoConfig
 from transformers import PretrainedConfig
+
 from ds_meta import BackboneID, BACKBONE_META
 
-# ============================================================
-# 3) Config
-# ============================================================
+
 class BackboneMLPHeadConfig(PretrainedConfig):
     """
-    backbone_name_or_path는 BACKBONE_META 키(화이트리스트)만 허용.
-
-    중요한 점
-    ----------
-    - transformers 내부 경로에서 "무인자 생성"이 발생할 수 있으므로,
-      backbone_name_or_path=None인 경우는 검증 없이 기본값만 세팅하고 return
-      하는 구현이 반드시 필요함.
-    - 단, 실제 사용에서는 backbone_name_or_path를 반드시 지정해서 생성해야 함.
+    Configuration for Backbone + MLP Head models.
+
+    Backbone + MLP Head 모델을 위한 설정 클래스입니다.
     """
 
-    # AutoConfig가 이 모델을 식별하는데 사용하는 문자열 ID.
+    # This string is used by Hugging Face AutoConfig to identify the config class.
+    # Hugging Face AutoConfig가 이 config를 식별하기 위해 사용하는 고유 ID입니다.
     model_type = "backbone-mlphead-224-fixed"
 
-    # 생성자에서 모든 인자에 기본값 부여 반드시 필요!
     def __init__(
         self,
         backbone_name_or_path: BackboneID | None = None,
         mlp_head_bottleneck: int = 256,
         mlp_head_dropout: float = 0.2,
-        label2id: dict[str, int]|None = None,
-        id2label: dict[int, str]|None = None,
+        label2id: dict[str, int] | None = None,
+        id2label: dict[int, str] | None = None,
         **kwargs,
     ):
-        # 무인자 생성 경로 방어
+        # ============================================================
+        # 0) Guard for argument-less construction
+        # 0) 무인자 생성 경로 방어
+        # ============================================================
+        # Transformers may internally construct this config without arguments
+        # (e.g., during AutoConfig resolution or Hub loading).
+        # Transformers 내부에서 AutoConfig 또는 Hub 로드 과정 중
+        # 인자 없이 config를 생성하는 경로가 실제로 존재합니다.
+        #
+        # In this case, we must NOT validate or raise errors.
+        # 이 경우 검증이나 예외를 발생시키면 안 됩니다.
+        #
+        # The goal here is to provide a minimal, serialization-safe config.
+        # 목표는 최소한의 값만 채워 직렬화/역직렬화가 깨지지 않게 하는 것입니다.
         if backbone_name_or_path is None:
+            # num_labels may be implicitly assumed by downstream code,
+            # so we explicitly set a safe default.
+            # num_labels는 downstream 코드에서 암묵적으로 가정되므로
+            # 안전한 기본값을 명시적으로 넣어줍니다.
+            if "num_labels" not in kwargs:
+                kwargs["num_labels"] = 0
+
             super().__init__(**kwargs)
+
+            # Backbone is intentionally unset in this path.
+            # 이 경로에서는 backbone을 의도적으로 설정하지 않습니다.
             self.backbone_name_or_path = None
-            self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-            self.mlp_head_dropout      = float(mlp_head_dropout)
-            # num_labels도 기본값 하나 줘서 0 방지(3으로 두든 0으로 두든 정책)
-            # 최소 안전: id2label이 있으면 그 길이, 없으면 0
+
+            # Store MLP head hyperparameters for completeness.
+            # MLP head 관련 하이퍼파라미터는 형태 유지를 위해 저장합니다.
+            self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+            self.mlp_head_dropout = float(mlp_head_dropout)
+
+            # Empty label mappings ensure stable save/load behavior.
+            # 빈 label 매핑은 저장/로드 안정성을 보장합니다.
+            self.label2id = {}
+            self.id2label = {}
+            self.num_labels = int(kwargs.get("num_labels", 0))
             return
 
-        # 화이트리스트 검증
+        # ============================================================
+        # 1) Backbone whitelist validation
+        # 1) Backbone 화이트리스트 검증
+        # ============================================================
+        # Only backbones explicitly registered in BACKBONE_META are allowed.
+        # BACKBONE_META에 등록된 backbone만 허용합니다.
+        #
+        # This prevents accidental usage of unsupported or inconsistent backbones.
+        # 지원되지 않거나 불일치한 backbone 사용을 원천 차단합니다.
         if backbone_name_or_path not in BACKBONE_META:
             raise ValueError(
                 f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
                 f"Allowed: {sorted(BACKBONE_META.keys())}"
             )
-        if id2label is None and label2id is None:
-            raise ValueError("id2label/label2id 둘 중 하나는 필요합니다.")
-        if id2label is None:
-            id2label = {v: k for k, v in label2id.items()}
-        if label2id is None:
-            label2id = {v: k for k, v in id2label.items()}
-
-        num_labels = len(id2label)
-        # kwargs에 이미 num_labels가 있으면 그대로 사용
-        if "num_labels" not in kwargs:
+
+        # ============================================================
+        # 2) Label mapping normalization
+        # 2) 라벨 매핑 정규화
+        # ============================================================
+        # Both label2id and id2label may be None during pure loading scenarios.
+        # 단순 로드(from_pretrained) 시 label2id/id2label이 None일 수 있습니다.
+        #
+        # We allow this here to keep Hub loading and verification stable.
+        # Hub 로드 및 검증 안정성을 위해 여기서는 이를 허용합니다.
+        #
+        # Fail-fast validation should happen at model or training level instead.
+        # 실제 사용 검증은 모델 또는 학습 단계에서 fail-fast로 처리해야 합니다.
+        if label2id is None and id2label is None:
+            # Respect num_labels if explicitly provided, otherwise default to 0.
+            # num_labels가 주어졌다면 존중하고, 아니면 0으로 둡니다.
+            num_labels = int(kwargs.get("num_labels", 0))
+            label2id_norm: dict[str, int] = {}
+            id2label_norm: dict[int, str] = {}
+        else:
+            # If only one mapping is provided, derive the other.
+            # 하나만 주어진 경우 나머지를 자동으로 생성합니다.
+            if id2label is None:
+                id2label = {v: k for k, v in label2id.items()}
+            if label2id is None:
+                label2id = {v: k for k, v in id2label.items()}
+
+            # Ensure both mappings are consistent in size.
+            # 두 매핑의 크기가 일치하는지 확인합니다.
+            if len(label2id) != len(id2label):
+                raise ValueError(
+                    f"label2id/id2label size mismatch: "
+                    f"{len(label2id)} vs {len(id2label)}"
+                )
+
+            num_labels = len(id2label)
+            label2id_norm = dict(label2id)
+            id2label_norm = dict(id2label)
+
+        # ============================================================
+        # 3) num_labels consistency enforcement
+        # 3) num_labels 일관성 강제
+        # ============================================================
+        # If num_labels is provided via kwargs, it must match inferred labels.
+        # kwargs로 num_labels가 들어온 경우 추론된 값과 반드시 일치해야 합니다.
+        if "num_labels" in kwargs:
+            if (label2id is not None or id2label is not None) and int(kwargs["num_labels"]) != num_labels:
+                raise ValueError(
+                    f"kwargs['num_labels']={kwargs['num_labels']} "
+                    f"!= inferred num_labels={num_labels}"
+                )
+        else:
             kwargs["num_labels"] = num_labels
 
+        # ============================================================
+        # 4) Parent initialization
+        # 4) 부모 클래스 초기화
+        # ============================================================
+        # Initialize PretrainedConfig with normalized label mappings.
+        # 정규화된 라벨 매핑을 사용하여 PretrainedConfig를 초기화합니다.
         super().__init__(
-            label2id=label2id,
-            id2label=id2label,
+            label2id=label2id_norm,
+            id2label=id2label_norm,
             **kwargs,
         )
-        
-        # 4) 중요: 부모 필드에도 num_labels 반영(저장/로드 안정)
-        self.num_labels = num_labels
-        self.label2id = label2id
-        self.id2label = id2label
 
+        # ============================================================
+        # 5) Explicit attribute assignment for save/load stability
+        # 5) 저장/로드 안정성을 위한 명시적 속성 고정
+        # ============================================================
+        # Explicitly reassign critical fields to avoid subtle serialization issues.
+        # 미묘한 직렬화 문제를 방지하기 위해 핵심 필드를 명시적으로 다시 설정합니다.
         self.backbone_name_or_path = backbone_name_or_path
-        self.mlp_head_bottleneck   = int(mlp_head_bottleneck)
-        self.mlp_head_dropout      = float(mlp_head_dropout)
+        self.mlp_head_bottleneck = int(mlp_head_bottleneck)
+        self.mlp_head_dropout = float(mlp_head_dropout)
+
+        self.label2id = label2id_norm
+        self.id2label = id2label_norm
+        self.num_labels = int(kwargs["num_labels"])
 
     def to_dict(self):
+        # Call the parent implementation first.
+        # 먼저 부모 구현을 호출합니다.
         output = super().to_dict()
-        # 명시적으로 포함
-        output["num_labels"] = self.num_labels
+
+        # Force num_labels to be present and consistent.
+        # num_labels가 반드시 존재하고 일관되도록 강제합니다.
+        output["num_labels"] = int(
+            getattr(self, "num_labels", output.get("num_labels", 0))
+        )
         return output
 
+
+# Register this config so it can be resolved via AutoConfig.
+# AutoConfig를 통해 이 config가 해석될 수 있도록 등록합니다.
 BackboneMLPHeadConfig.register_for_auto_class("AutoConfig")

models/torchvision__densenet121/ds_model.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
+# src/ds_model.py
 
-from dataclasses import dataclass
-from typing import Dict, Any, Optional, Tuple, Set, List
+from typing import Optional, List
 
 import torch
 import torch.nn as nn
@@ -12,146 +11,88 @@ import torch.nn.functional as F
 
 # --- transformers core ---
 from transformers.modeling_utils import PreTrainedModel
-from transformers import AutoModel, AutoConfig, PretrainedConfig
+from transformers import AutoModel, AutoConfig
 from transformers.modeling_outputs import ImageClassifierOutput
 
 # --- torchvision ---
 from torchvision import models as tv_models
 
-
-# ============================================================
-# (0) Config
-# - 기존 ds_cfg.BackboneMLPHeadConfig와 필드명을 맞추었습니다.
-# - 이미 ds_cfg.py가 있다면: 이 블록을 지우고 "from ds_cfg import BackboneMLPHeadConfig"로 바꿔도 됩니다.
-# ============================================================
-class BackboneMLPHeadConfig(PretrainedConfig):
-    model_type = "backbone_mlphead"
-
-    def __init__(
-        self,
-        backbone_name_or_path: Optional[str] = None,
-        num_labels: int = 2,
-        id2label: Optional[Dict[int, str]] = None,
-        label2id: Optional[Dict[str, int]] = None,
-        mlp_head_bottleneck: int = 256,
-        mlp_head_dropout: float = 0.2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-        self.backbone_name_or_path = backbone_name_or_path
-        self.num_labels = num_labels
-        self.id2label = id2label or {i: f"LABEL_{i}" for i in range(num_labels)}
-        self.label2id = label2id or {v: k for k, v in self.id2label.items()}
-        self.mlp_head_bottleneck = mlp_head_bottleneck
-        self.mlp_head_dropout = mlp_head_dropout
-
-
-# ============================================================
-# (1) BACKBONE_META
-# - 이미 ds_meta.py가 있다면: 이 블록을 지우고 "from ds_meta import BACKBONE_META"로 바꿔도 됩니다.
-# ============================================================
-BACKBONE_META: Dict[str, Dict[str, Any]] = {
-    # transformers
-    "google/vit-base-patch16-224": {
-        "type": "vit",
-        "feat_rule": "cls",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/swin-tiny-patch4-window7-224": {
-        "type": "swin",
-        "feat_rule": "pool_or_mean",
-        "feat_dim": 768,
-        "has_bn": False,
-        "unfreeze": "last_n",
-    },
-    "microsoft/resnet-50": {
-        "type": "resnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 2048,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "google/efficientnet-b0": {
-        "type": "efficientnet",
-        "feat_rule": "pool_or_gap",
-        "feat_dim": 1280,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-
-    # densenet
-    "timm/densenet121.tv_in1k": {
-        "type": "timm_densenet",
-        "feat_rule": "timm_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-    "torchvision/densenet121": {
-        "type": "torchvision_densenet",
-        "feat_rule": "torchvision_densenet_gap",
-        "feat_dim": 1024,
-        "has_bn": True,
-        "unfreeze": "last_n",
-    },
-}
-
-
-# ============================================================
-# (2) MLP Head
-# - 이미 mlp_head.py가 있다면: 이 블록을 지우고 "from mlp_head import MLPHead"로 바꿔도 됩니다.
-# ============================================================
-class MLPHead(nn.Module):
-    def __init__(self, in_dim: int, num_labels: int, bottleneck: int = 256, p: float = 0.2):
-        super().__init__()
-        self.fc2 = nn.Linear(in_dim, bottleneck)
-        self.act2 = nn.GELU()
-        self.drop2 = nn.Dropout(p)
-        self.fc3 = nn.Linear(bottleneck, num_labels)
-
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = self.drop2(self.act2(self.fc2(x)))
-        return self.fc3(x)
-
+from ds_cfg import BackboneMLPHeadConfig
+from ds_meta import BACKBONE_META
+from mlp_head import MLPHead
 
 # ============================================================
 # (3) Model: backbone + MLP head
-# 핵심 설계:
-# - __init__: backbone 구조(skeleton)만 생성. pretrained를 절대 로드하지 않음.
-# - pretrained 주입: model.load_backbone_pretrained_()를 "fresh-start에서만" 직접 호출.
-# - from_pretrained override 없음: HF 기본 로더가 checkpoint를 그대로 복원.
+# (3) 모델: backbone + MLP head
 # ============================================================
+# Design principle: __init__ builds only a skeleton and MUST NOT load pretrained weights.
+# 설계 원칙: __init__에서는 skeleton만 만들고 pretrained weight 로드는 절대 하면 안 됩니다.
+#
+# Pretrained injection is allowed ONLY via an explicit call in fresh-start flows.
+# pretrained 주입은 fresh-start 흐름에서의 명시적 호출로만 허용합니다.
+#
+# HF from_pretrained should restore checkpoints as-is without side effects.
+# HF from_pretrained는 부작용 없이 체크포인트를 그대로 복원해야 합니다.
 class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
+    # This links the model to its custom config for AutoClass usage.
+    # AutoClass 사용을 위해 모델과 커스텀 config를 연결합니다.
     config_class = BackboneMLPHeadConfig
 
     def __init__(self, config: BackboneMLPHeadConfig):
+        # PreTrainedModel expects a config object and stores it internally.
+        # PreTrainedModel은 config 객체를 받아 내부에 저장하는 전제를 가집니다.
         super().__init__(config)
 
+        # Fail-fast: the model is not meant to be instantiated without a valid backbone id.
+        # fail-fast: 유효한 backbone id 없이 모델을 만드는 사용 시나리오는 허용하지 않습니다.
+        #
+        # Note: Transformers may create configs with no args, but models are conventionally created with configs.
+        # 참고: Transformers는 config 무인자 생성이 있을 수 있으나, 모델은 관례적으로 config를 받아 생성됩니다.
         if config.backbone_name_or_path is None:
-            raise ValueError("config.backbone_name_or_path is None. Provide a valid backbone id.")
+            raise ValueError(
+                "config.backbone_name_or_path is None. "
+                "Provide a valid backbone id (whitelist key in BACKBONE_META)."
+            )
 
+        # Fail-fast: training/inference requires a positive number of labels.
+        # fail-fast: 학습/추론은 num_labels가 양수여야 합니다.
+        #
+        # Config may exist in a minimal form for internal serialization paths, but the model should not.
+        # config는 내부 직렬화 경로에서 최소 형태로 존재할 수 있으나 모델은 그러면 안 됩니다.
+        if int(getattr(config, "num_labels", 0)) <= 0:
+            raise ValueError(
+                f"config.num_labels must be > 0, got {getattr(config, 'num_labels', None)}. "
+                "Set num_labels (or id2label/label2id) when creating the config."
+            )
+
+        # Meta is a single source of truth for extraction and fine-tuning rules.
+        # meta는 feature 추출 및 미세조정 규칙의 단일 기준입니다.
         self._meta = BACKBONE_META[config.backbone_name_or_path]
 
-        # (중요) backbone은 항상 skeleton만 생성
+        # Backbone skeleton is always created without pretrained weights.
+        # backbone skeleton은 항상 pretrained weight 없이 생성합니다.
         self.backbone = self._build_backbone_skeleton(config.backbone_name_or_path)
 
-        # head
+        # Head shape is driven by meta feat_dim and config.num_labels.
+        # head shape은 meta의 feat_dim과 config.num_labels로 결정됩니다.
         self.classifier = MLPHead(
             in_dim=int(self._meta["feat_dim"]),
-            num_labels=config.num_labels,
-            bottleneck=config.mlp_head_bottleneck,
-            p=config.mlp_head_dropout,
+            num_labels=int(config.num_labels),
+            bottleneck=int(config.mlp_head_bottleneck),
+            p=float(config.mlp_head_dropout),
         )
 
-        # HF init hook (init_weights는 head-only로 override됨)
+        # HF initialization hook, but we override init_weights to initialize head-only.
+        # HF 초기화 훅이지만 init_weights를 override하여 head만 초기화합니다.
         self.post_init()
 
     def init_weights(self):
         """
-        HF의 기본 init_weights()는 모델 전체에 apply(...)를 걸 수 있으니,
-        head만 초기화한다.
+        Initialize only the head to avoid touching the backbone skeleton.
+        backbone skeleton을 건드리지 않기 위해 head만 초기화합니다.
+
+        HF's default init may traverse the entire module tree, which is undesirable here.
+        HF 기본 init은 전체 모듈 트리를 순회할 수 있어 여기서는 부적절합니다.
         """
         if getattr(self, "classifier", None) is not None:
             self.classifier.apply(self._init_weights)
@@ -159,8 +100,11 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     # ----------------------------
     # backbone skeleton builders
+    # backbone skeleton 생성기
     # ----------------------------
     def _build_backbone_skeleton(self, backbone_id: str) -> nn.Module:
+        # Meta decides which loader path to use.
+        # meta가 어떤 로더 경로를 사용할지 결정합니다.
         meta = BACKBONE_META[backbone_id]
         t = meta["type"]
 
@@ -170,18 +114,24 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         if t == "torchvision_densenet":
             return self._build_torchvision_densenet_skeleton(backbone_id)
 
-        # transformers: config로 구조만 생성
+        # For transformers backbones: build a random-weight skeleton from config only.
+        # transformers 백본: config로부터 랜덤 초기화 skeleton만 생성합니다.
         bb_cfg = AutoConfig.from_pretrained(backbone_id)
         return AutoModel.from_config(bb_cfg)
 
     @staticmethod
     def _build_timm_densenet_skeleton(hf_repo_id: str) -> nn.Module:
+        # timm is an optional dependency and should be imported lazily.
+        # timm은 옵션 의존성이므로 지연 import 합니다.
         try:
             import timm
         except Exception as e:
-            raise ImportError("DenseNet(timm) backbone requires `timm`. Install: pip install timm") from e
+            raise ImportError(
+                "DenseNet(timm) backbone requires `timm`. Install: pip install timm"
+            ) from e
 
-        # 구조만 (pretrained=False)
+        # Build structure only (pretrained=False) and remove classifier head (num_classes=0).
+        # 구조만 생성(pretrained=False)하고 분류기 head는 제거(num_classes=0)합니다.
         return timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=False,
@@ -190,33 +140,33 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
     @staticmethod
     def _build_torchvision_densenet_skeleton(model_id: str) -> nn.Module:
-        mapping = {
-            "torchvision/densenet121": "densenet121",
-            "torchvision/densenet169": "densenet169",
-            "torchvision/densenet201": "densenet201",
-            "torchvision/densenet161": "densenet161",
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch = mapping[model_id]
-        fn = getattr(tv_models, arch)
-
-        # 구조만 (weights=None)
-        m = fn(weights=None).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Build structure only (weights=None) to avoid implicit pretrained loading.
+        # implicit pretrained 로드를 피하기 위해 구조만 생성(weights=None)합니다.
+        m = tv_models.densenet121(weights=None)
         return m
 
     # ------------------------------------------------------------
-    # pretrained 로딩은 "명시적 호출"로만 수행 (fresh-start 전용)
+    # Pretrained loading is explicit and fresh-start only
+    # pretrained 로딩은 명시적 호출이며 fresh-start 전용
     # ------------------------------------------------------------
     @torch.no_grad()
-    def load_backbone_pretrained_(self, *, low_cpu_mem_usage: bool = False, device_map=None):
+    def load_backbone_pretrained_(
+        self,
+        *,
+        low_cpu_mem_usage: bool = False,
+        device_map=None,
+    ):
         """
-        fresh-start 전용:
-            model = BackboneWithMLPHeadForImageClassification(cfg)
-            model.load_backbone_pretrained_()
+        Fresh-start only: inject pretrained backbone weights into the skeleton.
+        fresh-start 전용: skeleton backbone에 pretrained 가중치를 주입합니다.
 
-        checkpoint reload(from_pretrained)에서는 호출하지 마십시오.
+        Do NOT call this after from_pretrained() because it would overwrite checkpoint weights.
+        from_pretrained() 이후 호출하면 체크포인트 가중치를 덮어쓰므로 절대 호출하면 안 됩니다.
         """
         bb = self.config.backbone_name_or_path
         meta = BACKBONE_META[bb]
@@ -230,48 +180,58 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             self._load_torchvision_pretrained_into_skeleton_(bb)
             return
 
-        # transformers pretrained -> skeleton에 주입
+        # For transformers backbones, load a reference pretrained model and copy weights into our skeleton.
+        # transformers 백본은 reference pretrained 모델을 로드한 뒤 skeleton에 가중치를 복사합니다.
         ref = AutoModel.from_pretrained(
             bb,
             low_cpu_mem_usage=low_cpu_mem_usage,
             device_map=device_map,
         )
+
+        # strict=False is used to tolerate harmless key differences across minor versions.
+        # strict=False는 마이너 버전 차이로 인한 무해한 키 차이를 허용하기 위해 사용합니다.
         self.backbone.load_state_dict(ref.state_dict(), strict=False)
         del ref
 
     @torch.no_grad()
     def _load_timm_pretrained_into_skeleton_(self, hf_repo_id: str):
+        # timm must be present for timm backbones.
+        # timm 백본에는 timm 설치가 필요합니다.
         import timm
+
+        # Create a pretrained reference model and copy its weights strictly.
+        # pretrained reference 모델을 만들고 가중치를 strict하게 복사합니다.
         ref = timm.create_model(
             f"hf_hub:{hf_repo_id}",
             pretrained=True,
             num_classes=0,
         ).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     @torch.no_grad()
     def _load_torchvision_pretrained_into_skeleton_(self, model_id: str):
-        mapping = {
-            "torchvision/densenet121": ("densenet121", tv_models.DenseNet121_Weights.DEFAULT),
-            "torchvision/densenet169": ("densenet169", tv_models.DenseNet169_Weights.DEFAULT),
-            "torchvision/densenet201": ("densenet201", tv_models.DenseNet201_Weights.DEFAULT),
-            "torchvision/densenet161": ("densenet161", tv_models.DenseNet161_Weights.DEFAULT),
-        }
-        if model_id not in mapping:
-            raise ValueError(f"Unsupported torchvision DenseNet id: {model_id}")
-
-        arch, weights = mapping[model_id]
-        fn = getattr(tv_models, arch)
-        ref = fn(weights=weights).eval()
+        # This project intentionally supports only torchvision/densenet121 in the 224 whitelist.
+        # 이 프로젝트는 224 화이트리스트에서 torchvision/densenet121만 의도적으로 지원합니다.
+        if model_id != "torchvision/densenet121":
+            raise ValueError(f"Unsupported torchvision DenseNet id (224 whitelist only): {model_id}")
+
+        # Use torchvision's default pretrained weights for densenet121.
+        # torchvision의 densenet121 기본 pretrained weights를 사용합니다.
+        ref = tv_models.densenet121(weights=tv_models.DenseNet121_Weights.DEFAULT).eval()
+
         self.backbone.load_state_dict(ref.state_dict(), strict=True)
         del ref
 
     # ----------------------------
     # feature extraction
+    # feature 추출
     # ----------------------------
     @staticmethod
     def _pool_or_gap(outputs) -> torch.Tensor:
+        # Some transformers vision CNNs provide pooler_output explicitly.
+        # 일부 transformers vision CNN은 pooler_output을 명시적으로 제공합니다.
         if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
             x = outputs.pooler_output
             if x.dim() == 2:
@@ -280,29 +240,42 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
                 return x.flatten(1)
             raise RuntimeError(f"Unexpected pooler_output shape: {tuple(x.shape)}")
 
+        # Otherwise we expect a CNN-style last_hidden_state=(B,C,H,W) and apply GAP.
+        # 그렇지 않으면 CNN 스타일 last_hidden_state=(B,C,H,W)를 기대하고 GAP을 적용합니다.
         x = outputs.last_hidden_state
         if x.dim() == 4:
             return x.mean(dim=(2, 3))
+
         raise RuntimeError(
             "Expected pooler_output or (B,C,H,W) last_hidden_state for CNN backbones. "
             f"Got last_hidden_state shape={tuple(x.shape)}"
         )
 
     def _extract_features(self, outputs, pixel_values: Optional[torch.Tensor] = None) -> torch.Tensor:
+        # Feature rule is defined by BACKBONE_META and must remain stable across saves/loads.
+        # feature 규칙은 BACKBONE_META로 정의되며 저장/로드 간 안정적으로 유지되어야 합니다.
         rule = self._meta["feat_rule"]
 
         if rule == "cls":
+            # ViT-style: use CLS token embedding from last_hidden_state.
+            # ViT 스타일: last_hidden_state에서 CLS 토큰 임베딩을 사용합니다.
             return outputs.last_hidden_state[:, 0, :]
 
         if rule == "pool_or_mean":
+            # Swin-style: prefer pooler_output if present, else mean-pool over tokens.
+            # Swin 스타일: pooler_output이 있으면 우선 사용하고, 없으면 토큰 평균 풀링을 사용합니다.
             if hasattr(outputs, "pooler_output") and outputs.pooler_output is not None:
                 return outputs.pooler_output
             return outputs.last_hidden_state.mean(dim=1)
 
         if rule == "pool_or_gap":
+            # CNN-style: use pooler_output if present, else GAP over spatial dims.
+            # CNN 스타일: pooler_output이 있으면 사용하고, 없으면 공간 차원 GAP을 사용합니다.
             return self._pool_or_gap(outputs)
 
         if rule == "timm_gap":
+            # timm forward_features returns a feature map (B,C,H,W) which we GAP to (B,C).
+            # timm forward_features는 (B,C,H,W) feature map을 반환하며 이를 GAP으로 (B,C)로 만듭니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"timm_gap expects Tensor features, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -310,6 +283,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             return outputs.mean(dim=(2, 3))
 
         if rule == "torchvision_densenet_gap":
+            # torchvision DenseNet features are feature maps (B,C,H,W) and require GAP.
+            # torchvision DenseNet features는 (B,C,H,W) feature map이며 GAP이 필요합니다.
             if not isinstance(outputs, torch.Tensor):
                 raise TypeError(f"torchvision_densenet_gap expects Tensor, got {type(outputs)}")
             if outputs.dim() != 4:
@@ -327,9 +302,13 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
         return_dict=True,
         **kwargs,
     ):
+        # Type decides the backbone forward path and output format.
+        # type이 backbone forward 경로 및 출력 포맷을 결정합니다.
         t = self._meta["type"]
 
         if t == "timm_densenet":
+            # timm DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # timm DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("timm DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -341,6 +320,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         elif t == "torchvision_densenet":
+            # torchvision DenseNet consumes pixel_values as a 4D tensor (B,C,H,W).
+            # torchvision DenseNet은 pixel_values를 4D 텐서 (B,C,H,W)로 받습니다.
             if pixel_values is None:
                 raise ValueError("torchvision DenseNet backbone requires pixel_values.")
             if pixel_values.dim() != 4:
@@ -353,6 +334,8 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             attentions = None
 
         else:
+            # Transformers vision models are called with pixel_values and return ModelOutput.
+            # transformers vision 모델은 pixel_values로 호출되며 ModelOutput을 반환합니다.
             outputs = self.backbone(
                 pixel_values=pixel_values,
                 output_attentions=output_attentions,
@@ -364,10 +347,14 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
             hidden_states = getattr(outputs, "hidden_states", None)
             attentions = getattr(outputs, "attentions", None)
 
+        # Classifier consumes (B, feat_dim) and returns logits (B, num_labels).
+        # classifier는 (B, feat_dim)을 받아 logits (B, num_labels)를 반환합니다.
         logits = self.classifier(feats)
 
         loss = None
         if labels is not None:
+            # Cross entropy expects labels as class indices in [0, num_labels).
+            # cross entropy는 labels가 [0, num_labels) 범위의 class index이길 기대합니다.
             loss = F.cross_entropy(logits, labels)
 
         if not return_dict:
@@ -383,20 +370,27 @@ class BackboneWithMLPHeadForImageClassification(PreTrainedModel):
 
 
 # ============================================================
-# Freeze / Unfreeze utilities (당신 코드 유지)
+# Freeze / Unfreeze utilities
+# Freeze / Unfreeze 유틸리티
 # ============================================================
 def _set_requires_grad(module: nn.Module, flag: bool):
+    # Toggle requires_grad for all parameters in a module.
+    # 모듈의 모든 파라미터에 대해 requires_grad를 토글합니다.
     for p in module.parameters():
         p.requires_grad = flag
 
 
 def set_bn_eval(module: nn.Module):
+    # Put BatchNorm layers into eval mode to freeze running stats.
+    # BatchNorm 레이어를 eval 모드로 두어 running stats를 고정합니다.
     for m in module.modules():
         if isinstance(m, (nn.BatchNorm1d, nn.BatchNorm2d, nn.BatchNorm3d, nn.SyncBatchNorm)):
             m.eval()
 
 
 def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn: bool = True):
+    # Stage1: freeze backbone and train only the head.
+    # stage1: backbone을 freeze하고 head만 학습합니다.
     _set_requires_grad(model.backbone, False)
     _set_requires_grad(model.classifier, True)
 
@@ -406,6 +400,8 @@ def freeze_backbone(model: BackboneWithMLPHeadForImageClassification, freeze_bn:
 
 
 def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_bn_eval: bool = True):
+    # Stage2: train mode, optionally keeping BN layers in eval for stability.
+    # stage2: train 모드로 두되 안정성을 위해 BN을 eval로 유지할 수 있습니다.
     model.train()
     meta = BACKBONE_META[model.config.backbone_name_or_path]
     if keep_bn_eval and meta.get("has_bn", False):
@@ -413,6 +409,8 @@ def finetune_train_mode(model: BackboneWithMLPHeadForImageClassification, keep_b
 
 
 def trainable_summary(model: nn.Module):
+    # Print a compact summary of trainable parameters.
+    # 학습 가능 파라미터 요약을 간단히 출력합니다.
     total = sum(p.numel() for p in model.parameters())
     trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
     ratio = trainable / total if total > 0 else 0.0
@@ -425,6 +423,8 @@ def unfreeze_last_stage(
     last_n: int = 2,
     keep_bn_eval: bool = True,
 ):
+    # This utility implements BACKBONE_META['unfreeze']=="last_n" across supported backbones.
+    # 이 유틸은 지원 백본들에 대해 BACKBONE_META['unfreeze']=="last_n"을 구현합니다.
     freeze_backbone(model, freeze_bn=keep_bn_eval)
 
     n = int(last_n)
@@ -438,12 +438,16 @@ def unfreeze_last_stage(
     bb_type = meta["type"]
 
     if bb_type == "vit":
+        # ViT blocks live under backbone.encoder.layer in the transformers implementation.
+        # ViT 블록은 transformers 구현에서 backbone.encoder.layer 아래에 있습니다.
         blocks = list(model.backbone.encoder.layer)
         for blk in blocks[-n:]:
             _set_requires_grad(blk, True)
         return
 
     if bb_type == "swin":
+        # Swin blocks are nested by stages and blocks; we flatten and unfreeze last n blocks.
+        # Swin 블록은 stage와 block으로 중첩되어 있어 펼친 후 마지막 n개를 unfreeze 합니다.
         stages = list(model.backbone.encoder.layers)
         blocks: List[nn.Module] = []
         for st in stages:
@@ -453,6 +457,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "resnet":
+        # ResNet uses layer1..layer4 stages; we unfreeze at block granularity.
+        # ResNet은 layer1..layer4 stage를 사용하며 block 단위로 unfreeze 합니다.
         bb = model.backbone
         for name in ("layer1", "layer2", "layer3", "layer4"):
             if not hasattr(bb, name):
@@ -472,6 +478,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type == "efficientnet":
+        # EfficientNet in transformers exposes features; we unfreeze from the tail blocks.
+        # transformers EfficientNet은 features를 노출하며 뒤쪽 블록부터 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected EfficientNet structure: missing features")
@@ -488,6 +496,8 @@ def unfreeze_last_stage(
         return
 
     if bb_type in ("timm_densenet", "torchvision_densenet"):
+        # DenseNet exposes a .features module with named blocks; we unfreeze last n submodules.
+        # DenseNet은 .features 모듈에 블록들이 이름으로 존재하며 마지막 n개 서브모듈을 unfreeze 합니다.
         bb = model.backbone
         if not hasattr(bb, "features"):
             raise RuntimeError("Unexpected DenseNet: missing features")
@@ -505,6 +515,8 @@ def unfreeze_last_stage(
                 raise RuntimeError(f"Unexpected DenseNet features: missing {name}")
 
         def _denselayers(db: nn.Module) -> List[nn.Module]:
+            # Dense blocks contain multiple DenseLayer children; we return them for fine-grained unfreezing.
+            # denseblock은 DenseLayer 자식들을 가지므로 세밀한 unfreeze를 위해 이를 반환합니다.
             return list(db.children())
 
         blocks: List[nn.Module] = []
@@ -526,20 +538,8 @@ def unfreeze_last_stage(
 
 # -------------------------
 # register
+# register
+# -------------------------
+# Register for AutoModelForImageClassification so from_pretrained can resolve this custom class.
+# from_pretrained가 이 커스텀 클래스를 해석할 수 있도록 AutoModelForImageClassification에 등록합니다.
 BackboneWithMLPHeadForImageClassification.register_for_auto_class("AutoModelForImageClassification")
-
-
-# ==========================================================
-
-# # fresh-start
-# cfg = BackboneMLPHeadConfig(backbone_name_or_path="timm/densenet121.tv_in1k", num_labels=3)
-# model = BackboneWithMLPHeadForImageClassification(cfg)
-
-# # pretrained를 쓰려면 명시적으로 호출
-# model.load_backbone_pretrained_()
-
-# # 이후 학습
-
-# # checkpoint에서 시작
-# model = BackboneWithMLPHeadForImageClassification.from_pretrained("checkpoints/xxx")
-# # 여기서는 load_backbone_pretrained_() 호출하면 안 됩니다.

models/torchvision__densenet121/ds_proc.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# src/ds_proc.py
+
+# ============================================================
+# (4) ImageProcessor (AutoImageProcessor integration)
+# (4) ImageProcessor (AutoImageProcessor 연동)
+# ============================================================
+
+from typing import Any
+
+import numpy as np
+import torch
+from transformers import AutoImageProcessor, AutoConfig
+from transformers.image_processing_base import ImageProcessingMixin
+from transformers.utils.generic import TensorType
+
+from ds_meta import BackboneID, BACKBONE_META
+
+
+class BackboneMLPHead224ImageProcessor(ImageProcessingMixin):
+    """
+    This processor performs image preprocessing and outputs {"pixel_values": ...}.
+    이 processor는 이미지 전처리를 수행하고 {"pixel_values": ...}를 출력합니다.
+
+    Key requirements:
+    핵심 요구사항:
+
+    1) save_pretrained() must produce a JSON-serializable preprocessor_config.json.
+       save_pretrained()는 JSON 직렬화 가능한 preprocessor_config.json을 생성해야 합니다.
+
+    2) Runtime-only objects (delegate processor, timm/torchvision transforms) must NOT be serialized.
+       런타임 객체(delegate processor, timm/torchvision transform)는 절대 직렬화하면 안 됩니다.
+
+    3) Runtime objects are rebuilt at init/load time based on backbone meta.
+       런타임 객체는 backbone meta에 따라 init/load 시점에 재구성됩니다.
+    """
+
+    # HF vision models conventionally expect "pixel_values" as the primary input key.
+    # HF vision 모델은 관례적으로 입력 키로 "pixel_values"를 기대합니다.
+    model_input_names = ["pixel_values"]
+
+    def __init__(self, backbone_name_or_path: BackboneID, is_training: bool = False, **kwargs):
+        # ImageProcessingMixin stores extra kwargs and manages auto_map metadata.
+        # ImageProcessingMixin은 추가 kwargs를 저장하고 auto_map 메타를 관리합니다.
+        super().__init__(**kwargs)
+
+        # Enforce whitelist via BACKBONE_META to keep behavior stable.
+        # 동작 안정성을 위해 BACKBONE_META 기반 화이트리스트를 강제합니다.
+        if backbone_name_or_path not in BACKBONE_META:
+            raise ValueError(
+                f"Unsupported backbone_name_or_path={backbone_name_or_path}. "
+                f"Allowed: {sorted(BACKBONE_META.keys())}"
+            )
+
+        # Serializable fields only: these should appear in preprocessor_config.json.
+        # 직렬화 가능한 필드만: 이 값들만 preprocessor_config.json에 들어가야 합니다.
+        self.backbone_name_or_path = backbone_name_or_path
+        self.is_training = bool(is_training)
+
+        # Runtime-only fields: must never be serialized.
+        # 런타임 전용 필드: 절대 직렬화되면 안 됩니다.
+        self._meta = None
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        # Build runtime objects according to backbone type.
+        # backbone type에 따라 런타임 객체를 구성합니다.
+        self._build_runtime()
+
+    # ============================================================
+    # Runtime builders
+    # 런타임 빌더
+    # ============================================================
+    def _build_runtime(self):
+        """
+        Build runtime delegate/transform based on BACKBONE_META["type"].
+        BACKBONE_META["type"]에 따라 런타임 delegate/transform을 구성합니다.
+        """
+        meta = BACKBONE_META[self.backbone_name_or_path]
+        self._meta = meta
+
+        # Always reset runtime fields before rebuilding.
+        # 재구성 전 런타임 필드는 항상 초기화합니다.
+        self._delegate = None
+        self._timm_transform = None
+        self._torchvision_transform = None
+
+        t = meta["type"]
+
+        if t == "timm_densenet":
+            # timm DenseNet uses timm.data transforms for ImageNet-style preprocessing.
+            # timm DenseNet은 ImageNet 전처리를 위해 timm.data transform을 사용합니다.
+            self._timm_transform = self._build_timm_transform(
+                backbone_id=self.backbone_name_or_path,
+                is_training=self.is_training,
+            )
+            return
+
+        if t == "torchvision_densenet":
+            # torchvision DenseNet requires torchvision-style preprocessing (resize/crop/tensor/normalize).
+            # torchvision DenseNet은 torchvision 스타일 전처리(resize/crop/tensor/normalize)가 필요합니다.
+            self._torchvision_transform = self._build_torchvision_densenet_transform(
+                is_training=self.is_training
+            )
+            return
+
+        # Default: transformers backbone delegates to its official AutoImageProcessor.
+        # 기본: transformers 백본은 공식 AutoImageProcessor에 위임합니다.
+        self._delegate = AutoImageProcessor.from_pretrained(self.backbone_name_or_path)
+
+    @staticmethod
+    def _build_timm_transform(*, backbone_id: str, is_training: bool):
+        """
+        Create timm transform without storing non-serializable objects in config.
+        비직렬화 객체를 config에 저장하지 않고 timm transform을 생성합니다.
+        """
+        try:
+            import timm
+            from timm.data import resolve_model_data_config, create_transform
+        except Exception as e:
+            raise ImportError(
+                "timm backbone processor requires `timm`. Install: pip install timm"
+            ) from e
+
+        # We only need model metadata to resolve data config, so pretrained=False is preferred.
+        # data config 추출만 필요하므로 pretrained=False를 우선 사용합니다.
+        m = timm.create_model(f"hf_hub:{backbone_id}", pretrained=False, num_classes=0)
+        dc = resolve_model_data_config(m)
+
+        # create_transform returns a torchvision-like callable that maps PIL -> torch.Tensor(C,H,W).
+        # create_transform은 PIL -> torch.Tensor(C,H,W)로 매핑하는 callable을 반환합니다.
+        tfm = create_transform(**dc, is_training=is_training)
+        return tfm
+
+    @staticmethod
+    def _build_torchvision_densenet_transform(*, is_training: bool):
+        """
+        Build torchvision preprocessing for DenseNet-121 (224 pipeline).
+        DenseNet-121용 torchvision 전처리(224 파이프라인)를 구성합니다.
+        """
+        try:
+            from torchvision import transforms
+        except Exception as e:
+            raise ImportError(
+                "torchvision DenseNet processor requires `torchvision`. Install: pip install torchvision"
+            ) from e
+
+        # These are the standard ImageNet normalization stats used by torchvision weights.
+        # 이 값들은 torchvision weights가 사용하는 표준 ImageNet 정규화 통계입니다.
+        mean = (0.485, 0.456, 0.406)
+        std = (0.229, 0.224, 0.225)
+
+        # Training pipeline typically uses RandomResizedCrop and horizontal flip.
+        # 학습 파이프라인은 보통 RandomResizedCrop과 좌우반전을 사용합니다.
+        if is_training:
+            return transforms.Compose(
+                [
+                    transforms.RandomResizedCrop(224),
+                    transforms.RandomHorizontalFlip(p=0.5),
+                    transforms.ToTensor(),
+                    transforms.Normalize(mean=mean, std=std),
+                ]
+            )
+
+        # Inference pipeline typically uses Resize(256) + CenterCrop(224).
+        # 추론 파이프라인은 보통 Resize(256) + CenterCrop(224)를 사용합니다.
+        return transforms.Compose(
+            [
+                transforms.Resize(256),
+                transforms.CenterCrop(224),
+                transforms.ToTensor(),
+                transforms.Normalize(mean=mean, std=std),
+            ]
+        )
+
+    # ============================================================
+    # Serialization
+    # 직렬화
+    # ============================================================
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return a JSON-serializable dict for preprocessor_config.json.
+        preprocessor_config.json에 들어갈 JSON 직렬화 dict를 반환합니다.
+
+        Important: do not leak runtime objects into the serialized dict.
+        중요: 런타임 객체가 직렬화 dict에 섞이면 안 됩니다.
+        """
+        # ImageProcessingMixin.to_dict() adds metadata such as image_processor_type/auto_map.
+        # ImageProcessingMixin.to_dict()는 image_processor_type/auto_map 같은 메타를 추가합니다.
+        d = super().to_dict()
+
+        # Force minimal stable fields for long-term compatibility.
+        # 장기 호환을 위해 최소 안정 필드를 강제합니다.
+        d["image_processor_type"] = self.__class__.__name__
+        d["backbone_name_or_path"] = self.backbone_name_or_path
+        d["is_training"] = self.is_training
+
+        # Remove any runtime-only fields defensively.
+        # 런타임 전용 필드는 보수적으로 제거합니다.
+        for key in ["_meta", "_delegate", "_timm_transform", "_torchvision_transform"]:
+            d.pop(key, None)
+
+        return d
+
+    @classmethod
+    def from_dict(cls, image_processor_dict: dict[str, Any], **kwargs):
+        """
+        Standard load path used by BaseImageProcessor / AutoImageProcessor.
+        BaseImageProcessor / AutoImageProcessor가 사용하는 표준 로드 경로입니다.
+        """
+        backbone = image_processor_dict.get("backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("preprocessor_config.json missing key: backbone_name_or_path")
+
+        is_training = bool(image_processor_dict.get("is_training", False))
+        return cls(backbone_name_or_path=backbone, is_training=is_training, **kwargs)
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        """
+        Fallback path if AutoImageProcessor calls class.from_pretrained directly.
+        AutoImageProcessor가 class.from_pretrained를 직접 호출하는 경우를 대비한 경로입니다.
+
+        Strategy:
+        전략:
+
+        - Read config.json via AutoConfig and recover backbone_name_or_path.
+          AutoConfig로 config.json을 읽고 backbone_name_or_path를 복구합니다.
+        """
+        cfg = AutoConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        backbone = getattr(cfg, "backbone_name_or_path", None)
+        if backbone is None:
+            raise ValueError("Cannot build processor: backbone_name_or_path not found in config.json")
+
+        # is_training is runtime-only and should default to False for inference/serving.
+        # is_training은 런타임 전용이며 추론/서빙 기본값은 False가 맞습니다.
+        return cls(backbone_name_or_path=backbone, is_training=False)
+
+    # ============================================================
+    # Call interface
+    # 호출 인터페이스
+    # ============================================================
+    @staticmethod
+    def _ensure_list(images: Any) -> list[Any]:
+        # Normalize scalar image input to a list for uniform processing.
+        # 단일 입력을 리스트로 정규화하여 동일한 처리 경로를 사용합니다.
+        if isinstance(images, (list, tuple)):
+            return list(images)
+        return [images]
+
+    @staticmethod
+    def _to_pil_rgb(x: Any):
+        # Convert common image inputs into PIL RGB images.
+        # 일반적인 입력을 PIL RGB 이미지로 변환합니다.
+        from PIL import Image as PILImage
+
+        if isinstance(x, PILImage.Image):
+            return x.convert("RGB")
+        if isinstance(x, np.ndarray) and x.ndim == 3:
+            return PILImage.fromarray(x).convert("RGB")
+        raise TypeError(f"Unsupported image type: {type(x)}")
+
+    def __call__(
+        self,
+        images: Any | list[Any],
+        return_tensors: str | TensorType | None = "pt",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Convert images into {"pixel_values": Tensor/ndarray}.
+        이미지를 {"pixel_values": Tensor/ndarray}로 변환합니다.
+        """
+        images = self._ensure_list(images)
+
+        # Rebuild runtime if needed (e.g., right after deserialization).
+        # 직렬화 복원 직후 등 런타임이 비어있을 수 있으므로 재구성합니다.
+        if (self._delegate is None) and (self._timm_transform is None) and (self._torchvision_transform is None):
+            self._build_runtime()
+
+        # timm path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # timm 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._timm_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._timm_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected timm transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # torchvision path: PIL -> torch.Tensor(C,H,W) normalized float32.
+        # torchvision 경로: PIL -> torch.Tensor(C,H,W) 정규화 float32입니다.
+        if self._torchvision_transform is not None:
+            pv: list[torch.Tensor] = []
+            for im in images:
+                pil = self._to_pil_rgb(im)
+                t = self._torchvision_transform(pil)
+                if not isinstance(t, torch.Tensor):
+                    raise RuntimeError("Unexpected torchvision transform output (expected torch.Tensor).")
+                pv.append(t)
+            pixel_values = torch.stack(pv, dim=0)  # (B,C,H,W)
+            return self._format_return(pixel_values, return_tensors)
+
+        # transformers delegate path: rely on official processor behavior.
+        # transformers 위임 경로: 공식 processor 동작을 그대로 사용합니다.
+        if self._delegate is None:
+            raise RuntimeError("Processor runtime not built: delegate is None and no transforms are available.")
+
+        return self._delegate(images, return_tensors=return_tensors, **kwargs)
+
+    @staticmethod
+    def _format_return(pixel_values: torch.Tensor, return_tensors: str | TensorType | None) -> dict[str, Any]:
+        """
+        Format pixel_values according to return_tensors.
+        return_tensors에 맞춰 pixel_values 반환 포맷을 맞춥니다.
+        """
+        if return_tensors is None or return_tensors in ("pt", TensorType.PYTORCH):
+            return {"pixel_values": pixel_values}
+        if return_tensors in ("np", TensorType.NUMPY):
+            return {"pixel_values": pixel_values.detach().cpu().numpy()}
+        raise ValueError(f"Unsupported return_tensors={return_tensors}. Use 'pt' or 'np'.")
+
+
+# Register this processor for AutoImageProcessor resolution.
+# AutoImageProcessor 해석을 위해 이 processor를 등록합니다.
+if __name__ != "__main__":
+    BackboneMLPHead224ImageProcessor.register_for_auto_class("AutoImageProcessor")

models/torchvision__densenet121/model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:969ad71b68ca03294c98303e609ea596d833f4381ff3039131e4a5239b72dd99
+oid sha256:e8431398f3461657aea5362b326d351fcdd4c5c009bf126765d0dcd60f94aa72
 size 33394052

models/torchvision__densenet121/preprocessor_config.json

@@ -0,0 +1,8 @@
+{
+  "auto_map": {
+    "AutoImageProcessor": "ds_proc.BackboneMLPHead224ImageProcessor"
+  },
+  "backbone_name_or_path": "torchvision/densenet121",
+  "image_processor_type": "BackboneMLPHead224ImageProcessor",
+  "is_training": false
+}