数据整理器

数据整理器（Data collators）是一种对象，它接收一个由数据集元素组成的列表作为输入，并据此构建一个批次（batch）。这些元素与 train_dataset 或 eval_dataset 中的元素类型相同。

为了能够构建批次，数据整理器可能会应用一些处理（例如填充）。其中一些（例如 DataCollatorForLanguageModeling）还会对已形成的批次应用一些随机数据增强（例如随机掩码）。

使用示例可在示例笔记本中找到。

默认数据整理器

transformers.default_data_collator

< source >

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

一个非常简单的数据整理器，它仅对字典样式的对象批次进行整理，并对以下潜在键名执行特殊处理：

label：每个对象处理单个值（int 或 float）
label_ids：处理每个对象的一组值

不会执行任何额外的预处理：输入对象的属性名将直接用作模型的对应输入。请参阅 glue 和 ner，了解其具体用途示例。

DefaultDataCollator

class transformers.DefaultDataCollator

< source >

( return_tensors: str = 'pt' )

参数

return_tensors (str，可选，默认为 "pt") — 要返回的 Tensor 类型。允许的值是 “np” 或 “pt”。

一个非常简单的数据整理器，它仅对字典样式的对象批次进行整理，并对以下潜在键名执行特殊处理：

label：每个对象处理单个值（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, 可选) — 如果设置，则将序列填充为所提供值的倍数。
这在启用 NVIDIA 硬件（计算能力 >= 7.0，即 Volta 架构）上的 Tensor Cores 使用时尤为有用。
return_tensors (str，可选，默认为 "pt") — 要返回的 Tensor 类型。允许的值是 “np” 或 “pt”。

用于动态填充所接收输入的数据整理器。

DataCollatorForTokenClassification

class transformers.DataCollatorForTokenClassification

< source >

参数

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, 可选) — 如果设置，则将序列填充为所提供值的倍数。
这在启用 NVIDIA 硬件（计算能力 >= 7.0，即 Volta 架构）上的 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 时，这有助于避免重复计算损失。
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, 可选) — 如果设置，则将序列填充为所提供值的倍数。
这在启用 NVIDIA 硬件（计算能力 >= 7.0，即 Volta 架构）上的 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) — 是否对整个单词进行掩码，而不是对单个 token 进行掩码。
mlm_probability (float，可选，默认值为 0.15) — 当 mlm 设置为 True 时，用于（随机）掩码输入中 token 的概率。
mask_replace_prob (float，可选，默认值为 0.8) — 被掩码的 token 被替换为分词器掩码 token（例如 [MASK]）的概率。默认值为 0.8，表示 80% 的被掩码 token 将被替换为 [MASK]。仅在 mlm 设置为 True 时生效。
random_replace_prob (float，可选，默认值为 0.1) — 被掩码的 token 被替换为分词器词表中随机 token 的概率。默认值为 0.1，表示 10% 的被掩码 token 将被替换为随机 token。其余被掩码的 token（1 - mask_replace_prob - random_replace_prob）保持不变。仅在 mlm 设置为 True 时生效。
pad_to_multiple_of (int, 可选) — 如果设置，则将序列填充为所提供值的倍数。
return_tensors (str) — 要返回的 Tensor 类型。允许的值是 “np” 或 “pt”。
seed (int, 可选) — 用于掩码随机数生成器的种子。如果未提供，将使用全局随机数生成器。

用于语言建模的数据整理器。如果输入的长度不完全相同，则动态填充到批次中的最大长度。

为了获得最佳性能，此数据整理器应与包含字典或 BatchEncoding 类型项的数据集配合使用，这些项需包含 "special_tokens_mask" 键，即由 PreTrainedTokenizer 或 PreTrainedTokenizerFast 在参数 return_special_tokens_mask=True 下返回的结果。
<Example Options and Expectations>
默认行为：

mask_replace_prob=0.8, random_replace_prob=0.1.

预计 80% 的掩码 token 会被替换为 [MASK]，10% 会被替换为随机 token，10% 保持不变。

所有被 [MASK] 替换的掩码标记：

mask_replace_prob=1.0, random_replace_prob=0.0.

预期所有被掩码的 token 都会被替换为 [MASK]。不会有任何 token 保持不变或被替换为随机 token。

没有 [MASK] 替换，只有随机 token：

mask_replace_prob=0.0, random_replace_prob=1.0.

预期所有被掩码的 token 都会被替换为随机 token。不会出现 [MASK] 替换或保持不变的 token。

平衡替换：

mask_replace_prob=0.5, random_replace_prob=0.4.

预计 50% 的掩码 token 会被替换为 [MASK]，40% 会被替换为随机 token，10% 保持不变。

注意： mask_replace_prob 与 random_replace_prob 之和不得超过 1。如果它们的和小于 1，则剩余比例将由保持不变的掩码 token 组成。

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

类 transformers.DataCollatorForPermutationLanguageModeling

< source >

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

用于排列语言建模的数据整理器。

将张量批次进行整理，并遵循其分词器的 pad_token
使用 XLNet 特有的流程为排列语言建模预处理批次

numpy_mask_tokens

< source >

( inputs: Any )

用于预测特定序列中掩码标记的算法如下：

从序列的开头开始，设置 cur_len = 0（到目前为止已处理的 token 数量）。
从区间 [1, max_span_length] 中采样一个 span_length（即要掩码的 token 跨度长度）
保留一个长度为 context_length = span_length / plm_probability 的上下文，用于包围将被掩码的 span
从区间 [cur_len, cur_len + context_length - span_length] 中采样一个起始位置 start_index，并屏蔽 start_index:start_index + span_length 处的 token
设置 cur_len = cur_len + context_length。如果 cur_len < max_len（即序列中仍有待处理的 token），则从步骤 1 开始重复。

torch_mask_tokens

< source >

( inputs: Any )

用于预测特定序列中掩码标记的算法如下：

从序列的开头开始，设置 cur_len = 0（到目前为止已处理的 token 数量）。
从区间 [1, max_span_length] 中采样一个 span_length（即要掩码的 token 跨度长度）
保留一个长度为 context_length = span_length / plm_probability 的上下文，用于包围将被掩码的 span
从区间 [cur_len, cur_len + context_length - span_length] 中采样一个起始位置 start_index，并屏蔽 start_index:start_index + span_length 处的 token
设置 cur_len = cur_len + context_length。如果 cur_len < max_len（即序列中仍有待处理的 token），则从步骤 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，该值指示每个 token 所属的序列。
position_ids_start (int，可选，默认为 0) — 分配给每个序列中第一个 token 的位置 ID。

用于无填充（padding free）方法的数据整理器（Data collator）。执行以下操作：

将整个 mini batch 拼接为形状为 [1, total_tokens] 的单一长序列
使用 separator_id 来分隔拼接后的 labels 中的序列，默认值为 -100
不会添加填充，默认返回 input_ids、labels 和 position_ids
可选地返回 FlashAttentionKwargs 中包含的 kwargs
可选地返回 seq_idx，指示每个 token 属于哪个序列

使用 DataCollatorWithFlattening 会将整个 mini batch 展平为单个长序列。请确保你的注意力计算能够处理这种情况！

并非所有模型在自行计算位置 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（PreTrainedTokenizer 或 PreTrainedTokenizerFast）—— 用于对数据进行编码的分词器。
padding (bool, str 或 PaddingStrategy, 可选, 默认为 True) — 根据模型的填充侧和填充索引，选择用于填充返回序列的策略，可选值如下：
- True 或 'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。
- 'max_length'：填充至由参数 max_length 指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。
- False 或 'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
max_length (int，可选) — 返回列表的最大长度，以及可选的填充长度（见上文）。
pad_to_multiple_of (int, 可选) — 将序列填充为指定值的倍数。这在启用 NVIDIA 硬件（计算能力 >= 7.5，即 Volta 架构）上的 Tensor Cores 时特别有用。
这在启用 NVIDIA 硬件（计算能力 >= 7.5，即 Volta 架构）上的 Tensor Cores 使用时尤为有用。
return_tensors (str，可选，默认为 "pt") — 要返回的 Tensor 类型。允许的值是 “np” 或 “pt”。

用于动态填充嵌套示例批次的数据整理器，适用于多项选择题，以确保所有示例的所有选项长度相同。

Update on GitHub

Transformers

数据整理器

默认数据整理器

transformers.default_data_collator

DefaultDataCollator

class transformers.DefaultDataCollator

DataCollatorWithPadding

class transformers.DataCollatorWithPadding

DataCollatorForTokenClassification

class transformers.DataCollatorForTokenClassification

DataCollatorForSeq2Seq

类 transformers.DataCollatorForSeq2Seq

DataCollatorForLanguageModeling

class transformers.DataCollatorForLanguageModeling

numpy_mask_tokens

torch_mask_tokens

DataCollatorForPermutationLanguageModeling

类 transformers.DataCollatorForPermutationLanguageModeling

numpy_mask_tokens

torch_mask_tokens

DataCollatorWithFlattening

class transformers.DataCollatorWithFlattening

DataCollatorForMultipleChoice

class transformers.DataCollatorForMultipleChoice