# カスタムレイヤーとユーティリティ

このページでは、ライブラリで使用されるすべてのカスタムレイヤー、およびモデリングのために提供されるユーティリティ関数とクラスをリストしています。

これらの多くは、ライブラリ内のモデルのコードを研究する場合にのみ有用です。

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

WeightRenaming 変換のペアのリストを適用し、最初の（「ガード」）ソースパターンによって遅延評価で有効化します。2つのリネームが中間名を共有する場合（例: `norm0→norm1` と `norm1→norm2`）に使用してください。これにより、変換済みのチェックポイント（`norm1` と `norm2` はあるが `norm0` はない）を読み込んだ際に、リネームが誤って再適用されるのを防げます。

NOTE: `source_patterns` は、変換済みのチェックポイントに存在しないものが先頭に来るように並べ替えてください。 state dict はソートされたキー順に反復されるため、ガードパターンは依存するパターンよりも辞書順で小さい必要があります。そうしないと、依存するパターンは最初のパスでスキップされ、再試行されません。

## 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`は、何個のテンソルに分割するかを読み取るための設定フィールドです。任意の数のテンソルを連結する場合に便利です。

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

融合された QKV に対して、複素数 RoPE 重みを分割された 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)

融合された 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 = False`）。`model.set_gradient_checkpointing()` が呼び出されると、`gradient_checkpointing = True` に設定し、`_gradient_checkpointing_func` にチェックポイント関数を割り当てることで、勾配チェックポイントが有効になります。

重要:

`use_reentrant=True` を使用して勾配チェックポイントを実行する場合、勾配を必要とする入力（例: 隠れ状態）は、勾配を正しく伝播させるために、キーワード引数ではなく位置引数（`*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)
```

## アテンション関数[[transformers.AttentionInterface]]

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

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

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

許可されたアテンション関数を管理する辞書のようなオブジェクトです。`register()` を呼び出すことで、新しいアテンション関数を簡単に追加できます。モデルが既存のアテンション関数、例えば `sdpa` をローカルで上書きする必要がある場合は、`modeling_<model>.py` の内部でこのクラスの新しいインスタンスを宣言し、そのインスタンス上で宣言する必要があります。

#### 登録[[transformers.AttentionInterface.register]]

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

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

## アテンションマスク関数[[transformers.AttentionMaskInterface]]

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

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

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

#### 登録[[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 実装のフォワードパス。

**戻り値:**

デコレーションされたフォワードパス。

モデルが動的 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（およびGPT-2でも使用）において、Radford らによって定義された1次元畳み込み層。

基本的には線形層と同様に動作しますが、重みが転置されています。

## 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`) : チャンク化されたテンソルのチャンクサイズ: `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`、*optional*、デフォルトは 0) : インデックスを保持する次元。

**戻り値:** `torch.nn.Linear`

`requires_grad=True` を設定した新しいレイヤーとして、プルーニングされたレイヤーを扱います。

index のエントリのみを保持するように、線形層を剪定します。

ヘッドを削除するために使用されます。

