# Super-Tuning

[Super-Tuning](https://huggingface.co/papers/2607.09287) est une méthode de fine-tuning creux qui fige les poids de base et n’entraîne qu’un support creux d’entrées scalaires sélectionnées par magnitude des poids. La définition de `r` alloue en outre un adaptateur de faible rang de type LoRA, composé de manière additive par-dessus le support creux (l’hybride « Supra » de l’article).

Le score par défaut est basé uniquement sur l’amplitude et ne requiert aucune donnée. L’ablation 8B du rapport indique que `magnitude-topk` obtient en moyenne 79,02 %, surpassant la saillance pondérée par Wanda à 78,66 %, tout en ne nécessitant aucune passe de calibration. Le score pondéré par les activations de type Wanda n’est pas proposé par cette implémentation.

Super-Tuning présente actuellement la contrainte suivante :

- Seules les couches `nn.Linear` sont prises en charge.

L'abstract de l'article est :

> Le fine-tuning de grands modèles de langage à l'aide de méthodes efficaces en termes de paramètres est devenu une pratique standard, mais les approches existantes comme LoRA restreignent le sous-espace entraînable à une décomposition de faible rang. Nous introduisons Super-Tuning, une approche de fine-tuning creux qui sélectionne à la place un petit support d'entrées scalaires individuelles de poids — un ensemble entraînable de rang non restreint à un budget de paramètres fixe. La sélection est guidée par des signaux de saillance inspirés de l'élagage : un score basé uniquement sur l'amplitude (style PaFi) ou un score pondéré par les activations (style Wanda). Nous montrons que, sur les fine-tunes de Llama-3.2-1B et Meta-Llama-3-8B évalués sur Math17K, Super-Tuning basé sur l'amplitude égale ou dépasse LoRA à des budgets de paramètres comparables, et qu'une variante hybride « Supra » — combinant un support creux avec un composant de faible rang — améliore encore la précision en aval.

## Aperçu des benchmarks

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

## Utilisation

**Pure Super (notation par magnitude, sans données) :**

```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)
```

**Hybride Supra** (prise en charge des structures creuses + LoRA composées de manière additive) :

```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)
```

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

**Paramètres :**

target_modules (`Optional[Union[List[str], str]]`) : Les noms des modules auxquels appliquer l'adaptateur. Chaîne de caractères → correspondance par expression régulière ; liste → correspondance par suffixe / exacte ; None → valeur par défaut de l'architecture du modèle.

modules_to_save (`Optional[List[str]]`) : Modules situés en dehors des couches de Supertuning qui doivent également être entraînables et sauvegardés dans le point de contrôle final (par exemple, des têtes de classifieurs initialisés aléatoirement).

sparsity (`float`) : Ratio de sparsité cible dans `[0.0, 1.0)`. `0.99` = 1 % des entrées de poids sont entraînables. Valeur par défaut : `0.99`.

select_top (`bool`) : Extrémité du score d'amplitude à conserver comme support entraînable. `True` conserve les entrées de plus grande amplitude (Super / Supra de l'article) ; `False` conserve les plus petites (variantes `-bottom` de l'article). L'article indique que la meilleure direction dépend du modèle et de la tâche. Valeur par défaut : `True`.

r (`Optional[int]`) : rang LoRA pour l'hybride « Supra ». Lorsque `None` (par défaut), seul le support creux est entraînable (mode Super). Lorsqu'il est défini sur un entier positif, alloue en outre les paramètres LoRA `A` (`[r, in_features]`) et `B` (`[out_features, r]`) dont la contribution est ajoutée au support creux lors du passage avant.

lora_alpha (`Optional[float]`) : Facteur d'échelle LoRA pour le mode Supra. Si `None` et que `r` est défini, la valeur par défaut est `2 * r`. Ignoré lorsque `r is None`.

lora_dropout (`float`) : Probabilité de dropout LoRA pour le mode Supra. Valeur par défaut : `0.0`. Ignoré lorsque `r is None`.

init_weights (`bool`) : Si `True` (par défaut), les `values` creuses sont initialisées à zéro et `B` de LoRA est initialisé à zéro — l’adaptateur est une mise à jour identité à la construction. Si `False`, les deux sont initialisés avec une distribution uniforme de Kaiming (utilisé par les tests pour exercer un adaptateur non trivial). `A` de LoRA utilise une distribution uniforme de Kaiming dans les deux cas.

save_precomputed_indices (`bool`) : Indique s'il faut enregistrer les indices de support creux dans le dictionnaire d'état. La valeur par défaut est `True`. Définissez cette valeur sur `False` pour réduire la taille du point de contrôle — les indices seront reconstruits de manière déterministe à partir des amplitudes des poids de base au moment du chargement. La reconstruction suppose que les poids du modèle de base sont identiques à ceux utilisés lors de l'entraînement ; un léger dérive numérique peut entraîner des différences dans la résolution des égalités lors du topk.

Classe de configuration pour [SupertuningModel](/docs/peft/main/fr/package_reference/supertuning#peft.SupertuningModel).

Super-Tuning (arXiv:2607.09287) fige les poids de base et n’entraîne qu’un support sparse d’entrées scalaires, sélectionnées par magnitude des poids. La configuration `r` alloue en outre un adaptateur de faible rang de type LoRA par-dessus le support sparse (l’hybride « Supra » de l’article).

La configuration par défaut (score par magnitude, `r=None`) reproduit la configuration à mécanisme unique la mieux rapportée dans l'article : sur Meta-Llama-3-8B, `magnitude-topk` obtient une moyenne de 79,02 %, dépassant `Wanda` à 78,66 %, et ne nécessite aucune passe de calibration. Le score pondéré par activation de type Wanda n'est pas proposé par cette implémentation.

Article : 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)
```

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

**Paramètres :**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : le modèle de base à adapter.

config ([SupertuningConfig](/docs/peft/main/fr/package_reference/supertuning#peft.SupertuningConfig)) : La configuration de Supertuning.

adapter_name (`str`) : Le nom de l'adaptateur. La valeur par défaut est `"default"`.

low_cpu_mem_usage (`bool`, *facultatif*) : Crée des poids d'adaptateur vides sur le périphérique meta pour accélérer le chargement.

**Retourne :** `torch.nn.Module`

Le modèle enveloppé par Supertuning.

Super-Tuning tuner (arXiv:2607.09287).

Gèle les poids de base et n’entraîne qu’un support creux d’entrées scalaires sélectionnées par magnitude des poids (configuration à mécanisme unique la plus performante de l’article ; sans données). Lorsque `config.r` est défini, alloue en outre des paramètres LoRA A/B composés de manière additive avec le support creux — l’hybride Supra de l’article.

Example (pure 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 hybride) :

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

Article : https://arxiv.org/abs/2607.09287

