# Couches et utilitaires personnalisés

Cette page répertorie toutes les couches personnalisées utilisées par la bibliothèque, ainsi que les fonctions utilitaires et les classes qu'elle fournit pour la modélisation.

La plupart de ces éléments ne sont utiles que si vous étudiez le code des modèles de la bibliothèque.

## WeightRenaming[[transformers.GroupWeightRename]]

#### transformers.GroupWeightRename[[transformers.GroupWeightRename]]

```python
transformers.GroupWeightRename(source_patterns: list[str], target_patterns: list[str])
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L1087)

Applique une liste de transformations de renommage de poids appariées, activées paresseusement par le premier motif source (« garde »). Utilisez ceci lorsque deux renommages partagent un nom intermédiaire (par exemple `norm0→norm1` et `norm1→norm2`) afin que le chargement d’un point de contrôle déjà converti (qui contient `norm1` et `norm2` mais pas `norm0`) ne réapplique pas incorrectement les renommages.

NOTE : ordonnez `source_patterns` de manière à ce que celui qui est absent d'un point de contrôle déjà converti soit placé en premier. Le state dict est itéré dans l'ordre trié des clés, le motif de garde doit donc être lexicographiquement inférieur aux motifs dépendants. Sinon, les dépendants seront ignorés lors du premier passage et ne seront jamais réessayés.

## WeightConverter[[transformers.WeightConverter]]

#### transformers.WeightConverter[[transformers.WeightConverter]]

```python
transformers.WeightConverter(source_patterns: str | list[str], target_patterns: str | list[str], operations: list[ConversionOps], force_cpu: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L1231)

### Opérations de conversion[[transformers.ConversionOps]]

#### transformers.ConversionOps[[transformers.ConversionOps]]

```python
transformers.ConversionOps()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L81)

Classe de base pour les opérations de conversion de poids.

#### transformers.Chunk[[transformers.Chunk]]

```python
transformers.Chunk(dim: int = 0, num_shards_attribute: str | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L116)

Divise un tenseur le long de `dim` en blocs de taille égale. De plus, `num_shards_attribute` est un champ de configuration à lire pour savoir en combien de blocs diviser les tenseurs. Utile lors de la concaténation d'un nombre arbitraire de tenseurs.

#### transformers.Concatenate[[transformers.Concatenate]]

```python
transformers.Concatenate(dim: int = 0, num_shards_attribute: str | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L187)

Concatène les tenseurs le long de `dim`. De plus, lors de la concaténation d'un nombre arbitraire de tenseurs, `num_shards_attribute` est un champ de configuration à lire pour savoir combien de tenseurs recréer lors de l'utilisation des Ops opposés.

#### transformers.MergeModulelist[[transformers.MergeModulelist]]

```python
transformers.MergeModulelist(dim: int = 0)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L259)

Fusionne une liste de tenseurs en un seul tenseur le long de la première dimension. Nous définissons explicitement cette fonction car, pour EP ou TP, vous devez être certain de savoir ce que vous faites !

#### transformers.SplitModulelist[[transformers.SplitModulelist]]

```python
transformers.SplitModulelist(dim: int = 0)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L310)

Inverse de `MergeModulelist` utilisant des tailles de scission explicites par groupe.

#### transformers.PermuteForRope[[transformers.PermuteForRope]]

```python
transformers.PermuteForRope(subconfig_key: str | None = None, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L465)

Applique la permutation requise pour convertir les poids RoPE complexes au format sin/cos séparé.

#### transformers.VisionFuseAndPermuteForRope[[transformers.VisionFuseAndPermuteForRope]]

```python
transformers.VisionFuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = True)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L537)

Applique la permutation nécessaire pour convertir les poids RoPE complexes au format sin/cos séparé sur les QKV fusionnés. Équivalent à l'appel de `PermuteForRope() + Concatenate()`, mais permet d'appeler `Permute` uniquement sur un sous-ensemble de tenseurs fractionnés.

NOTE : cette conversion ne s'applique qu'à un backbone visuel dans les modèles multimodaux, car elle vérifie `config.vision_config`

#### transformers.VisionUnfuseAndPermuteForRope[[transformers.VisionUnfuseAndPermuteForRope]]

```python
transformers.VisionUnfuseAndPermuteForRope(dim: int = 0, permute_layer_names: list[str] | None = None, inverse: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/core_model_loading.py#L591)

Applique la permutation nécessaire pour convertir les poids RoPE complexes au format sin/cos séparé sur les QKV fusionnés. Équivalent à l'appel de `Chunk() + PermuteForRope()`, mais permet d'appeler `Permute` uniquement sur un sous-ensemble de tenseurs découpés.

NOTE : cette conversion ne s'applique qu'à un backbone visuel dans les modèles multimodaux, car elle vérifie `config.vision_config`

## Couches[[transformers.GradientCheckpointingLayer]]

#### transformers.GradientCheckpointingLayer[[transformers.GradientCheckpointingLayer]]

```python
transformers.GradientCheckpointingLayer(*args, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_layers.py#L54)

Classe de base pour les couches avec point de contrôle de gradient.

Cette classe permet d’activer le gradient checkpointing pour une couche. Par défaut, le gradient checkpointing est désactivé (`gradient_checkpointing = False`). Lorsque `model.set_gradient_checkpointing()` est appelé, le gradient checkpointing est activé en définissant `gradient_checkpointing = True` et en affectant une fonction de checkpointing à `_gradient_checkpointing_func`.

Important :

Lors de l’utilisation du gradient checkpointing avec `use_reentrant=True`, les entrées qui nécessitent des gradients (par exemple, les états cachés) doivent être transmises en tant qu’arguments positionnels (`*args`) plutôt qu’en arguments nommés, afin de propager correctement les gradients.

Exemple :

```python
>>> # Correct - hidden_states passed as positional arg
>>> out = self.layer(hidden_states, attention_mask=attention_mask)

>>> # Incorrect - hidden_states passed as keyword arg
>>> out = self.layer(hidden_states=hidden_states, attention_mask=attention_mask)
```

## Fonctions d'attention[[transformers.AttentionInterface]]

#### transformers.AttentionInterface[[transformers.AttentionInterface]]

```python
transformers.AttentionInterface()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_utils.py#L5234)

Objet de type dictionnaire qui suit les fonctions d'attention autorisées. Vous pouvez facilement ajouter une nouvelle fonction d'attention en appelant `register()`. Si un modèle doit remplacer localement une fonction d'attention existante, par exemple `sdpa`, il doit déclarer une nouvelle instance de cette classe dans `modeling_<model>.py` et la déclarer sur cette instance.

#### register[[transformers.AttentionInterface.register]]

```python
register(key: str, value: Callable)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/utils/generic.py#L1143)

## Fonctions de masque d'attention[[transformers.AttentionMaskInterface]]

#### transformers.AttentionMaskInterface[[transformers.AttentionMaskInterface]]

```python
transformers.AttentionMaskInterface()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/masking_utils.py#L733)

#### register[[transformers.AttentionMaskInterface.register]]

```python
register(key: str, value: Callable)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/utils/generic.py#L1143)

## Fonctions d'incorporation de position rotative[[transformers.dynamic_rope_update]]

#### transformers.dynamic_rope_update[[transformers.dynamic_rope_update]]

```python
transformers.dynamic_rope_update(rope_forward)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/modeling_rope_utils.py#L34)

**Paramètres :**

rope_forward (Callable) : Le passage avant de l'implémentation de RoPE.

**Retourne :**

Le passage avant décoré.

Fonction décorateur destinée à mettre à jour les paramètres de RoPE lors du passage avant, si le modèle utilise un RoPE dynamique (c’est-à-dire une implémentation de RoPE susceptible de recalculer ses fréquences lors du passage avant).

## Modules personnalisés PyTorch[[transformers.Conv1D]]

#### transformers.Conv1D[[transformers.Conv1D]]

```python
transformers.Conv1D(nf, nx)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L95)

**Paramètres :**

nf (`int`) : Le nombre de caractéristiques de sortie.

nx (`int`) : Le nombre de caractéristiques d'entrée.

Couche de convolution 1D telle que définie par Radford et al. pour OpenAI GPT (et également utilisée dans GPT-2).

Fonctionne essentiellement comme une couche linéaire, mais les poids sont transposés.

## Fonctions utilitaires PyTorch[[transformers.apply_chunking_to_forward]]

#### transformers.apply_chunking_to_forward[[transformers.apply_chunking_to_forward]]

```python
transformers.apply_chunking_to_forward(forward_fn: Callable[..., torch.Tensor], chunk_size: int, chunk_dim: int, *input_tensors)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L124)

**Paramètres :**

forward_fn (`Callable[..., torch.Tensor]`) : fonction avant du modèle.

chunk_size (`int`) : La taille de bloc d'un tensor par blocs : `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : La dimension sur laquelle les `input_tensors` doivent être fractionnés.

input_tensors (`tuple[torch.Tensor]`) : Les tenseurs d'entrée de `forward_fn` qui seront fractionnés

**Retourne :** `torch.Tensor`

Un tenseur de la même forme que celle que `forward_fn` aurait renvoyé s'il avait été appliqué`.

Cette fonction découpe les `input_tensors` en parties de tenseurs d'entrée plus petites de taille `chunk_size` sur la dimension `chunk_dim`. Elle applique ensuite la couche `forward_fn` à chaque fragment de manière indépendante afin d'économiser de la mémoire.

Si `forward_fn` est indépendant le long de `chunk_dim`, cette fonction produira le même résultat que l’application directe de `forward_fn` à `input_tensors`.

Exemples :

```python
# rename the usual forward() fn to forward_chunk()
def forward_chunk(self, hidden_states):
    hidden_states = self.decoder(hidden_states)
    return hidden_states

# implement a chunked forward function
def forward(self, hidden_states):
    return apply_chunking_to_forward(self.forward_chunk, self.chunk_size_lm_head, self.seq_len_dim, hidden_states)
```

#### transformers.pytorch_utils.prune_linear_layer[[transformers.pytorch_utils.prune_linear_layer]]

```python
transformers.pytorch_utils.prune_linear_layer(layer: nn.Linear, index: torch.LongTensor, dim: int = 0)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/pytorch_utils.py#L61)

**Paramètres :**

layer (`torch.nn.Linear`) : La couche à élaguer.

index (`torch.LongTensor`) : Les indices à conserver dans la couche.

dim (`int`, *facultatif*, valeur par défaut 0) : La dimension sur laquelle conserver les indices.

**Retourne :** `torch.nn.Linear`

La couche élaguée en tant que nouvelle couche avec `requires_grad=True`.

Supprimez une couche linéaire pour ne conserver que les entrées de l'index.

Utilisé pour supprimer des têtes.

