Transformers documentation

データコラテーター

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

データコラテーター

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

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

使用例はサンプルノートブックで確認できます。

デフォルトのデータコラテーター

transformers.default_data_collator

< >

( features: list[typing.Any]return_tensors = 'pt' )

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

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

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

DefaultDataCollator

class transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

パラメータ

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

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

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

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

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

DataCollatorWithPadding

class transformers.DataCollatorWithPadding

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

パラメータ

  • tokenizer(PreTrainedTokenizer または PreTrainedTokenizerFast)— データをエンコードするために使用されるトークナイザー。
  • padding (bool, str または PaddingStrategy, 省略可, デフォルトは True) — 返されるシーケンスのパディング戦略を選択します(モデルのパディング側とパディングインデックスに従います)。選択肢は以下の通りです: True または 'longest'(デフォルト):バッチ内の最も長いシーケンスまでパディングします(単一のシーケンスのみが提供された場合はパディングしません)。'max_length':引数 max_length で指定された最大長までパディングします。この引数が指定されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。False または 'do_not_pad':パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
    • True または 'longest'(デフォルト): バッチ内の最長のシーケンスの長さにパディングします(単一のシーケンスのみが提供された場合は、パディングを行いません)。
    • 'max_length': 引数 max_length で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
    • False または 'do_not_pad': パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
  • max_length (int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ(上記を参照)。
  • pad_to_multiple_of (int, 省略可能) — 設定すると、シーケンスを指定された値の倍数にパディングします。

    これは、計算能力が >= 7.0 (Volta) の NVIDIA ハードウェア上で Tensor Cores を使用できるようにするため、特に有用です。

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

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

DataCollatorForTokenClassification

class transformers.DataCollatorForTokenClassification

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

パラメータ

  • tokenizer(PreTrainedTokenizer または PreTrainedTokenizerFast)— データをエンコードするために使用されるトークナイザー。
  • padding (bool, str または PaddingStrategy, 省略可, デフォルトは True) — 返されるシーケンスのパディング戦略を選択します(モデルのパディング側とパディングインデックスに従います)。選択肢は以下の通りです: True または 'longest'(デフォルト):バッチ内の最も長いシーケンスまでパディングします(単一のシーケンスのみが提供された場合はパディングしません)。'max_length':引数 max_length で指定された最大長までパディングします。この引数が指定されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。False または 'do_not_pad':パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
    • True または 'longest'(デフォルト): バッチ内の最長のシーケンスの長さにパディングします(単一のシーケンスのみが提供された場合は、パディングを行いません)。
    • 'max_length': 引数 max_length で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
    • False または 'do_not_pad': パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
  • max_length (int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ(上記を参照)。
  • pad_to_multiple_of (int, 省略可能) — 設定すると、シーケンスを指定された値の倍数にパディングします。

    これは、計算能力が >= 7.0 (Volta) の NVIDIA ハードウェア上で Tensor Cores を使用できるようにするため、特に有用です。

  • label_pad_token_id (int、任意、デフォルトは -100) — ラベルのパディングに使用する ID です(-100 は PyTorch の損失関数によって自動的に無視されます)。
  • return_tensors (str、任意、デフォルトは"pt") — 返す Tensor の型です。許可される値は “np” または “pt” です。

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

DataCollatorForSeq2Seq

クラス transformers.DataCollatorForSeq2Seq

< >

( tokenizer: PreTrainedTokenizerBasemodel: typing.Any | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

パラメータ

  • tokenizer(PreTrainedTokenizer または PreTrainedTokenizerFast)— データをエンコードするために使用されるトークナイザー。
  • model (PreTrainedModel, 任意) — 学習対象のモデルです。設定されており、 prepare_decoder_input_ids_from_labels, メソッドを持つ場合は、それを使用して decoder_input_ids

    label_smoothing を使用する場合、損失を2回計算することを避けるために有用です。

  • padding (bool, str または PaddingStrategy, 省略可, デフォルトは True) — 返されるシーケンスのパディング戦略を選択します(モデルのパディング側とパディングインデックスに従います)。選択肢は以下の通りです: True または 'longest'(デフォルト):バッチ内の最も長いシーケンスまでパディングします(単一のシーケンスのみが提供された場合はパディングしません)。'max_length':引数 max_length で指定された最大長までパディングします。この引数が指定されていない場合は、モデルが受け入れ可能な最大入力長までパディングします。False または 'do_not_pad':パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
    • True または 'longest'(デフォルト): バッチ内の最長のシーケンスの長さにパディングします(単一のシーケンスのみが提供された場合は、パディングを行いません)。
    • 'max_length': 引数 max_length で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
    • False または 'do_not_pad': パディングなし(つまり、長さが異なるシーケンスのバッチを出力できます)。
  • max_length (int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ(上記を参照)。
  • pad_to_multiple_of (int, 省略可能) — 設定すると、シーケンスを指定された値の倍数にパディングします。

    これは、計算能力が >= 7.0 (Volta) の NVIDIA ハードウェア上で Tensor Cores を使用できるようにするため、特に有用です。

  • label_pad_token_id (int、任意、デフォルトは -100) — ラベルのパディングに使用する ID です(-100 は PyTorch の損失関数によって自動的に無視されます)。
  • return_tensors (str、任意、デフォルトは"pt") — 返す Tensor の型です。許可される値は “np” または “pt” です。

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

DataCollatorForLanguageModeling

class transformers.DataCollatorForLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBasemlm: bool = Truewhole_word_mask: bool = Falsemlm_probability: float | None = 0.15mask_replace_prob: float = 0.8random_replace_prob: float = 0.1pad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt'seed: int | None = None )

パラメータ

  • tokenizer(PreTrainedTokenizer または PreTrainedTokenizerFast)— データをエンコードするために使用されるトークナイザー。
  • 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, 省略可) — 設定した場合、シーケンスを指定された値の倍数にパディングします。
  • return_tensors (str) — 返す Tensor の型です。許可される値は “np” または “pt” です。
  • seed (int, 任意) — マスキング用の乱数生成器に使用するシードです。指定しない場合、グローバルRNGが使用されます。

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

最適なパフォーマンスを得るには、このデータコラテーターは、PreTrainedTokenizer または PreTrainedTokenizerFast が return_special_tokens_mask=True 引数で返すように、"special_tokens_mask" キーを持つ辞書または BatchEncoding のアイテムを含むデータセットと併用する必要があります。

<Example Options and Expectations>
  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%は変更されません。

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

numpy_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

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

torch_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

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

DataCollatorForPermutationLanguageModeling

class transformers.DataCollatorForPermutationLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBaseplm_probability: float = 0.16666666666666666max_span_length: int = 5return_tensors: str = 'pt' )

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

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

numpy_mask_tokens

< >

( inputs: Any )

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

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

torch_mask_tokens

< >

( inputs: Any )

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

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

DataCollatorWithFlattening

class transformers.DataCollatorWithFlattening

< >

( *argsreturn_position_ids = Trueseparator_id = -100return_flash_attn_kwargs = Falsereturn_seq_idx = Falseposition_ids_start = 0**kwargs )

パラメータ

  • return_position_ids (bool、省略可能、デフォルトは True) — position_ids を返すかどうか。フラット化された各シーケンスについて、position_ids_start から再開します。
  • 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、任意、デフォルトは 0) — 各シーケンスの最初のトークンに割り当てられる位置 ID です。

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

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

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

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

DataCollatorForMultipleChoice

class transformers.DataCollatorForMultipleChoice

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

パラメータ

  • tokenizer(PreTrainedTokenizer または PreTrainedTokenizerFast)— データをエンコードするために使用されるトークナイザー。
  • padding (bool, str または PaddingStrategy, 省略可, デフォルトは True) — モデルの padding 側と padding インデックスに基づいて、返されるシーケンスをパディングする戦略を選択します。選択肢は以下の通りです:
    • True または 'longest': バッチ内の最長のシーケンスの長さにパディングします(単一のシーケンスのみが提供された場合は、パディングを行いません)。
    • 'max_length': 引数 max_length で指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。
    • False または 'do_not_pad'(デフォルト):パディングを行いません(つまり、長さが異なるシーケンスのバッチを出力できます)。
  • max_length (int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ(上記を参照)。
  • pad_to_multiple_of (int, 省略可能) — シーケンスを指定された値の倍数にパディングします。

    これは、計算能力が >= 7.5 (Volta) の NVIDIA ハードウェア上で Tensor Cores を使用できるようにするため、特に有用です。

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

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

Update on GitHub