Transformers documentation
データコラテーター
データコラテーター
Data collatorは、データセット要素のリストを入力としてバッチを形成するオブジェクトです。これらの要素は、train_datasetまたはeval_datasetの要素と同じ型です。
バッチを構築するために、データコラテーターはパディングなどの処理を適用する場合があります。一部のデータコラテーター(DataCollatorForLanguageModeling など)は、形成されたバッチに対してランダムなデータ拡張(ランダムマスキングなど)も適用します。
使用例はサンプルノートブックで確認できます。
デフォルトのデータコラテーター
非常にシンプルなデータコラレーターです。dict 形式のオブジェクトのバッチを単にコラートし、以下の可能性のあるキー名に対して特別な処理を行います:
label: 1つのオブジェクトにつき1つの値(intまたはfloat)を処理しますlabel_ids: オブジェクトごとの値のリストを処理します
追加の前処理は行いません。入力オブジェクトのプロパティ名が、モデルへの対応する入力として使用されます。その有用性については、glueやnerを例として参照してください。
DefaultDataCollator
class transformers.DefaultDataCollator
< source >( return_tensors: str = 'pt' )
非常にシンプルなデータコラレーターです。dict 形式のオブジェクトのバッチを単にコラートし、以下の可能性のあるキー名に対して特別な処理を行います:
label: 1つのオブジェクトにつき1つの値(intまたはfloat)を処理しますlabel_ids: オブジェクトごとの値のリストを処理します
追加の前処理は行いません。入力オブジェクトのプロパティ名が、モデルへの対応する入力として使用されます。その有用性については、glueやnerを例として参照してください。
これは純粋な関数であるdefault_data_collatorとは異なり、他のデータコラクターと同様にオブジェクトです。初期化時にreturn_tensorsの値を設定する必要がある場合に、この点が役立ちます。
DataCollatorWithPadding
class transformers.DataCollatorWithPadding
< source >( 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
< source >( 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
< source >( 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
< source >( 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 が
<Example Options and Expectations>return_special_tokens_mask=True引数で返すように、"special_tokens_mask"キーを持つ辞書または BatchEncoding のアイテムを含むデータセットと併用する必要があります。
デフォルトの動作:
mask_replace_prob=0.8,random_replace_prob=0.1.- マスクされたトークンの80%は
[MASK]に置き換えられ、10%はランダムなトークンに置き換えられ、10%は変更されないことを想定してください。
[MASK]に置き換えられたすべてのマスク済みトークン:
mask_replace_prob=1.0,random_replace_prob=0.0.- すべてのマスクされたトークンは
[MASK]に置き換えられることを期待します。変更されないトークンや、ランダムなトークンに置き換えられるトークンは存在しません。
[MASK]の置換は行わず、ランダムなトークンのみを使用します:
mask_replace_prob=0.0,random_replace_prob=1.0.- すべてのマスクされたトークンがランダムなトークンに置き換えられることを期待します。
[MASK]への置き換えや、変更されないトークンは存在しません。バランスの取れた置換:
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
< source >( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )
マスク言語モデリング用のマスク済みトークン入力/ラベルを準備します。
torch_mask_tokens
< source >( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )
マスク言語モデリング用のマスク済みトークン入力/ラベルを準備します。
DataCollatorForPermutationLanguageModeling
class transformers.DataCollatorForPermutationLanguageModeling
< source >( tokenizer: PreTrainedTokenizerBaseplm_probability: float = 0.16666666666666666max_span_length: int = 5return_tensors: str = 'pt' )
置換言語モデリングに使用されるデータコラテーター。
- collates は、テンソルのバッチをまとめ、そのトークナイザーの pad_token を尊重します。
- XLNet固有の手順を用いて、置換言語モデリング用のバッチを前処理します
特定のシーケンスにおいて予測対象となるマスク済みトークンは、以下のアルゴリズムによって決定されます。
cur_len = 0(これまでに処理されたトークンの数)を設定して、シーケンスの先頭から開始します。[1, max_span_length]の区間からspan_lengthをサンプリングします(マスク対象のトークンスパンの長さ)- マスク対象のスパンを囲むために、
context_length = span_length / plm_probabilityの長さのコンテキストを確保します - 区間
[cur_len, cur_len + context_length - span_length]から開始位置start_indexをサンプリングし、トークンstart_index:start_index + span_lengthをマスクします。 cur_len = cur_len + context_lengthを設定します。cur_len < max_lenの場合(つまり、処理対象のシーケンスに未処理のトークンが残っている場合)、Step 1 から繰り返します。
特定のシーケンスにおいて予測対象となるマスク済みトークンは、以下のアルゴリズムによって決定されます。
cur_len = 0(これまでに処理されたトークンの数)を設定して、シーケンスの先頭から開始します。[1, max_span_length]の区間からspan_lengthをサンプリングします(マスク対象のトークンスパンの長さ)- マスク対象のスパンを囲むために、
context_length = span_length / plm_probabilityの長さのコンテキストを確保します - 区間
[cur_len, cur_len + context_length - span_length]から開始位置start_indexをサンプリングし、トークンstart_index:start_index + span_lengthをマスクします。 cur_len = cur_len + context_lengthを設定します。cur_len < max_lenの場合(つまり、処理対象のシーケンスに未処理のトークンが残っている場合)、Step 1 から繰り返します。
DataCollatorWithFlattening
class transformers.DataCollatorWithFlattening
< source >( *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
< source >( 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” です。
動的にパディングを行うデータコラテーターです。複数選択問題のネストされた例のバッチに対して、すべての例のすべての選択肢が同じ長さになるようにパディングを適用します。