Transformers 4.37 中文文档（十四）（2）https://developer.aliyun.com/article/1564956
数据收集器
原文：
huggingface.co/docs/transformers/v4.37.2/en/main_classes/data_collator
数据收集器是通过使用数据集元素列表作为输入来形成批次的对象。这些元素与 train_dataset 或 eval_dataset 的元素类型相同。
为了能够构建批次，数据收集器可能会应用一些处理（如填充）。其中一些（如 DataCollatorForLanguageModeling）还会对形成的批次应用一些随机数据增强（如随机掩码）。
使用示例可在示例脚本或示例笔记本中找到。
默认数据收集器
transformers.default_data_collator
( features: List return_tensors = 'pt' )
非常简单的数据收集器，只是将类似字典的对象的批次汇集在一起，并对名为潜在键执行特殊处理：
label: 处理每个对象的单个值（int 或 float）label_ids: 处理每个对象的值列表
不执行任何额外的预处理：输入对象的属性名称将用作模型的相应输入。查看 glue 和 ner 的示例，了解它的用途。
DefaultDataCollator
class transformers.DefaultDataCollator
( return_tensors: str = 'pt' )
参数
return_tensors（str，可选，默认为"pt"）— 要返回的张量类型。允许的值为 “np”、"pt"和 “tf”。
非常简单的数据收集器，只是将类似字典的对象的批次汇集在一起，并对名为潜在键执行特殊处理：
label: 处理每个对象的单个值（int 或 float）label_ids: 处理每个对象的值列表
不执行任何额外的预处理：输入对象的属性名称将用作模型的相应输入。查看 glue 和 ner 的示例，了解它的用途。
这是一个对象（像其他数据收集器一样），而不是像 default_data_collator 那样的纯函数。如果需要在初始化时设置 return_tensors 值，这可能会有所帮助。
DataCollatorWithPadding
class transformers.DataCollatorWithPadding
( tokenizer: PreTrainedTokenizerBase padding: Union = True max_length: Optional = None pad_to_multiple_of: Optional = None return_tensors: str = 'pt' )
参数
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，可选）— 如果设置，将序列填充到提供的值的倍数。
这对于启用具有计算能力 >= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 的使用特别有用。return_tensors（str，可选，默认为"pt"）— 要返回的张量类型。允许的值为 “np”、"pt"和 “tf”。
数据收集器，将动态填充接收到的输入。
DataCollatorForTokenClassification
class transformers.DataCollatorForTokenClassification
( tokenizer: PreTrainedTokenizerBase padding: Union = True max_length: Optional = None pad_to_multiple_of: Optional = None label_pad_token_id: int = -100 return_tensors: str = 'pt' )
参数
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，可选）— 如果设置，将序列填充到提供的值的倍数。
这对于启用具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 特别有用。label_pad_token_id（int，可选，默认为-100）— 填充标签时要使用的 id（-100 将被 PyTorch 损失函数自动忽略）。return_tensors（str，可选，默认为"pt"）— 要返回的 Tensor 类型。允许的值为“np”，"pt"和“tf”。
数据收集器，将动态填充接收到的输入以及标签。
DataCollatorForSeq2Seq
class transformers.DataCollatorForSeq2Seq
( tokenizer: PreTrainedTokenizerBase model: Optional = None padding: Union = True max_length: Optional = None pad_to_multiple_of: Optional = None label_pad_token_id: int = -100 return_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'：无填充（即，可以输出具有不同长度序列的批次）。
max_length（int，可选）— 返回列表的最大长度和可选填充长度（见上文）。pad_to_multiple_of（int，可选）— 如果设置，将序列填充到提供的值的倍数。
这对于启用具有计算能力>= 7.5（Volta）的 NVIDIA 硬件上的 Tensor Cores 特别有用。label_pad_token_id（int，可选，默认为-100）— 填充标签时要使用的 id（-100 将被 PyTorch 损失函数自动忽略）。return_tensors(str, optional, 默认为"pt") — 要返回的张量类型。允许的值为“np”，"pt"和“tf”。
数据收集器将动态填充接收到的输入和标签。
DataCollatorForLanguageModeling
class transformers.DataCollatorForLanguageModeling
( tokenizer: PreTrainedTokenizerBase mlm: bool = True mlm_probability: float = 0.15 pad_to_multiple_of: Optional = None tf_experimental_compile: bool = False return_tensors: str = 'pt' )
参数
tokenizer（PreTrainedTokenizer 或 PreTrainedTokenizerFast） — 用于对数据进行编码的分词器。mlm(bool, optional, 默认为True) — 是否使用遮罩语言建模。如果设置为False，则标签与输入相同，忽略填充标记（通过将它们设置为-100）。否则，对于未遮罩的标记，标签为-100，对于遮罩的标记，值为要预测的值。mlm_probability(float, optional, 默认为 0.15) — 当mlm设置为True时，在输入中（随机）遮罩标记的概率。pad_to_multiple_of(int, optional) — 如果设置，将序列填充到提供的值的倍数。return_tensors(str) — 要返回的张量类型。允许的值为“np”，“pt”和“tf”。
用于语言建模的数据收集器。如果它们的长度不相同，则输入将动态填充到批次的最大长度。
为了获得最佳性能，应该将此数据收集器与具有字典或 BatchEncoding 项目的数据集一起使用，其中包含"special_tokens_mask"键，如由 PreTrainedTokenizer 或 PreTrainedTokenizerFast 返回的，参数return_special_tokens_mask=True。
numpy_mask_tokens
( inputs: Any special_tokens_mask: Optional = None )
为遮罩语言建模准备遮罩标记输入/标签：80% MASK，10% 随机，10% 原始。
tf_mask_tokens
( inputs: Any vocab_size mask_token_id special_tokens_mask: Optional = None )
为遮罩语言建模准备遮罩标记输入/标签：80% MASK，10% 随机，10% 原始。
torch_mask_tokens
( inputs: Any special_tokens_mask: Optional = None )
为遮罩语言建模准备遮罩标记输入/标签：80% MASK，10% 随机，10% 原始。
DataCollatorForWholeWordMask
class transformers.DataCollatorForWholeWordMask
( tokenizer: PreTrainedTokenizerBase mlm: bool = True mlm_probability: float = 0.15 pad_to_multiple_of: Optional = None tf_experimental_compile: bool = False return_tensors: str = 'pt' )
用于遮罩整个单词的语言建模数据收集器。
- 整理张量批次，尊重它们的分词器的 pad_token
- 为遮罩语言建模预处理批次
此数据收集器依赖于 BertTokenizer 对子词分词的实现细节，特别是子词标记以*##*为前缀。对于不遵循此方案的分词器，此数据收集器将产生一个大致等同于.DataCollatorForLanguageModeling的输出。
numpy_mask_tokens
( inputs: Any mask_labels: Any )
为遮罩语言建模准备遮罩标记输入/标签：80% MASK，10% 随机，10% 原始。设置’mask_labels’表示我们使用整词遮罩（wwm），我们根据其引用直接遮罩 idxs。
tf_mask_tokens
( inputs: Any mask_labels: Any )
为掩码语言建模准备掩码标记输入/标签：80%掩码，10%随机，10%原始。设置’mask_labels’表示我们使用整词掩码（wwm），我们根据其引用直接掩码 idxs。
torch_mask_tokens
( inputs: Any mask_labels: Any )
为掩码语言建模准备掩码标记输入/标签：80%掩码，10%随机，10%原始。设置’mask_labels’表示我们使用整词掩码（wwm），我们根据其引用直接掩码 idxs。
DataCollatorForPermutationLanguageModeling
class transformers.DataCollatorForPermutationLanguageModeling
( tokenizer: PreTrainedTokenizerBase plm_probability: float = 0.16666666666666666 max_span_length: int = 5 return_tensors: str = 'pt' )
用于排列语言建模的数据收集器。
- 整理张量批次，尊重其分词器的 pad_token
- 使用特定于 XLNet 的程序对排列语言建模进行预处理
numpy_mask_tokens
( inputs: Any )
特定序列要预测的掩码标记由以下算法确定：
- 从序列开头开始，通过设置
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（即序列中仍有剩余标记要处理），则从步骤 1 重复。
tf_mask_tokens
( inputs: Any )
特定序列要预测的掩码标记由以下算法确定：
- 从序列开头开始，通过设置
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（即序列中仍有剩余标记要处理），则从步骤 1 重复。
torch_mask_tokens
( inputs: Any )
特定序列要预测的掩码标记由以下算法确定：
- 从序列开头开始，通过设置
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（即序列中仍有剩余标记要处理），则从步骤 1 重复。
Keras 回调
在使用 Keras 训练 Transformers 模型时，有一些特定于库的回调可用于自动化常见任务：
KerasMetricCallback
class transformers.KerasMetricCallback
( metric_fn: Callable eval_dataset: Union output_cols: Optional = None label_cols: Optional = None batch_size: Optional = None predict_with_generate: bool = False use_xla_generation: bool = False generate_kwargs: Optional = None )
参数
metric_fn（Callable）- 用户提供的度量函数。它将使用两个参数调用-predictions和labels。这些包含数据集中模型的输出和匹配标签。它应返回一个将度量名称映射到数值的字典。eval_dataset（tf.data.Dataset或dict或tuple或np.ndarray或tf.Tensor）- 用于生成metric_fn预测的验证数据。output_cols（List[str]，可选）- 从模型输出中保留的列的列表作为预测。默认为全部。label_cols（List[str]，可选）- 从输入数据集中保留的列的列表作为标签。如果未提供，则将自动检测。batch_size（int，可选）- 批量大小。仅在数据不是预先批处理的tf.data.Dataset时使用。predict_with_generate（bool，可选，默认为False）- 是否应使用model.generate()来获取模型的输出。use_xla_generation（bool，可选，默认为False）- 如果我们正在生成，是否使用 XLA 编译模型生成。这可以大大提高生成速度（最多提高 100 倍），但将需要为每个输入形状进行新的 XLA 编译。在使用 XLA 生成时，最好将输入填充到相同大小，或者在您的tokenizer或DataCollator中使用pad_to_multiple_of参数，这将减少唯一输入形状的数量并节省大量编译时间。如果predict_with_generate为False，则此选项不起作用。generate_kwargs（dict，可选）- 生成时传递给model.generate()的关键字参数。如果predict_with_generate为False，则不起作用。
在每个时代结束时计算指标的回调。与普通的 Keras 指标不同，这些指标不需要由 TF 编译。对于像 BLEU 和 ROUGE 这样需要字符串操作或无法编译的生成循环的常见 NLP 指标，这是特别有用的。在将预测（或生成）传递给metric_fn之前，将在eval_dataset上计算预测（或生成）并以np.ndarray格式传递给metric_fn。metric_fn应计算指标并返回将度量名称映射到度量值的字典。
我们在下面提供了一个适合的 metric_fn 示例，用于计算摘要模型的 ROUGE 分数。请注意，为了可读性和简单起见，此示例跳过了一些后处理步骤，可能不应直接使用！
from datasets import load_metric rouge_metric = load_metric("rouge") def rouge_fn(predictions, labels): decoded_predictions = tokenizer.batch_decode(predictions, skip_special_tokens=True) decoded_labels = tokenizer.batch_decode(labels, skip_special_tokens=True) result = rouge_metric.compute(predictions=decoded_predictions, references=decoded_labels) return {key: value.mid.fmeasure * 100 for key, value in result.items()}
上述函数将返回一个包含值的字典，这些值将像其他 Keras 指标一样被记录：
{'rouge1': 37.4199, 'rouge2': 13.9768, 'rougeL': 34.361, 'rougeLsum': 35.0781
PushToHubCallback
class transformers.PushToHubCallback
( output_dir: Union save_strategy: Union = 'epoch' save_steps: Optional = None tokenizer: Optional = None hub_model_id: Optional = None hub_token: Optional = None checkpoint: bool = False **model_card_args )
参数
output_dir（str）- 模型预测和检查点将被写入并与 Hub 上的存储库同步的输出目录。save_strategy（str或 IntervalStrategy，可选，默认为"epoch"）- 训练期间采用的检查点保存策略。可能的值为：
"no"：保存在训练结束时完成。"epoch"：在每个时代结束时完成保存。"steps"：每save_steps完成保存
save_steps（int，可选）- 使用“steps”save_strategy时保存之间的步数。tokenizer（PreTrainedTokenizerBase，可选）—模型使用的分词器。如果提供，将与权重一起上传到存储库。hub_model_id（str，可选）—要与本地output_dir同步的存储库的名称。它可以是一个简单的模型 ID，此时模型将被推送到您的命名空间。否则，它应该是整个存储库名称，例如"user_name/model"，这样您就可以推送到您所属的组织，例如"organization_name/model"。
将默认为output_dir的名称。hub_token（str，可选）—用于将模型推送到 Hub 的令牌。将默认为使用huggingface-cli login获取的缓存文件夹中的令牌。checkpoint（bool，可选，默认为False）—是否保存完整的训练检查点（包括 epoch 和优化器状态），以允许恢复训练。仅在save_strategy为"epoch"时可用。
回调函数将定期保存并推送模型到 Hub。默认情况下，它每个 epoch 推送一次，但可以使用save_strategy参数进行更改。推送的模型可以像 Hub 上的任何其他模型一样访问，例如使用from_pretrained方法。
from transformers.keras_callbacks import PushToHubCallback push_to_hub_callback = PushToHubCallback( output_dir="./model_save", tokenizer=tokenizer, hub_model_id="gpt5-7xlarge", ) model.fit(train_dataset, callbacks=[push_to_hub_callback])
Transformers 4.37 中文文档（十四）（4）https://developer.aliyun.com/article/1564958
