# Camadas e utilitários personalizados

Esta página lista todas as camadas personalizadas usadas pela biblioteca, bem como as funções e classes utilitárias que ela fornece para modelagem.

A maioria delas só é útil se você estiver estudando o código dos modelos da biblioteca.

## WeightRenaming[[transformers.GroupWeightRename]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L1079)

Aplica uma lista de transformações de renomeação de pesos em pares, ativadas de forma preguiçosa pelo primeiro padrão de origem ("guard"). Use isso quando dois renomeamentos compartilham um nome intermediário (por exemplo, `norm0→norm1` e `norm1→norm2`) para que a carga de um checkpoint já convertido (que possui `norm1` e `norm2`, mas não `norm0`) não re aplique incorretamente os renomeamentos.

OBSERVAÇÃO: ordene `source_patterns` de modo que o padrão ausente em um checkpoint já convertido apareça primeiro. O state dict é iterado em ordem alfabética das chaves, portanto o padrão de guarda deve ser lexicograficamente menor que os padrões dependentes. Caso contrário, os dependentes serão ignorados na primeira passagem e nunca serão reprocessados.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L1199)

### Operações de conversão[[transformers.ConversionOps]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L81)

Classe base para operações de conversão de pesos.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L112)

Divide um tensor ao longo de `dim` em blocos de tamanho igual. Além disso, `num_shards_attribute` é um campo de configuração para ler e saber em quantos blocos dividir os tensors. Útil ao concatenar um número arbitrário de tensors.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L183)

Concatene tensores ao longo de `dim`. Além disso, ao concatenar um número arbitrário de tensores, `num_shards_attribute` é um campo de configuração a ser lido para saber quantos tensores recriar ao usar as Ops opostas.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L255)

Mesclar uma lista de tensores em um único tensor ao longo da primeira dimensão. Definimos isso explicitamente porque, para EP ou TP, você precisa ter certeza de que sabe o que está fazendo!

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L306)

Inverso de `MergeModulelist` usando tamanhos de divisão 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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L461)

Aplica a permutação necessária para converter os pesos complexos do RoPE para o formato dividido em sin/cos.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L533)

Aplica a permutação necessária para converter os pesos complexos do RoPE para o formato de sin/cos separados em QKV fundido. É o mesmo que chamar `PermuteForRope() + Concatenate()`, mas permite chamar `Permute` apenas em um subconjunto de tensores em blocos.

OBSERVAÇÃO: essa conversão se aplica apenas a um backbone de visão em modelos multimodais, pois verifica `config.vision_config`

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/core_model_loading.py#L587)

Aplica a permutação necessária para converter os pesos complexos do RoPE para o formato de sin/cos separados em QKV fundido. É o mesmo que chamar `Chunk() + PermuteForRope()`, mas permite chamar `Permute` apenas em um subconjunto dos tensores em blocos.

OBSERVAÇÃO: essa conversão se aplica apenas a um backbone de visão em modelos multimodais, pois verifica `config.vision_config`

## Camadas[[transformers.GradientCheckpointingLayer]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_layers.py#L54)

Classe base para camadas com checkpointing de gradiente.

Esta classe habilita a funcionalidade de gradient checkpointing para uma camada. Por padrão, o gradient checkpointing está desativado (`gradient_checkpointing = False`). Quando `model.set_gradient_checkpointing()` é chamado, o gradient checkpointing é ativado ao definir `gradient_checkpointing = True` e atribuir uma função de checkpointing a `_gradient_checkpointing_func`.

Importante:

Ao usar gradient checkpointing com `use_reentrant=True`, as entradas que exigem gradientes (por exemplo, hidden states) devem ser passadas como argumentos posicionais (`*args`) em vez de argumentos por palavra-chave para propagar os gradientes corretamente.

Exemplo:

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

## Funções de Atenção[[transformers.AttentionInterface]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py#L5220)

Objeto com comportamento de dicionário que mantém o controle das funções de atenção permitidas. Você pode adicionar facilmente uma nova função de atenção com uma chamada para `register()`. Se um modelo precisa sobrescrever localmente uma função de atenção existente, por exemplo `sdpa`, ele precisa declarar uma nova instância desta classe dentro do `modeling_<model>.py` e declará-la nessa instância.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/generic.py#L1143)

## Funções de Máscara de Atenção[[transformers.AttentionMaskInterface]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/masking_utils.py#L697)

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/generic.py#L1143)

## Funções de incorporação de posição rotativa[[transformers.dynamic_rope_update]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L34)

**Parâmetros:**

rope_forward (Callable) : A passagem direta da implementação do RoPE.

**Retorna:**

A passagem de frente decorada.

Função decoradora para atualizar os parâmetros do RoPE na passagem direta, caso o modelo esteja usando um RoPE dinâmico (ou seja, uma implementação de RoPE que pode recalcular suas frequências na passagem direta).

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

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/pytorch_utils.py#L95)

**Parâmetros:**

nf (`int`) : O número de recursos de saída.

nx (`int`) : O número de recursos de entrada.

Camada de convolução 1D definida por Radford et al. para o OpenAI GPT (e também utilizada no GPT-2).

Basicamente, funciona como uma camada linear, mas os pesos são transpostos.

## Funções auxiliares do 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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/pytorch_utils.py#L124)

**Parâmetros:**

forward_fn (`Callable[..., torch.Tensor]`) : A função forward do modelo.

chunk_size (`int`) : O tamanho do bloco de um tensor em blocos: `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : A dimensão ao longo da qual os `input_tensors` devem ser divididos em blocos.

input_tensors (`tuple[torch.Tensor]`) : Os tensores de entrada de `forward_fn` que serão divididos em blocos

**Retorna:** `torch.Tensor`

Um tensor com a mesma forma que o `forward_fn` teria fornecido se fosse aplicado`.

Esta função divide o `input_tensors` em partes menores de tamanho `chunk_size` ao longo da dimensão `chunk_dim`. Em seguida, aplica a camada `forward_fn` a cada parte de forma independente para economizar memória.

Se o `forward_fn` for independente ao longo do `chunk_dim`, esta função produzirá o mesmo resultado que a aplicação direta de `forward_fn` a `input_tensors`.

Exemplos:

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/pytorch_utils.py#L61)

**Parâmetros:**

layer (`torch.nn.Linear`) : A camada a ser podada.

index (`torch.LongTensor`) : Os índices a serem mantidos na camada.

dim (`int`, *opcional*, padrão 0) : A dimensão na qual manter os índices.

**Retorna:** `torch.nn.Linear`

A camada podada como uma nova camada com `requires_grad=True`.

Prune uma camada linear para manter apenas as entradas em index.

Usado para remover cabeças.