# Super-Tuning

[Super-Tuning](https://huggingface.co/papers/2607.09287)은 베이스 가중치를 고정하고, 가중치 크기에 따라 선택된 희소 스칼라 엔트리의 희소 서포트만 학습하는 희소 파인튜닝 방법입니다. `r`을 설정하면 희소 서포트 위에 가산적으로 구성된 LoRA 스타일의 저랭크 어댑터가 추가로 할당됩니다(논문에서 "Supra" 하이브리드라고 부르는 방식).

기본 스코어링은 크기(magnitude)만 사용하고 데이터가 필요 없습니다. 해당 논문에서 8B 아블레이션은 `magnitude-topk`가 평균 79.02%로, 캘리브레이션 패스가 필요하지 않으면서도 Wanda 가중 saliency의 78.66%를 상회한다고 보고합니다. 이 구현에서는 Wanda 스타일의 활성화 가중치 스코어링을 제공하지 않습니다.

Super-Tuning에는 현재 다음과 같은 제약이 있습니다:

- `nn.Linear` 레이어만 지원됩니다.

해당 논문의 초록은 다음과 같습니다:

> 매개변수 효율적 방법으로 대규모 언어 모델을 파인튜닝하는 것이 표준 관행이 되었지만, LoRA와 같은 기존 접근법은 학습 가능한 부분공간을 저랭크 분해로 제한합니다. 우리는 Super-Tuning을 소개합니다. 이는 개별 스칼라 가중치 항목의 작은 서포트(support)를 선택하는 희소 파인튜닝 접근법으로, 고정된 매개변수 예산 내에서 제한 없는 랭크의 학습 가능 집합을 제공합니다. 선택은 프루닝에서 영감을 받은 saliency 신호에 의해 안내되며, 크기 기반 스코어링(PaFi 스타일) 또는 활성화 가중 스코어링(Wanda 스타일)을 사용합니다. Math17K에서 평가된 Llama-3.2-1B 및 Meta-Llama-3-8B 파인튜닝에서, 크기 기반 Super-Tuning은 유사한 매개변수 예산에서 LoRA와 동등하거나 그 이상의 성능을 보이며, 희소 서포트와 저랭크 구성 요소를 결합한 하이브리드 변형인 "Supra"는 다운스트림 정확도를 추가로 향상시킵니다.

## 벤치마크 개요

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=SUPERTUNING" frameborder="0" width="850" height="1000"
>

## 사용

**순수 슈퍼 (크기 점수, 데이터 없음):**

```python
from peft import SupertuningConfig, get_peft_model

config = SupertuningConfig(target_modules=["q_proj", "v_proj"], sparsity=0.99)
model = get_peft_model(base_model, config)
```

**Supra 하이브리드**(희소 지원 + LoRA의 가산적 구성):

```python
config = SupertuningConfig(
    target_modules=["q_proj", "v_proj"], sparsity=0.99,
    r=8, lora_alpha=16,   # lora_alpha defaults to 2 * r when omitted
)
model = get_peft_model(base_model, config)
```

## SupertuningConfig[[peft.SupertuningConfig]]

#### peft.SupertuningConfig[[peft.SupertuningConfig]]

```python
peft.SupertuningConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, target_modules: Optional[Union[list[str], str]] = None, modules_to_save: Optional[list[str]] = None, sparsity: float = 0.99, select_top: bool = True, r: Optional[int] = None, lora_alpha: Optional[float] = None, lora_dropout: float = 0.0, init_weights: bool = True, save_precomputed_indices: bool = True)
```

[소스](https://github.com/huggingface/peft/blob/main/src/peft/tuners/supertuning/config.py#L26)

**매개변수:**

target_modules (`Optional[Union[List[str], str]]`) : 어댑터를 적용할 모듈의 이름입니다. 문자열 → 정규식 매칭; 리스트 → 접미사 / 정확한 매칭; None → 모델 아키텍처 기본값.

modules_to_save (`Optional[List[str]]`) : Supertuning 레이어 외부에 있으면서 최종 체크포인트에 학습 가능 상태로 저장해야 하는 모듈들 (예: 무작위 초기화된 분류 헤드).

sparsity (`float`) : `[0.0, 1.0)` 범위의 목표 희소성 비율. `0.99` = 가중치 항목의 1%가 학습 가능. 기본값은 `0.99`입니다.

select_top (`bool`) : magnitude score의 어느 끝을 trainable support로 유지할지 지정합니다. `True`는 가장 큰 magnitude 항목을 유지하며(논문에서 Super / Supra로 언급), `False`는 가장 작은 항목을 유지합니다(논문에서 `-bottom` 변형으로 언급). 논문에서는 최적의 방향이 모델과 작업에 따라 달라진다고 보고합니다. 기본값은 `True`입니다.

r (`Optional[int]`) : "Supra" 하이브리드의 LoRA 랭크입니다. `None`(기본값)인 경우, 학습 가능한 것은 sparse support만입니다(Super 모드). 양의 정수로 설정하면, forward pass에서 sparse support에 기여도가 추가되는 LoRA `A` (`[r, in_features]`) 및 `B` (`[out_features, r]`) 파라미터가 추가로 할당됩니다.

lora_alpha (`Optional[float]`) : Supra 모드의 LoRA 스케일링 팩터입니다. `None`이고 `r`이 설정된 경우 기본값은 `2 * r`입니다. `r is None`인 경우 무시됩니다.

lora_dropout (`float`) : Supra 모드에서 사용할 LoRA dropout 확률입니다. 기본값은 `0.0`입니다. `r is None`인 경우 무시됩니다.

init_weights (`bool`) : `True`(기본값)인 경우, 희소 `values`는 0으로 초기화되고 LoRA `B`도 0으로 초기화됩니다. 즉, 어댑터는 생성 시점에 항등 변환(identity update)을 수행합니다. `False`인 경우, 두 매개변수 모두 Kaiming-uniform 분포로 초기화됩니다(비자명한(non-trivial) 어댑터를 검증하기 위한 테스트에 사용됨). LoRA `A`는 두 경우 모두 Kaiming-uniform 분포를 사용합니다.

save_precomputed_indices (`bool`) : state dict에 sparse-support 인덱스를 저장할지 여부입니다. 기본값은 `True`입니다. 체크포인트 크기를 줄이려면 `False`로 설정하세요. 로드 시점에 base weight의 크기를 기반으로 인덱스가 결정적으로 재구성됩니다. 재구성은 base model weights가 학습 시 사용된 것과 동일하다는 것을 전제로 합니다. 작은 수치적 오차가 발생하면 topk tie-break 결과가 달라질 수 있습니다.

[SupertuningModel](/docs/peft/main/ko/package_reference/supertuning#peft.SupertuningModel)의 구성 클래스입니다.

Super-Tuning(arXiv:2607.09287)은 베이스 가중치를 고정하고, 가중치 크기에 따라 선택된 희소 스칼라 항목의 서포트만 학습합니다. `r`을 설정하면 희소 서포트 위에 LoRA 스타일의 저랭크 어댑터를 추가로 할당합니다(논문에서 "Supra" 하이브리드라고 부르는 방식).

기본 설정(크기 점수화, `r=None`)은 논문에서 보고된 단일 메커니즘 중 최고의 구성을 재현합니다. Meta-Llama-3-8B에서 `magnitude-topk`는 평균 79.02%로 `Wanda`의 78.66%를 능가할 뿐만 아니라, 보정 패스도 필요하지 않습니다. 이 구현에서는 Wanda 스타일의 활성화 가중치 점수화를 제공하지 않습니다.

논문: https://arxiv.org/abs/2607.09287

## SupertuningModel[[peft.SupertuningModel]]

#### peft.SupertuningModel[[peft.SupertuningModel]]

```python
peft.SupertuningModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[소스](https://github.com/huggingface/peft/blob/main/src/peft/tuners/supertuning/model.py#L25)

**매개변수:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : 적응할 기본 모델입니다.

config ([SupertuningConfig](/docs/peft/main/ko/package_reference/supertuning#peft.SupertuningConfig)) : Supertuning 구성입니다.

adapter_name (`str`) : 어댑터 이름. 기본값은 `"default"`입니다.

low_cpu_mem_usage (`bool`, *선택 사항*) : 로딩 속도를 높이기 위해 meta device에 빈 어댑터 가중치를 생성합니다.

**반환값:** `torch.nn.Module`

Supertuning으로 래핑된 모델.

Super-Tuning 튜너 (arXiv:2607.09287).

기본 가중치를 고정하고, 가중치 크기로 선택된 희소 스칼라 항목의 부분 집합만 학습합니다(논문에서 단일 메커니즘 중 최상의 구성; 데이터 불필요). `config.r`이 설정된 경우, 희소 지원과 가산적으로 결합되는 LoRA A/B 매개변수를 추가로 할당합니다 — 논문의 Supra 하이브리드입니다.

Example (순수 Super):

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import SupertuningConfig, get_peft_model

>>> base = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")
>>> config = SupertuningConfig(target_modules=["q_proj", "v_proj"], sparsity=0.99)
>>> model = get_peft_model(base, config)
```

Example (Supra 하이브리드):

```py
>>> config = SupertuningConfig(
...     target_modules=["q_proj", "v_proj"],
...     sparsity=0.99,
...     r=8,
...     lora_alpha=16,
... )
>>> model = get_peft_model(base, config)
```

논문: https://arxiv.org/abs/2607.09287