# Capas y utilidades personalizadas

Esta página enumera todas las capas personalizadas que utiliza la biblioteca, así como las funciones y clases de utilidad que proporciona para el modelado.

La mayoría de ellas solo son útiles si estás estudiando el código de los modelos de la biblioteca.

## WeightRenaming[[transformers.GroupWeightRename]]

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

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

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

Aplica una lista de transformaciones de WeightRenaming emparejadas, activadas de forma perezosa por el primer patrón de origen ("guard"). Úsela cuando dos renombramientos compartan un nombre intermedio (p. ej., `norm0→norm1` y `norm1→norm2`) para que la carga de un checkpoint ya convertido (que tiene `norm1` y `norm2` pero no `norm0`) no vuelva a aplicar incorrectamente los renombramientos.

NOTA: ordene `source_patterns` de modo que el patrón que no está presente en un checkpoint ya convertido aparezca primero. El state dict se itera en orden de claves ordenadas, por lo que el patrón de guarda debe ser lexicográficamente menor que los patrones dependientes. De lo contrario, los dependientes se omitirán en el primer paso y nunca se reintentarán.

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

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

### Operaciones de conversión[[transformers.ConversionOps]]

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

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

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

Clase base para operaciones de conversión de pesos.

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

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

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

Divide un tensor a lo largo de `dim` en fragmentos de tamaño igual. Además, `num_shards_attribute` es un campo de configuración que se lee para saber en cuántos fragmentos dividir los tensores. Útil al concatenar un número arbitrario de tensores.

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

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

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

Concatena tensores a lo largo de `dim`. Además, si se concatenan un número arbitrario de tensores, `num_shards_attribute` es un campo de configuración que se lee para saber cuántos tensores hay que recrear al usar las operaciones opuestas.

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

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

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

Fusiona una lista de tensores en un solo tensor a lo largo de la primera dimensión. Definimos esto explícitamente porque, en el caso de EP o TP, es importante asegurarse de saber lo que se está haciendo.

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

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

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

Inverso de `MergeModulelist` usando tamaños de división explícitos por grupo.

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

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

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

Aplica la permutación necesaria para convertir los pesos complejos de RoPE al formato dividido en sin/cos.

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

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

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

Aplica la permutación necesaria para convertir los pesos complejos de RoPE al formato de sin/cos separados en QKV fusionado. Es lo mismo que llamar a `PermuteForRope() + Concatenate()`, pero nos permite llamar a `Permute` solo en un subconjunto de tensores fragmentados.

NOTA: esta conversión se aplica solo a un backbone de visión en modelos multimodales, porque comprueba `config.vision_config`

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

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

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

Aplica la permutación necesaria para convertir los pesos complejos de RoPE al formato dividido sin/cos en QKV fusionado. Es lo mismo que llamar a `Chunk() + PermuteForRope()`, pero nos permite llamar a `Permute` solo en un subconjunto de tensores segmentados.

NOTA: esta conversión se aplica solo a un backbone de visión en modelos multimodales, porque comprueba `config.vision_config`

## Capas[[transformers.GradientCheckpointingLayer]]

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

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

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

Clase base para capas con punto de control de gradiente.

Esta clase habilita la funcionalidad de *gradient checkpointing* para una capa. De forma predeterminada, el *gradient checkpointing* está deshabilitado (`gradient_checkpointing = False`). Cuando se llama a `model.set_gradient_checkpointing()`, se habilita el *gradient checkpointing* estableciendo `gradient_checkpointing = True` y asignando una función de *checkpointing* a `_gradient_checkpointing_func`.

Importante:

Al usar gradient checkpointing con `use_reentrant=True`, las entradas que requieren gradientes (p. ej., hidden states) deben pasarse como argumentos posicionales (`*args`) en lugar de argumentos por nombre para propagar correctamente los gradientes.

Ejemplo:

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

## Funciones de atención[[transformers.AttentionInterface]]

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

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

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

Objeto tipo diccionario que mantiene un registro de las funciones de atención permitidas. Puede agregar fácilmente una nueva función de atención mediante una llamada a `register()`. Si un modelo necesita sobrescribir localmente una función de atención existente, por ejemplo `sdpa`, debe declarar una nueva instancia de esta clase dentro de `modeling_<model>.py` y declararla en esa instancia.

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

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

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

## Funciones de máscara de atención[[transformers.AttentionMaskInterface]]

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

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

[Fuente](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)
```

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

## Funciones de incrustación de posición rotacional[[transformers.dynamic_rope_update]]

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

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

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

**Parámetros:**

rope_forward (Callable) : La pasada hacia adelante de la implementación de RoPE.

**Devuelve:**

La pasada hacia adelante decorada.

Función decoradora para actualizar los parámetros de RoPE en la pasada hacia adelante, si el modelo está utilizando un RoPE dinámico (es decir, una implementación de RoPE que puede recalcular sus frecuencias en la pasada hacia adelante).

## Módulos personalizados de Pytorch[[transformers.Conv1D]]

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

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

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

**Parámetros:**

nf (`int`) : El número de características de salida.

nx (`int`) : El número de características de entrada.

Capa de convolución 1D definida por Radford et al. para OpenAI GPT (y también utilizada en GPT-2).

Básicamente funciona como una capa lineal, pero los pesos están transpuestos.

## Funciones auxiliares de 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)
```

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

**Parámetros:**

forward_fn (`Callable[..., torch.Tensor]`) : La función forward del modelo.

chunk_size (`int`) : El tamaño de bloque de un tensor por bloques: `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : La dimensión sobre la que se deben dividir los `input_tensors`.

input_tensors (`tuple[torch.Tensor]`) : Los tensores de entrada de `forward_fn` que se dividirán en fragmentos

**Devuelve:** `torch.Tensor`

Un tensor con la misma forma que habría dado `forward_fn` si se hubiera aplicado`.

Esta función divide `input_tensors` en partes de tensor de entrada más pequeñas de tamaño `chunk_size` a lo largo de la dimensión `chunk_dim`. A continuación, aplica la capa `forward_fn` a cada fragmento de forma independiente para ahorrar memoria.

Si `forward_fn` es independiente a lo largo de `chunk_dim`, esta función producirá el mismo resultado que aplicar `forward_fn` directamente a `input_tensors`.

Ejemplos:

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

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

**Parámetros:**

layer (`torch.nn.Linear`) : La capa a podar.

index (`torch.LongTensor`) : Los índices que se conservarán en la capa.

dim (`int`, *opcional*, valor predeterminado 0) : La dimensión en la que se deben conservar los índices.

**Devuelve:** `torch.nn.Linear`

La capa podada como una nueva capa con `requires_grad=True`.

Recorta una capa lineal para conservar solo las entradas en index.

Se utiliza para eliminar cabezas.

