# データコラテーター

Data collatorは、データセット要素のリストを入力としてバッチを形成するオブジェクトです。これらの要素は、`train_dataset`または`eval_dataset`の要素と同じ型です。

バッチを構築するために、データコラテーターはパディングなどの処理を適用する場合があります。一部のデータコラテーター（[DataCollatorForLanguageModeling](/docs/transformers/v5.23.0/ja/main_classes/data_collator#transformers.DataCollatorForLanguageModeling) など）は、形成されたバッチに対してランダムなデータ拡張（ランダムマスキングなど）も適用します。

使用例は[サンプルノートブック](https://github.com/huggingface/notebooks/tree/main/examples)で確認できます。

## デフォルトのデータコラテーター[[transformers.default_data_collator]]

#### transformers.default_data_collator[[transformers.default_data_collator]]

```python
transformers.default_data_collator(features: list[typing.Any], return_tensors = 'pt')
```

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

非常にシンプルなデータコラレーターです。dict 形式のオブジェクトのバッチをコラートし、以下の名前を持つ可能性のあるキーに対して特別な処理を行います。

- `label`: 1つのオブジェクトにつき1つの値（intまたはfloat）を処理します
- `label_ids`: オブジェクトごとの値のリストを処理します

追加の前処理は行いません。入力オブジェクトのプロパティ名が、モデルの対応する入力として使用されます。その有用性については、glueやnerを例として参照してください。

## DefaultDataCollator[[transformers.DefaultDataCollator]]

#### transformers.DefaultDataCollator[[transformers.DefaultDataCollator]]

```python
transformers.DefaultDataCollator(return_tensors: str = 'pt')
```

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

**パラメータ:**

return_tensors (`str`、*任意*、デフォルトは `"pt"`) : 返す Tensor の型。許可される値は "np" または "pt" です。

非常にシンプルなデータコラレーターです。dict 形式のオブジェクトのバッチをコラートし、以下の名前を持つ可能性のあるキーに対して特別な処理を行います。

- `label`: 1つのオブジェクトにつき1つの値（intまたはfloat）を処理します
- `label_ids`: オブジェクトごとの値のリストを処理します

追加の前処理は行いません。入力オブジェクトのプロパティ名が、モデルの対応する入力として使用されます。その有用性については、glueやnerを例として参照してください。

これは純粋な関数であるdefault_data_collatorとは異なり、他のデータコラクターと同様にオブジェクトです。初期化時にreturn_tensorsの値を設定する必要がある場合に、この点が役立ちます。

## DataCollatorWithPadding[[transformers.DataCollatorWithPadding]]

#### transformers.DataCollatorWithPadding[[transformers.DataCollatorWithPadding]]

```python
transformers.DataCollatorWithPadding(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt')
```

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

**パラメータ:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend)) : データのエンコードに使用されるトークナイザー。

padding (`bool`、`str` または [PaddingStrategy](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*optional*、デフォルトは `True`) : 返されるシーケンスのパディング戦略を選択します（モデルのパディング側とパディングインデックスに従います）。選択肢は以下の通りです。 - `True` または `'longest'`（デフォルト）: バッチ内の最も長いシーケンスまでパディングします（単一のシーケンスのみが提供された場合はパディングしません）。 - `'max_length'`: 引数 `max_length` で指定された最大長までパディングします。この引数が提供されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。 - `False` または `'do_not_pad'`: パディングなし（つまり、長さが異なるシーケンスのバッチを出力できます）。

max_length (`int`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

pad_to_multiple_of (`int`, *optional*) : 設定すると、シーケンスを指定された値の倍数にパディングします。これは、計算能力が 7.0 以上 (Volta) の NVIDIA ハードウェアで Tensor Cores を有効にするために特に有用です。

return_tensors (`str`、*任意*、デフォルトは `"pt"`) : 返す Tensor の型。許可される値は "np" または "pt" です。

動的にパディングを行うデータコラテーター

## DataCollatorForTokenClassification[[transformers.DataCollatorForTokenClassification]]

#### transformers.DataCollatorForTokenClassification[[transformers.DataCollatorForTokenClassification]]

```python
transformers.DataCollatorForTokenClassification(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, label_pad_token_id: int = -100, return_tensors: str = 'pt')
```

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

**パラメータ:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend)) : データのエンコードに使用されるトークナイザー。

padding (`bool`、`str` または [PaddingStrategy](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*optional*、デフォルトは `True`) : 返されるシーケンスのパディング戦略を選択します（モデルのパディング側とパディングインデックスに従います）。選択肢は以下の通りです。 - `True` または `'longest'`（デフォルト）: バッチ内の最も長いシーケンスまでパディングします（単一のシーケンスのみが提供された場合はパディングしません）。 - `'max_length'`: 引数 `max_length` で指定された最大長までパディングします。この引数が提供されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。 - `False` または `'do_not_pad'`: パディングなし（つまり、長さが異なるシーケンスのバッチを出力できます）。

max_length (`int`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

pad_to_multiple_of (`int`, *optional*) : 設定すると、シーケンスを指定された値の倍数にパディングします。これは、計算能力が 7.0 以上 (Volta) の NVIDIA ハードウェアで Tensor Cores を有効にするために特に有用です。

label_pad_token_id (`int`、*optional*、デフォルトは -100) : ラベルのパディングに使用する id（-100 は PyTorch の損失関数によって自動的に無視されます）。

return_tensors (`str`、*任意*、デフォルトは `"pt"`) : 返す Tensor の型。許可される値は "np" または "pt" です。

受け取った入力およびラベルを動的にパディングするデータコラテーターです。

## DataCollatorForSeq2Seq[[transformers.DataCollatorForSeq2Seq]]

#### transformers.DataCollatorForSeq2Seq[[transformers.DataCollatorForSeq2Seq]]

```python
transformers.DataCollatorForSeq2Seq(tokenizer: PreTrainedTokenizerBase, model: typing.Any | None = None, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, label_pad_token_id: int = -100, return_tensors: str = 'pt')
```

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

**パラメータ:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend)) : データのエンコードに使用されるトークナイザー。

model ([PreTrainedModel](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.PreTrainedModel)、*optional*) : 学習対象のモデルです。設定されており、*prepare_decoder_input_ids_from_labels* を持つ場合、*decoder_input_ids* の準備にこれを使用します。*label_smoothing* を使用する場合に、loss を2回計算することを避けるために有用です。

padding (`bool`、`str` または [PaddingStrategy](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*optional*、デフォルトは `True`) : 返されるシーケンスのパディング戦略を選択します（モデルのパディング側とパディングインデックスに従います）。選択肢は以下の通りです。 - `True` または `'longest'`（デフォルト）: バッチ内の最も長いシーケンスまでパディングします（単一のシーケンスのみが提供された場合はパディングしません）。 - `'max_length'`: 引数 `max_length` で指定された最大長までパディングします。この引数が提供されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。 - `False` または `'do_not_pad'`: パディングなし（つまり、長さが異なるシーケンスのバッチを出力できます）。

max_length (`int`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

pad_to_multiple_of (`int`, *optional*) : 設定すると、シーケンスを指定された値の倍数にパディングします。これは、計算能力が 7.0 以上 (Volta) の NVIDIA ハードウェアで Tensor Cores を有効にするために特に有用です。

label_pad_token_id (`int`、*optional*、デフォルトは -100) : ラベルのパディングに使用する id（-100 は PyTorch の損失関数によって自動的に無視されます）。

return_tensors (`str`、*任意*、デフォルトは `"pt"`) : 返す Tensor の型。許可される値は "np" または "pt" です。

受け取った入力およびラベルを動的にパディングするデータコラテーターです。

## DataCollatorForLanguageModeling[[transformers.DataCollatorForLanguageModeling]]

#### transformers.DataCollatorForLanguageModeling[[transformers.DataCollatorForLanguageModeling]]

```python
transformers.DataCollatorForLanguageModeling(tokenizer: PreTrainedTokenizerBase, mlm: bool = True, whole_word_mask: bool = False, mlm_probability: float | None = 0.15, mask_replace_prob: float = 0.8, random_replace_prob: float = 0.1, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt', seed: int | None = None)
```

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

**パラメータ:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend)) : データのエンコードに使用されるトークナイザー。

mlm (`bool`、*任意*、デフォルトは`True`) : マスク言語モデリングを使用するかどうか。`False`に設定した場合、ラベルは入力と同じになり、パディングトークンは無視されます（-100に設定されます）。それ以外の場合、ラベルはマスクされていないトークンに対して-100、マスクされたトークンに対しては予測する値になります。

whole_word_mask (`bool`, *任意*, デフォルトは `False`) : 個々のトークンではなく、単語全体をマスクするかどうかを指定します。

mlm_probability (`float`、*任意*、デフォルト値は 0.15) : `mlm` が `True` に設定されている場合、入力内のトークンを（ランダムに）マスクする確率です。

mask_replace_prob (`float`、*任意*、デフォルトは 0.8) : マスクされたトークンが、トークナイザーのマスクトークン（例: `[MASK]`）に置き換えられる確率です。デフォルトは 0.8 で、マスクされたトークンの 80% が `[MASK]` に置き換えられます。`mlm` が `True` に設定されている場合のみ有効です。

random_replace_prob (`float`、*任意*、デフォルト値は 0.1) : マスクされたトークンを、トークナイザーの語彙からランダムに選択したトークンに置き換える確率です。デフォルト値は 0.1 で、マスクされたトークンの 10% がランダムなトークンに置き換えられます。残りのマスクされたトークン (1 - mask_replace_prob - random_replace_prob) は変更されません。`mlm` が `True` に設定されている場合のみ有効です。

pad_to_multiple_of (`int`, *optional*) : 設定されている場合、シーケンスを指定された値の倍数にパディングします。

return_tensors (`str`) : 返す Tensor の型。許可される値は "np" または "pt" です。

seed (`int`, *optional*) : マスキング用の乱数生成器に使用するシードです。指定しない場合、グローバルRNGが使用されます。

言語モデリングに使用されるデータコラレーターです。すべての入力が同じ長さでない場合、バッチ内の最大長に合わせて動的にパディングが行われます。

最適なパフォーマンスを得るには、[PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend) が `return_special_tokens_mask=True` を引数として返す、`"special_tokens_mask"` キーを持つ辞書または BatchEncoding のアイテムを含むデータセットと組み合わせて、このデータコラテーターを使用してください。

1. デフォルトの動作:
   - `mask_replace_prob=0.8`, `random_replace_prob=0.1`.
   - マスクされたトークンの80%は`[MASK]`に置き換えられ、10%はランダムなトークンに置き換えられ、10%は変更されないことを想定してください。

2. `[MASK]` に置き換えられたすべてのマスク済みトークン:
   - `mask_replace_prob=1.0`, `random_replace_prob=0.0`.
   - すべてのマスクされたトークンは`[MASK]`に置き換えられることを期待します。変更されないトークンや、ランダムなトークンに置き換えられるトークンは存在しません。

3. `[MASK]`の置換は行わず、ランダムなトークンのみを使用します:
   - `mask_replace_prob=0.0`, `random_replace_prob=1.0`.
   - すべてのマスクされたトークンがランダムなトークンに置き換えられることを期待します。`[MASK]`への置き換えや、変更されないトークンは存在しません。

4. バランスの取れた置換:
   - `mask_replace_prob=0.5`, `random_replace_prob=0.4`.
   - マスクされたトークンの50%は`[MASK]`に、40%はランダムなトークンに置き換えられ、10%は変更されません。

注: `mask_replace_prob`と`random_replace_prob`の合計は1を超えてはいけません。合計が1未満の場合、残りの割合は変更されないマスクトークンで構成されます。

#### numpy_mask_tokens[[transformers.DataCollatorForLanguageModeling.numpy_mask_tokens]]

```python
numpy_mask_tokens(inputs: Any, special_tokens_mask: typing.Any | None = None, offset_mapping: typing.Any | None = None)
```

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

マスク言語モデリング用のマスク済みトークン入力/ラベルを準備します。

#### torch_mask_tokens[[transformers.DataCollatorForLanguageModeling.torch_mask_tokens]]

```python
torch_mask_tokens(inputs: Any, special_tokens_mask: typing.Any | None = None, offset_mapping: typing.Any | None = None)
```

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

マスク言語モデリング用のマスク済みトークン入力/ラベルを準備します。

## DataCollatorForPermutationLanguageModeling[[transformers.DataCollatorForPermutationLanguageModeling]]

#### transformers.DataCollatorForPermutationLanguageModeling[[transformers.DataCollatorForPermutationLanguageModeling]]

```python
transformers.DataCollatorForPermutationLanguageModeling(tokenizer: PreTrainedTokenizerBase, plm_probability: float = 0.16666666666666666, max_span_length: int = 5, return_tensors: str = 'pt')
```

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

置換言語モデリングに使用されるデータコラテーター。

- collates は、テンソルのバッチを結合し、そのトークナイザーの pad_token を尊重します。
- XLNet固有の手順を用いて、置換言語モデリング用のバッチを前処理します

#### numpy_mask_tokens[[transformers.DataCollatorForPermutationLanguageModeling.numpy_mask_tokens]]

```python
numpy_mask_tokens(inputs: Any)
```

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

特定のシーケンスにおいて予測対象となるマスク済みトークンは、以下のアルゴリズムによって決定されます。

0. `cur_len = 0`（これまでに処理されたトークンの数）を設定して、シーケンスの先頭から開始します。
1. `[1, max_span_length]` の区間から `span_length` をサンプリングします（マスク対象のトークンスパンの長さ）
2. マスク対象のスパンを囲むために、`context_length = span_length / plm_probability` の長さのコンテキストを確保します
3. 区間`[cur_len, cur_len + context_length - span_length]`から開始位置`start_index`をサンプリングし、トークン`start_index:start_index + span_length`をマスクします。
4. `cur_len = cur_len + context_length` を設定します。`cur_len < max_len` の場合（つまり、処理対象のシーケンスに未処理のトークンが残っている場合）、ステップ 1 から繰り返します。

#### torch_mask_tokens[[transformers.DataCollatorForPermutationLanguageModeling.torch_mask_tokens]]

```python
torch_mask_tokens(inputs: Any)
```

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

特定のシーケンスにおいて予測対象となるマスク済みトークンは、以下のアルゴリズムによって決定されます。

0. `cur_len = 0`（これまでに処理されたトークンの数）を設定して、シーケンスの先頭から開始します。
1. `[1, max_span_length]` の区間から `span_length` をサンプリングします（マスク対象のトークンスパンの長さ）
2. マスク対象のスパンを囲むために、`context_length = span_length / plm_probability` の長さのコンテキストを確保します
3. 区間`[cur_len, cur_len + context_length - span_length]`から開始位置`start_index`をサンプリングし、トークン`start_index:start_index + span_length`をマスクします。
4. `cur_len = cur_len + context_length` を設定します。`cur_len < max_len` の場合（つまり、処理対象のシーケンスに未処理のトークンが残っている場合）、ステップ 1 から繰り返します。

## DataCollatorWithFlattening[[transformers.DataCollatorWithFlattening]]

#### transformers.DataCollatorWithFlattening[[transformers.DataCollatorWithFlattening]]

```python
transformers.DataCollatorWithFlattening(*args, return_position_ids = True, separator_id = -100, return_flash_attn_kwargs = False, return_seq_idx = False, position_ids_start = 0, **kwargs)
```

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

**パラメータ:**

return_position_ids (`bool`、*任意*、デフォルトは `True`) : 各フラット化されたシーケンスごとに `position_ids_start` から再開する `position_ids` を返すかどうか。

separator_id (`int`、*任意*、デフォルトは -100) : 連結された`labels`内のシーケンスを区切るために使用される値。

return_flash_attn_kwargs (`bool`, *任意*, デフォルトは `False`) : FlashAttention で使用されるシーケンス境界の kwargs (`cu_seq_lens_q`、`cu_seq_lens_k`、`max_length_q` および `max_length_k`) を返すかどうかを指定します。

return_seq_idx (`bool`、*任意*、デフォルトは`False`) : 各トークンがどのシーケンスに属しているかを示す`seq_idx`を返すかどうか。

position_ids_start (`int`、*optional*、デフォルトは 0) : 各シーケンスの最初のトークンに割り当てられる position id。

パディングなしのアプローチで使用するデータコラテーター。以下を実行します:

- concatenates は、ミニバッチ全体を [1, total_tokens] の形状を持つ単一の長いシーケンスに連結します
- `separator_id` を使用して、連結された `labels` 内のシーケンスを区切ります。デフォルト値は -100 です。
- パディングは追加されず、デフォルトでは`input_ids`、`labels`、`position_ids`を返します
- FlashAttentionKwargs に含まれる kwargs を任意で返します
- 各トークンがどのシーケンスに属しているかを示す seq_idx を任意で返します

`DataCollatorWithFlattening` を使用すると、ミニバッチ全体が1つの長いシーケンスにフラット化されます。アテンションの計算がこれに対応できることを確認してください。

モデルが位置 ID を自身で計算する場合、必ずしも 0 から番号付けするとは限りません。`roberta`、`xlm_roberta`、`camembert`、`mpnet`、`esm` といった、絶対位置埋め込みを持つ RoBERTa 系のアーキテクチャは、`padding_idx + 1`（通常は 2）から番号付けを開始します。これらのモデルにデフォルトの 0 始まりの `position_ids` を渡すと、位置埋め込みが静かにずれて出力の品質が低下するため、該当するモデルでは `position_ids_start` を適切に設定してください。

## DataCollatorForMultipleChoice[[transformers.DataCollatorForMultipleChoice]]

#### transformers.DataCollatorForMultipleChoice[[transformers.DataCollatorForMultipleChoice]]

```python
transformers.DataCollatorForMultipleChoice(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt')
```

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

**パラメータ:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.PythonBackend) または [PreTrainedTokenizerFast](/docs/transformers/v5.23.0/ja/main_classes/tokenizer#transformers.TokenizersBackend)) : データのエンコードに使用されるトークナイザー。

padding (`bool`、`str`、または [PaddingStrategy](/docs/transformers/v5.23.0/ja/internal/file_utils#transformers.utils.PaddingStrategy)、*省略可能*、デフォルトは `True`) : モデルの padding side と padding index に従って、返されるシーケンスをパディングする戦略を以下のいずれかから選択します。 - `True` または `'longest'`: バッチ内の最も長いシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。 - `'max_length'`: 引数 `max_length` で指定された最大長、またはその引数が提供されていない場合はモデルが受け入れられる最大入力長までパディングします。 - `False` または `'do_not_pad'`（デフォルト）: パディングを行いません（つまり、長さが異なるシーケンスを含むバッチを出力できます）。

max_length (`int`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

pad_to_multiple_of (`int`, *optional*) : シーケンスを指定された値の倍数にパディングします。これは、計算能力が 7.5 以上 (Volta) の NVIDIA ハードウェアで Tensor Cores を有効にするために特に有用です。

return_tensors (`str`、*任意*、デフォルトは `"pt"`) : 返す Tensor の型。許可される値は "np" または "pt" です。

動的にパディングを行うデータコラテーターです。複数選択問題のネストされた例のバッチに対して、すべての例のすべての選択肢が同じ長さになるようにパディングを適用します。

