# 커스텀 레이어 및 유틸리티

이 페이지에서는 라이브러리가 사용하는 모든 커스텀 레이어와 모델링을 위해 제공하는 유틸리티 함수 및 클래스를 나열합니다.

대부분은 라이브러리의 모델 코드를 연구하는 경우에만 유용합니다.

## WeightRenaming[[transformers.GroupWeightRename]]

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

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

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

첫 번째("guard") 소스 패턴에 의해 지연 활성화되는 쌍으로 짝지어진 WeightRenaming 변환 목록을 적용합니다. 두 개의 이름 변경이 중간 이름을 공유하는 경우(예: `norm0→norm1`와 `norm1→norm2`)에 이 기능을 사용하십시오. 이렇게 하면 이미 변환된 체크포인트(`norm1`와 `norm2`는 있지만 `norm0`는 없는 경우)를 로드할 때 이름 변경이 잘못되게 다시 적용되는 것을 방지할 수 있습니다.

NOTE: `source_patterns`는 이미 변환된 checkpoint에 없는 패턴이 앞에 오도록 정렬하세요. state dict는 정렬된 키 순서로 반복되므로, guard 패턴은 종속 패턴보다 사전 순으로 작아야 합니다. 그렇지 않으면 종속 항목이 첫 번째 패스에서 건너뛰어지고 다시 시도되지 않습니다.

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

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

### 변환 작업[[transformers.ConversionOps]]

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

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

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

가중치 변환 작업의 베이스 클래스입니다.

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

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

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

`dim`을 따라 텐서를 동일한 크기의 청크로 분할합니다. 또한 `num_shards_attribute`는 몇 개의 텐서로 청크를 분할할지 알기 위해 읽는 config 필드입니다. 임의의 개수의 텐서를 연결할 때 유용합니다.

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

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

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

`dim`을 따라 텐서를 연결합니다. 또한, 임의의 개수의 텐서를 연결하는 경우, `num_shards_attribute`는 반대 방향의 Ops를 사용할 때 재구성할 텐서의 개수를 파악하기 위해 읽는 설정 필드입니다.

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

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

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

첫 번째 차원을 따라 텐서 목록을 단일 텐서로 병합합니다. EP 또는 TP의 경우, 수행하는 작업에 대해 명확히 인지하고 있는지 확인해야 하므로 이 함수를 명시적으로 정의합니다.

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

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

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

각 그룹에 대해 명시적인 분할 크기를 사용하여 `MergeModulelist`의 역연산을 수행합니다.

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

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

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

복소수 RoPE 가중치를 분리된 sin/cos 형식으로 변환하는 데 필요한 순열을 적용합니다.

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

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

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

복합 RoPE 가중치를 융합된 QKV에 대한 분리된 sin/cos 형식으로 변환하는 데 필요한 순열을 적용합니다. `PermuteForRope() + Concatenate()`를 호출하는 것과 동일하지만, 청크된 텐서의 부분 집합에만 `Permute`를 호출할 수 있게 합니다.

참고: 이 변환은 멀티모달 모델의 비전 백본에만 적용됩니다. `config.vision_config`를 확인하기 때문입니다.

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

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

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

fused QKV에 대해 복소수 RoPE 가중치를 분리된 sin/cos 형식으로 변환하는 데 필요한 순열을 적용합니다. `Chunk() + PermuteForRope()`를 호출하는 것과 동일하지만, 분할된 텐서의 부분 집합에만 `Permute`를 호출할 수 있게 합니다.

참고: 이 변환은 멀티모달 모델의 비전 백본에만 적용됩니다. `config.vision_config`를 확인하기 때문입니다.

## 레이어[[transformers.GradientCheckpointingLayer]]

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

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

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

그라디언트 체크포인트링을 지원하는 레이어의 베이스 클래스입니다.

이 클래스는 레이어에 대한 gradient checkpointing 기능을 활성화합니다. 기본적으로 gradient checkpointing은 비활성화되어 있습니다(`gradient_checkpointing = False`). `model.set_gradient_checkpointing()`이 호출되면 `gradient_checkpointing = True`로 설정하고 `_gradient_checkpointing_func`에 checkpointing 함수를 할당하여 gradient checkpointing이 활성화됩니다.

중요:

`use_reentrant=True`로 gradient checkpointing을 사용할 때, gradient가 필요한 입력(예: hidden states)은 gradient가 올바르게 전파되도록 keyword argument가 아닌 positional argument(`*args`)로 전달해야 합니다.

예:

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

## Attention Functions[[transformers.AttentionInterface]]

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

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

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

허용된 attention 함수를 추적하는 dict 유사 객체입니다. `register()`를 호출하여 새로운 attention 함수를 쉽게 추가할 수 있습니다. 모델이 기존 attention 함수, 예: `sdpa`를 로컬에서 덮어쓰려면 `modeling_<model>.py` 내부에서 이 클래스의 새 인스턴스를 선언하고 해당 인스턴스에 선언해야 합니다.

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

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

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

## Attention Mask 함수[[transformers.AttentionMaskInterface]]

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

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

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

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

## Rotary Position Embedding 함수[[transformers.dynamic_rope_update]]

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

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

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

**매개변수:**

rope_forward (Callable) : RoPE 구현의 forward pass입니다.

**반환값:**

장식된 forward pass

모델이 동적 RoPE(즉, forward pass에서 주파수를 다시 계산할 수 있는 RoPE 구현)를 사용하는 경우, forward pass에서 RoPE 매개변수를 업데이트하는 데 사용되는 데코레이터 함수입니다.

## Pytorch 커스텀 모듈[[transformers.Conv1D]]

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

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

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

**매개변수:**

nf (`int`) : 출력 특징의 개수.

nx (`int`) : 입력 특징의 개수.

OpenAI GPT를 위해 Radford et al.이 정의한 1D-convolutional layer (GPT-2에서도 사용됨).

기본적으로 선형 레이어와 유사하게 작동하지만 가중치가 전치됩니다.

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

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

**매개변수:**

forward_fn (`Callable[..., torch.Tensor]`) : 모델의 forward 함수.

chunk_size (`int`) : chunked tensor의 chunk size: `num_chunks = len(input_tensors[0]) / chunk_size`.

chunk_dim (`int`) : `input_tensors`를 청크할 차원.

input_tensors (`tuple[torch.Tensor]`) : `forward_fn`의 입력 텐서로, 청킹됩니다

**반환값:** `torch.Tensor`

`forward_fn`을 적용했을 때 생성되었을 텐서와 동일한 형상을 가진 텐서

이 함수는 `input_tensors`를 `chunk_dim` 차원을 따라 `chunk_size` 크기의 더 작은 입력 텐서 조각으로 나눕니다. 그런 다음 각 조각에 대해 레이어 `forward_fn`을 독립적으로 적용하여 메모리를 절약합니다.

`forward_fn`이 `chunk_dim`에 대해 독립적이라면, 이 함수는 `input_tensors`에 `forward_fn`을 직접 적용했을 때와 동일한 결과를 반환합니다.

예:

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

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

**매개변수:**

layer (`torch.nn.Linear`) : 프루닝할 레이어.

index (`torch.LongTensor`) : 레이어에서 유지할 인덱스.

dim (`int`, *선택 사항*, 기본값 0) : 인덱스를 유지할 차원.

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

`requires_grad=True`를 가진 새로운 레이어로 프루닝된 레이어.

index에 있는 항목만 유지하도록 선형 레이어를 가지치기합니다.

헤드를 제거하는 데 사용됩니다.

