一、Configuration

  1. PretrainedConfig 基类实现了一些通用方法，如从本地或者远程加载/保存一个 configuration 。每个派生的 config class 实现了模型的特定属性。所有 config class 的常见属性是：hidden_size、num_attention_heads、num_hidden_layers 。文本模型进一步实现了 vocab_size 属性。

  2. 配置文件可以加载到内存、以及保存到文件。注意，使用配置文件来初始化一个模型并不会加载模型的权重，它仅仅影响模型的配置。

  3. 安装 Transformer：

    检验是否安装成功：

1.1 API

  1. class transformers.PretrainedConfig：PretrainedConfig 基类。

    参数：

    • name_or_path：一个字符串，默认为空字符串，作为 pretrained_model_name_or_path 传递给 PreTrainedModel.from_pretrained()/TFPreTrainedModel.from_pretrained() 。

    • output_hidden_states：一个布尔值，默认为 False，指定模型是否应该返回所有的 hidden state 。

    • output_attentions：一个布尔值，默认为 False，指定模型是否应该返回所有的注意力。

    • return_dict：一个布尔值，默认为 True，指定模型是否应该返回一个 ModelOutput 而不是一个普通的元组。

    • is_encoder_decoder：一个布尔值，默认为 False，指定模型是否作为一个 encoder/decoder 使用。

    • is_decoder：一个布尔值，默认为 False，模型是否被用作解码器。如果为 False，则模型被用作编码器。

    • cross_attention_hidden_size：一个整数，指定 cross-attention layer 的隐层维度。当该模型被用作 encoder-decoder setting 中的解码器时，并且当 cross-attention 隐层维度与 self.config.hidden_size 维度不同时使用。

    • add_cross_attention：一个布尔值，默认为 False，指定是否应该将 cross-attention layer 添加到模型中。

      注意，这个选项只与可以作为 EncoderDecoderModel 类的解码器的模型有关，其中 EncoderDecoderModel 类包括AUTO_MODELS_FOR_CAUSAL_LM 中的所有模型。

    • tie_encoder_decoder：一个布尔值，默认为 False，指定是否所有编码器权重应与它们的等价的解码器权重绑定（即，权重共享）。

      注意，这要求编码器和解码器的参数名称完全相同。

    • prune_heads：一个字典，键为层的编号，值为 head 的编号组成的列表，默认为空字典。该参数指定模型每一层的被裁剪的 head 。

      例如：{1: [0, 2], 2: [2, 3]} 表示 layer 1 裁剪 heads 0, 2， layer 2 裁剪 heads 2, 3 。

    • chunk_size_feed_forward：一个整数，默认为零，指定 residual attention block 中所有 feed forward layer 的 chunk size 。

      chunk size = 0 意味着 feed forward layer 不被分块；chunk size = n 意味着 feed forward layer 每次处理 n 个 embedding ，其中 n < sequence_length ，这是在 Reformer 论文中提出的方法。

    针对序列生成任务的参数：

    • max_length：一个整数，默认为 20，指定模型的生成方法中，默认使用的最大长度。

    • min_length：一个整数，默认为 10，指定模型的生成方法中，默认使用的最小长度。

    • do_sample：一个布尔值，默认为 False，指定模型的生成方法中，是否使用采样。如果为 False 则使用贪心解码 greedy decoding 。

    • early_stopping：一个布尔值，默认为 False，指定模型的生成方法中，是否当至少 num_beams 句子已经生成的时候提前结束 beam search 。

    • num_beams：一个整数，默认为 1，指定模型的生成方法中，beam search 默认使用的 beam 数量（即，beam size ）。 1 意味着没有 beam search 。

    • num_beam_groups：一个整数，默认为 1，指定模型的生成方法中，将 num_beams 分成的组数，以确保在模型的生成方法中不同 beam group 的多样性。 1 意味着没有 group beam search 。

    • diversity_penalty：一个浮点数，默认为 0.0 ，指定模型的生成方法中，控制 group beam search 的多样性。0 意味着没有多样性惩罚。惩罚越大，输出的多样性越强。

    • temperature：一个浮点数，默认为 1.0，指定模型的生成方法中，用于建模 next token 概率（即 softmax 函数的温度）。必须是严格为正的数。

    • top_k：一个整数，默认为 50，指定模型的生成方法中，用于 top-k-filtering 的、保留最高概率的多少个 vocabulary token 。

    • top_p：一个浮点数，默认为 1.0，指定模型的生成方法中，top_p 的值。如果 top_p < 1.0，那么保留概率加起来大于等于 top_p 的、top 概率的 token 。

    • repetition_penalty：一个浮点数，默认为 1.0，指定模型的生成方法中，repetition penalty 的超参数。1.0 意味着没有惩罚。

    • length_penalty：一个浮点数，默认为 1.0，指定模型的生成方法中，beam-based 方法中针对长度的指数惩罚。它以指数的形式作用在序列长度上，然后把序列的得分除以这个指数结果。

      由于序列的得分是对数似然（是个负数），因此 length_penalty > 0.0 会鼓励更长的序列，而 length_penalty < 0.0 会鼓励更短的序列。

    • no_repeat_ngram_size：一个整数，默认为 0，指定模型的生成方法中，no_repeat_ngram_size 的值。如果是大于零的整数，则所有该 size 的 ngram 只能出现一次。

    • encoder_no_repeat_ngram_size：一个整数，默认为 0，指定模型的生成方法中，encoder_no_repeat_ngram_size 的值。如果是大于零的整数，则出现在 encoder_input_ids 中的所有该 size 的 ngram ，都不能出现在 decoder_input_ids 中。

    • bad_words_ids：一个整数列表，指定模型的生成方法中，哪些 token id 禁止被生成。

      为了获得不应该出现在生成文本中的单词的 token id，使用 tokenizer.encode(bad_word, add_prefix_space=True) 。

    • num_return_sequences：一个整数，默认为 1，指定模型的生成方法中，batch 中每个样本需要独立返回的序列数量。

    • output_scores：一个布尔值，默认为 False，指定模型的生成方法中，是否需要返回 logits 。

    • return_dict_in_generate：一个布尔值，默认为 False，指定模型的生成方法中，是否应该返回 ModelOutput 而不是 torch.LongTensor 。

    • forced_bos_token_id：一个整数，指定模型的生成方法中，在解码器的 decoder_start_token_id 之后强制作为第一个被生成的 token 的 token id 。

      这对于像 mBART 这样的多语言模型非常有用，在这种情况下，第一个被生成的token 需要是 target language token 。

    • forced_eos_token_id：一个整数，指定模型的生成方法中，当生成的序列达到 max_length 时，强制作为最后一个被生成的 token 的 token id 。

    • remove_invalid_values：一个布尔值，指定模型的生成方法中，是否删除模型中可能的 nan 和 inf 输出以防止生成方法崩溃。

      注意，使用 remove_invalid_values 会减慢生成速度。

    针对微调任务的参数：

    • architectures：一个字符串列表，指定微调任务中，可以与模型预训练权重一起使用的模型架构。
    • finetuning_task：一个字符串，指定微调任务中，微调任务的名称。当从原始的 checkpoint 转换时，可以用这个参数。
    • id2label：一个整数到字符串的字典，指定微调任务中，index 到 label 名字的映射。
    • label2id ：一个字符串到整数的字典，指定微调任务中，label 名字到 index 的映射。
    • num_labels：一个整数，指定微调任务中，使用的 label 的数量，通常用于分类任务。
    • task_specific_params：一个 Dict[str, Any] 字典 ，指定微调任务中，存储的额外关键字参数。
    • problem_type：一个字符串，指定微调任务中，针对 XxxForSequenceClassification 模型的问题类型，可以为 "regression"、"single_label_classification"、"multi_label_classification" 。

    和 tokenizer 关联的参数：

    • tokenizer_class：一个字符串，指定要使用的 tokenizer class 的名字。如果未设置，则默认使用模型相关的 tokenizer。
    • prefix：一个字符串，指定在调用模型之前，应该在每个文本的开头添加的一个特定的 prompt 。
    • bos_token_id：一个整数，指定 beginning-of-stream token 的 ID 。
    • pad_token_id：一个整数，指定 padding token 的 ID 。
    • eos_token_id：一个整数，指定 end-of-stream token 的 ID 。
    • decoder_start_token_id：一个整数，指定如果一个 encoder-decoder 模型以不同于 bos 的 token 开始解码，则指定该 token 的 id 。
    • sep_token_id：一个整数，指定 separation token 的 ID 。

    PyTorch 特定的参数：

    • torchscript：一个布尔值，默认为 False，指定该模型是否应与Torchscript 一起使用。

    • tie_word_embeddings：一个布尔值，默认为 True，指定模型的 input word embedding 和 output word embedding 是否应该绑定（即，权重共享）。请注意，仅当模型有一个 output word embedding layer 时，该参数才生效。

    • torch_dtype：一个字符串，指定权重的 dtype 。这个属性可以用来将模型初始化为一个非默认的 dtype （模型权重通常是float32），从而允许优化存储。 例如，如果保存的模型是 float16 ，理想情况下，我们希望将模型权重初始化为 float16 而不是 float32 。

      由于config 对象是以纯文本形式存储的，这个属性只包含浮点类型的字符串，没有 torch. 前缀。例如，对于 torch.float16 的 torch_dtype 是 "float16" 字符串。

      注意，这个属性目前在模型加载时没有被使用（而是在将模型初始化时使用）。

    TensorFlow 特定的参数：

    • use_bfloat16：一个布尔值，默认为 False，指定模型是否应该使用 BFloat16 （仅用于部分 TF 模型）。
    • tf_legacy_loss：一个布尔值，默认为 False，指定模型是否应该使用 legacy TensorFlow loss 。legacy loss 具有可变的 output shape，并且可能与 XLA 不兼容。该参数将在 Transformer 后续版本中移除。

  2. PretrainedConfig 的 class 属性（由派生类所覆盖）：

    • model_type：一个字符串，用于模型类型的一个 identifier。它被序列化到 JSON 文件中，并用于在 AutoConfig 中重新创建正确的对象。
    • is_composition：一个布尔值，指定该 config class 是否由多个 sub-config 组成。在这种情况下，该 config 必须从两个或更多的 PretrainedConfig 类型的配置中初始化。
    • keys_to_ignore_at_inference：一个字符串列表，在推断过程中查看模型的 dictionary output 时，默认要忽略的键的列表。
    • attribute_map：一个字符串到字符串的字典，将模型的 specific attribute name 映射到标准化的属性名。

  3. PretrainedConfig 的通用属性（在所有子类中都存在）：

    • vocab_size：一个整数，指定词表的大小，它也是 embedding 矩阵的第一个维度。对于像 ViT 这样没有文本模态的模型，这个属性可能会丢失。
    • hidden_size：一个整数，指定模型的隐层维度。
    • num_attention_heads：一个整数，指定模型的注意力头的数量。
    • num_hidden_layers：一个整数，指定模型中 block 的数量。

  4. 方法：

    • push_to_hub()：将配置文件上传到 Model Hub ，同时同步位于 repo_path_or_name 中的 repo 的 local clone 。

      参数：参考 PreTrainedTokenizerBase.push_to_hub() 方法。

    • dict_torch_dtype_to_str(d: Dict[str, Any]) -> None：检查字典 d 及其嵌套的字典是否有 torch_dtype 键，如果有，就把 torch.dtype 转换为一个对应的字符串。如 torch.float32 转换为 "float32" 。

    • from_dict(config_dict: Dict[str, Any], **kwargs) -> PretrainedConfig：从字典中创建一个 PretrainedConfig 。

    • from_json_file(json_file: Union[str, os.PathLike]) -> PretrainedConfig：从 json 文件中创建一个 PretrainedConfig 。

    • from_pretrained(pretrained_model_name_or_path: Union[str, os.PathLike], **kwargs) -> PretrainedConfig：从 pretrained model configuration 中建一个 PretrainedConfig 。

      参数：参考 PreTrainedTokenizerBase.from_pretrained() 方法。

    • get_config_dict(pretrained_model_name_or_path: Union[str, os.PathLike], **kwargs) -> Tuple[Dict[str, Any], Dict[str, Any]]：从一个配置对象中返回字典，这个字典可用于 from_dict() 。

      参数：参考 from_pretrained() 。

      返回值：一个元组，每个元素都是一个字典，其中第二个字典通常是空字典。

    • register_for_auto_class(auto_class="AutoConfig")：将当前的 class 注册到给定的 auto class 。该方法仅用于自定义的 config class，因为内置的 config class 已经注册到 AutoConfig。

    • save_pretrained(save_directory: Union[str, os.PathLike], push_to_hub: bool = False, **kwargs)：保存配置对象到 save_directory 目录，从而便于 from_pretrained() 方法加载。

      参数：参考 PreTrainedTokenizerBase.save_pretrained() 方法。

    • to_dict() -> Dict[str, Any]：将配置对象序列化为字典。

    • to_diff_dict() -> Dict[str, Any]：将配置对象序列化为字典，但是字典中移除了所有的默认配置从而便于阅读。

    • to_json_file(json_file_path: Union[str, os.PathLike], use_diff: bool = True) ：将配置对象保存到 json 文件。

    • to_json_string(use_diff: bool = True) -> str ：将配置对象序列化为 json 字符串。

    • update(config_dict: Dict[str, Any])：根据 config_dict 指定的属性来更新当前配置对象的属性。

    • update_from_string(update_str: str)：根据 update_str 指定的属性来更新当前配置对象的属性。

      update_str 的格式为："n_embd=10,resid_pdrop=0.2,scale_attn_weights=false,summary_type=cls_index" 。

二、Data Collator

  1. data collator 是一个对象，它将数据集元素的一个列表作为输入从而构建成一个 batch 。为了能够构建 batch，data collator 可能会应用一些处理（如 padding 或截断）。其中，某些 data collator （如 DataCollatorForLanguageModeling）还在构成的 batch 上应用一些随机数据增强（如，random masking）。

2.1 API

  1. class transformers.DefaultDataCollator(return_tensors: str = 'pt' )：非常简单的 data collator，它简单地处理一组 dict-like 对象，并以下的 key 进行特殊处理：

    • label：为每个 dict-like 对象处理一个 single value。
    • label_ids：为每个 dict-like 对象处理一个 list of values。

    参数：

    • return_tensors：一个字符串，指定返回的 batch 数据的类型。

    示例：

  2. transformers.default_data_collator(features: typing.List[InputDataClass], return_tensors = 'pt')：非常简单的 data collator，是 DefaultDataCollator 的函数式方式。

  3. class transformers.DataCollatorWithPadding：对 input 进行动态填充的 data collator。

    参数：

    • tokenizer：一个 PreTrainedTokenizerBase 对象，指定用于 data encoding 的 tokenizer 。
    • padding：一个布尔值、字符串、或者 PaddingStrategy，参考 PreTrainedTokenizerBase.__call__() 方法。
    • max_length：一个整数，参考 PreTrainedTokenizerBase.__call__() 方法。
    • pad_to_multiple_of：一个整数，参考 PreTrainedTokenizerBase.__call__() 方法。
    • return_tensors：一个字符串，参考 DefaultDataCollator 。

  4. class transformers.DataCollatorForTokenClassification：对 input 和 label 进行动态填充的 data collator。

    参数：

    • label_pad_token_id：一个整数，指定填充 label 的 token id。-100 将被 PyTorch 损失函数自动忽略。
    • 其它参数参考 DataCollatorWithPadding 。

  5. class transformers.DataCollatorForSeq2Seq：对 input 和 label 进行动态填充的 data collator。

    参数：参考 DataCollatorForTokenClassification 。

  6. class transformers.DataCollatorForLanguageModeling：用于语言模型的 data collator 。input 被动态填充到 batch 内的最大长度（如果序列长度不是一样长）。

    参数：

    • mlm：一个布尔值，指定是否使用 masked language modeling 。

      • 如果为 False，那么 label 和 input 完全相同，其中 padding token 被忽略（将它们的 label 设置为 -100）。
      • 如果为 True，那么将 non-masked token 的 label 设置为 -100（从而忽略它们的损失），而 masked token 的 label 设置为 original value 。

    • mlm_probability：一个浮点数，指定 input 中 mask token 的概率，仅当 mlm = True 时有效。

    • tf_experimental_compile：一个布尔值，如果为 True，则基于 tensorflow 来编译。

    • 其它参数参考 DataCollatorForTokenClassification 。

    为了获得最佳性能，这个 应该与一个数据集一起使用，该数据集的item 是带有 "special_tokens_mask" 键的字典或 BatchEncoding （由 PreTrainedTokenizerBase 以参数 return_special_tokens_mask=True 来调用时的返回结果）。

    方法：

    • numpy_mask_tokens(inputs: Any, special_tokens_mask: Optional[Any] = None) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 numpy。
    • tf_mask_tokens(inputs: typing.Any, vocab_size, mask_token_id, special_tokens_mask: typing.Optional[typing.Any] = None) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 TensorFlow。
    • torch_mask_tokens(inputs: Any, special_tokens_mask: Optional[Any] = None) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 PyTorch。

  7. class transformers.DataCollatorForWholeWordMask：用于语言模型的 data collator ，其中执行全词掩码 whole word masking 。

    参数：参考 DataCollatorForLanguageModeling。

    注意：该 data collator 依赖于 BertTokenizer 的 subword tokenization，尤其是以 ## 为前缀的 subword token 。如果你的 tokenizer 不是这种方案，那么该 data collator 将得到等价于 DataCollatorForLanguageModeling 的结果。

    方法：

    • numpy_mask_tokens(inputs: typing.Any, mask_labels: typing.Any) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 numpy。

      mask_labels 由人工指定哪些索引处的 token 需要被掩码。因为它是由人工指定的 mask，因此被称作 mask_labels。

    • tf_mask_tokens(inputs: typing.Any, mask_labels: typing.Any) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 TensorFlow。

    • torch_mask_tokens(inputs: typing.Any, mask_labels: typing.Any) -> Tuple[Any, Any]：为掩码语言模型准备 masked inputs/labels，其中 80% MASK、10% random、10% original 。用于 Pytorch。

  8. class transformers.DataCollatorForPermutationLanguageModeling：用于排列语言建模 permutation language modeling （如，XLNet）的 data collator。

    参数：

    • plm_probability：一个浮点数，指定掩码率。
    • max_span_length：一个整数，指定 span of masked token 的最大长度。
    • 其它参数参考 DataCollatorForLanguageModeling。

    方法：

    • numpy_mask_tokens(inputs: typing.Any) -> Tuple[Any, Any, Any, Any]：为排列语言模型准备 masked inputs。用于 numpy。

      对于一个特定的序列，要预测的 masked token 是由以下算法决定的：

      • step 0：通过设置 cur_len = 0 （它指定已经处理的 token 数量）来从序列的 beginning 开始。
      • step 1：从区间 [1, max_span_length] 中随机采样一个 span_length （要掩码的 token 的 span 长度）。
      • step 2：保留一个长度为 context_length = span_length / plm_probability 的上下文，从而包围 masked span 。
      • step 3：从区间 [cur_len, cur_len + context_length - span_length] 之间采样一个 start_index，然后掩码 start_index: start_index + span_length 之间的 token 。
      • step 4：设置 cur_len = cur_len + context_length。如果 cur_len < max_len（即，序列中还有剩余的 token 需要被处理），那么从 step 1 开始重复执行。

    • tf_mask_tokens(inputs: typing.Any) -> Tuple[Any, Any, Any, Any]：为排列语言模型准备 masked inputs。用于 Tensorflow。

    • torch_mask_tokens(inputs: typing.Any) -> Tuple[Any, Any, Any, Any]：为排列语言模型准备 masked inputs。用于 PyTorch。

三、Models

  1. 基类 PreTrainedModel, TFPreTrainedModel, FlaxPreTrainedModel 实现了加载/保存模型的通用方法。此外，PreTrainedModel 和 TFPreTrainedModel 还实现了一些通用方法从而：

    • 当添加新 token 到词表时，resize 模型的 input token embedding matrix （注意，是增加 embedding vector，而不是调整 embedding 维度）。
    • 裁剪模型的 attention head 。

    其它的一些通用方法定义在 ModuleUtilsMixin（用于 PyTorch 模型）、或 TFModuleUtilsMixin （用于 TensorFlow 模型）。也有一些用于文本生成的方法定义在 GenerationMixin（用于 PyTorch 模型）、TFGenerationMixin（用于 TensorFlow 模型）、或 FlaxGenerationMixin（用于 Flax/JAX 模型）。

3.1 API

  1. class transformers.PreTrainedModel(config: PretrainedConfig, *inputs, **kwargs)：所有模型的基类。

    PreTrainedModel 负责存储模型的配置，并处理加载、下载、以及保存模型的方法，以及所有模型都有的一些方法（如 resize input embedding、裁剪 the self-attention 中的 head）。

    参数：

    • config：一个 PretrainedConfig 对象，指定模型的配置。
    • inputs：一个位置参数，指定模型的 input 。

    类属性（由派生类重写）：

    • config_class：一个 PretrainedConfig 对象，它是 PretrainedConfig 的子类，指定模型的配置类。

    • load_tf_weights：一个可调用对象，用于在一个 PyTorch 模型中加载一个 TensorFlow checkpoint 。这个可调用对象的参数为：

      • model：一个 PretrainedModel对象，指定用于加载TensorFlow checkpoint的模型实例。
      • config：一个 PreTrainedConfig 对象，指定模型相关的配置对象。
      • path：一个字符串，指定 TensorFlow checkpoint 的路径。

    • base_model_prefix：一个字符串，表示在与 base model 架构相同的派生类（这个派生类在 base model 之上添加模块）中与 base model 相关的属性。

    • is_parallelizable：一个布尔值，表示模型是否支持模型并行。

    • main_input_name：一个字符串，表示模型的 main input 的名字（通常而言，对于 NLP 模型是 "input_ids"、对于视觉模型而言是 "pixel_values"、对于语音模型而言是 "input_values" ）。

    方法：

    • push_to_hub()：将模型文件上传到 Model Hub ，同时同步到 repo_path_or_name 对应的 local clone 。

      参数：参考 PreTrainedTokenizerBase.push_to_hub() 方法。

    • from_pretrained( pretrained_model_name_or_path: typing.Union[str, os.PathLike, NoneType], *model_args, **kwargs)：从一个pre-trained model configuration 中实例化一个 pretrained pytorch model 。

      注意：

      • 该模型通过默认使用 model.eval() 来设置为 evaluation mode （Dropout 模块被停用）。要训练这个模型，你应该先用model.training() 将其设置回 training mode。
      • 警告 Weights from XXX not initialized from pretrained model 意味着 XXX 的权重不与模型的其他部分一起进行预训练。这取决于你用下游的微调任务来训练这些权重。
      • 警告 Weights from XXX not used in YYY 意味着 layer XXX 没有被 YYY 使用，因此这些权重被丢弃。

      参数：

      • pretrained_model_name_or_path：一个字符串或 os.PathLike 对象，可以为：

        • 一个字符串，指定位于 huggingface.co 的 model repo 中的预训练模型的 model id ，如 bert-base-uncased、dbmdz/bert-base-german-cased 。

        • 一个目录的路径，该目录包含模型权重（由 save_pretrained() 保存）。

        • 一个指向 tensorflow index checkpoint file 的路径或 url 。此时，from_tf 参数应该设为 True，并且 config 参数应该被提供一个配置对象。

          这种加载路径比使用提供的转换脚本在 PyTorch 模型中转换 TensorFlow checkpoint 并在之后加载 PyTorch 模型要慢。

        • 一个指向 flax checkpoint file（为 .msgpack 格式） 的路径或 url 。此时，from_flax 参数应该设为 True。

        • None，如果你同事提供了配置文件、以及 state 字典。即，以 config 和 state_dict 关键字参数来传入。

      • model_args：位置参数，它们将被传给底层模型的 __init__ 方法。

      • confg：一个 PretrainedConfig 对象、字符串、或 PathLike 对象，指定用于模型的配置（而不是自动加载配置）。

        如果是字符串或 PathLike 对象，则调用 PretrainedConfig.from_pretrained() 方法。

        对于以下情形，配置将被自动加载：

        • 模型是由 library 提供，即通过预训练模型的 model id 来加载模型。
        • 模型通过 save_pretrained() 方法保存，同时从被保存的目录中再次加载模型。
        • 模型通过以下方式被加载：pretrained_model_name_or_path 是一个本地路径、且该本地路径中找到一个叫做 config.json 的 configuration JSON file 。

      • state_dict：一个 Dict[str, torch.Tensor] 字典，直接指定模型的 state 而不是从保存的权重文件中加载。

        如果你想从一个预训练的配置中创建一个模型，但加载你自己的权重，可以使用这个方式。

      • cache_dir/force_download/resume_download/proxies/local_files_only/use_auth_token/revision：这些参数参考 PreTrainedTokenizerBase.from_pretrained() 。

      • from_tf：一个布尔值，指定是否从 TensorFlow checkpoint save file 中加载模型权重。

      • from_flax：一个布尔值，指定是否从 Flax checkpoint save file 中加载模型权重。

      • ignore_mismatched_sizes：一个布尔值，指定如果 checkpoint 的某些权重与模型的权重尺寸不一致，是否会引发错误。

      • output_loading_info：一个布尔值，指定是否同时返回一个包含 missing keys 、unexpected keys 和 error messages 的字典。

      用于大模型推断的参数：

      • low_cpu_mem_usage：一个布尔值，指定是否试图在加载模型时不使用超过 1 倍的模型大小的 CPU 内存（包括峰值内存）。通常加载模型需要 2 倍于模型的内存大小，一倍用于随机初始化模型（target）、一倍用于预训练好的权重（source）。

        这是一个实验性的功能，可以随时改变。它的工作方式如下：

        • 保存 state_dict 的键。
        • 在创建模型之前放弃 state_dict ，因为后者需要1 倍模型大小的 CPU 内存。
        • 在模型被实例化后，将所有 params/buffers 切换到 meda device （即，empty weights），这些 params/buffers 将要被来自于 state_dict 中的值所替代。
        • 第二次加载 state_dict 。
        • 将来自 state_dict 中的值来替代 params/buffers 。

        目前，它无法处理 deepspeed ZeRO state3，并且忽略了 loading 错误。

      • torch_dtype：一个字符串或 torch.dtype，覆盖默认的 torch.dtype 并在此 dtype 下加载模型。如果传入 "auto"，则 dtype 将自动从模型的权重中推导。

        Pytorch 模型默认使用 torch.float32 的权重类型，如果你需要加载一个 fp16 类型的模型，那么需要再 from_pretrained() 方法中指定 torch_dtype 。

        或者也可以在创建模型的时候，通过 config 来告诉模型是什么类型的权重：

      • device_map：一个字符串，或 Dict[str, Union[int, str, torch.device]] 字典，指定每个子模块对应的设备。不需要细化到每个参数/缓冲区名称，一旦指定一个模块的名字，它的每个子模块将被发送到同一个设备。

        如果模型无法完全容纳在内存中，你可以直接将模型放在不同的设备上（目前仅适用于推断）。要让 Accelerate 自动计算出最优的 device_map ，请设置 device_map="auto" 。此时，Accelerate 将决定模型的每一层放置在哪里，从而最大限度地利用你最快的设备（GPU），并将其余部分卸载到 CPU 上、甚至是磁盘上（如果你没有足够的 GPU 内存或 CPU 内存）。即使模型被分割到几个设备上，它也会像你通常期望的那样运行。

        当你传入一个 device_map （如，"auto"）时，low_cpu_mem_usage 自动被设置为 True。

        你可以通过查看模型的 hf_device_map 属性来检查模型是如何被分片到设备上的：

        或者你也可以直接人工指定：

      • max_memory：一个字典，指定每个设备的最大内存。如果未设定，则默认为每个 GPU 的可用最大内存、以及 CPU 的可用内存。

      • offload_folder：一个字符串或 os.PathLike 对象。如果 device_map 包含任何的值 "disk"，那么这个目录就是我们用于 offload weights 的。

      • offload_state_dict：一个布尔值，如果为 True 那么将暂时把 CPU state dict 卸载 offload 到磁盘上，从而避免 CPU 内存耗尽。当有一些 disk offload 时，默认为 True 。

      • load_in_8bit：一个布尔值，如果为 True，则把加载的模型转换为 mixed-8bit quantized model 。

      • load_in_8bit_threshold：一个浮点数，与 load_in_8bit 一起工作。

      • load_in_8bit_skip_modules：一个字符串列表，指定哪些模块不希望被转换为 8 bit 。

      • subfolder：一个字符串，如果相关的文件位于 huggingface.co 上的模型 repo 的一个子文件夹内，你可以在这里指定文件夹的名称。

      • kwargs：关键字参数，可以用于更新配置对象（在配置对象被加载完成之后）、初始化模型（如 output_attentions=True）。

    • get_input_embeddings() -> nn.Module：返回模型的 input embedding （它将词表映射到 embedding matrix）。

    • get_memory_footprint(return_buffers = True)：返回模型的内存占用，单位是字节。这对于 benchmark 当前模型的内存占用、以及设计某些测试很有用。

    • get_output_embeddings() -> nn.Module：返回模型的 output embedding （它将词表映射到 embedding matrix）。

    • gradient_checkpointing_disable()：停用当前模型的 gradient checkpointing （也被叫做 activation checkpointing 或 checkpoint activations ）。

    • gradient_checkpointing_enable()：启用当前模型的 gradient checkpointing 。

    • init_weights()：如果需要的话，对权重进行裁剪和初始化。

    • post_init()：在每个 Transformer 模型初始化结束时执行的方法（如权重初始化）。

    • prune_heads(heads_to_prune: typing.Dict[int, typing.List[int]] )：裁剪 base model 的 head 。

      参考 PretrainedConfig 的初始化方法。

    • register_for_auto_class( auto_class = 'AutoModel')：将当前 class 注册到给定的 auto class 。

      参考 PretrainedConfig.register_for_auto_class() 方法。

    • resize_token_embeddings(new_num_tokens: typing.Optional[int] = None ) -> torch.nn.Embedding：如果 new_num_tokens != config.vocab_size ，那么 resize 模型的 input token embeddings matrix 。

      参数：new_num_tokens：一个整数，指定新的 token 总数。如果总数增加，那么添加新的被初始化的 embedding vector；如果总数减少，那么从 embedding matrix 尾部移除 embedding vector 。

      如果模型有一个 tie_weights() 方法时，要小心 tying weights embedding 。

    • save_pretrained()：将模型和它的配置文件保存到目录中，以便后续可以使用 from_pretrained() 方法重新加载该模型。

      参数：

      • save_directory/push_to_hub/max_shard_size：参考 PreTrainedTokenizerBase.save_pretrained() 方法。
      • is_main_process：一个布尔值，指定调用该方法的进程是否是主进程。在像 TPU 这样的分布式训练中很有用，需要在所有进程上调用该方法。在这种情况下，仅在主进程上设置 is_main_process=True 从而避免争用。
      • state_dict ：torch.Tensor 的嵌套字典，指定要保存的模型的 state dictionary 。默认为 self.state_dict() ，但可以用来只保存模型的部分内容，或者在恢复模型的 state dictionary 时需要采取特殊的预防措施（比如使用模型并行时）。
      • save_function：一个可调用对象，它用于保存 state dictionary 。在如下场景很有用： TPU 这样的分布式训练，且需要用另一个方法来代替 torch.save 时。
      • safe_serialization：一个布尔值，指定是否使用 safetensors 或传统的 PyTorch 方式（即，pickle）保存模型。
      • kwargs：关键字参数，传递给 push_to_hub() 方法。

    • set_input_embeddings(value: Module )：设置模型的 input embedding 。

      参数：value：一个 nn.Module，它将词表映射到 embedding matrix 。

    • tie_weights()：将 input embedding 和 output embedding 进行权重绑定（即，权重共享）。

      如果在配置中设置了 torchscript flag，那么无法处理权重共享，此时我们将拷贝权重。

  2. class transformers.modeling_utils.ModuleUtilsMixin()：用于 torch.nn.Modules 的一些工具方法，它被作用 mixin 。

    方法：

    • add_memory_hooks()：在每个子模块的前向传播的 before/after 添加一个 memory hook，从而记录内存消耗的增加。

      内存消耗的增加被存储在每个模块的 mem_rss_diff 属性中，可以用 model.reset_memory_hooks_state() 重置为零。

    • estimate_tokens(input_dict: typing.Dict[str, typing.Union[torch.Tensor, typing.Any]]) -> int：一个 helper 方法，用于从 model input 中估计总的 token 数量。

      参数：input_dict：一个字典，给出 model inputs 。

    • floating_point_ops(batch_size:int, sequence_length:int, exclude_embeddings: bool = True ) -> int：获取该 transformer 模型对一个 batch 的前向传播和反向传播的浮点运算数量（non-embedding）。

      参数：

      • batch_size：一个整数，指定 batch size 。
      • sequence_length：一个整数，指定 batch 中每个样本的 token 数量。
      • exclude_embeddings：一个布尔值，指定是否考虑 embedding 操作和 softmax 操作的浮点数运算。

      默认的近似值忽略了对 token 数量的二次方依赖（如果 12 * d_model << sequence_length 则有效）。对于有参数共享的 transformer（如 ALBERT 或 Universal Transformer），或者对长序列进行长距离建模时，应该重写该方法。

    • get_extended_attention_mask(attention_mask: Tensor, input_shape: typing.Tuple[int], device: <property object at 0x7fe13accc720> = None, dtype: torch.float32 = None ) ：获得 broadcastable attention 和 causal mask ，使得未来的和 masked 的 token 被忽略。

      参数：

      • attention_mask：一个张量，指定 Mask，其中元素 1 代表 un-masked、0 代表 masked。
      • input_shape：一个元组（类型为整数），指定模型的 input 的形状。

    • get_head_mask( head_mask: typing.Optional[torch.Tensor], num_hidden_layers: int, is_attention_chunked: bool = False)：准备 head mask 。

      参数：

      • head_mask：一个形状为 [num_heads] 或 [num_hidden_layers x num_heads] 的张量，指定我们要保留哪些 head（1 表示保留，0 表示放弃）。
      • num_hidden_layers：一个整数，指定模型的隐层的数量。
      • is_attention_chunked：一个布尔值，指定 attentions score 是否按 chunk 来计算的。

    • invert_attention_mask( encoder_attention_mask: Tensor ) -> torch.Tensor：翻转一个 attention mask（即，翻转 0 和 1）。

    • num_parameters(only_trainable: bool = False， exclude_embeddings: bool = False ) -> int：返回模型中的所有参数数量。

      参数：

      • only_trainable：一个布尔值，指定是否进考虑可训练的参数。
      • exclude_embeddings：一个布尔值，指定是否排除 embedding 参数。

    • reset_memory_hooks_state()：清零每个模块的 mem_rss_diff 属性。

  3. class transformers.TFPreTrainedModel(*args, **kwargs) ：所有 TF 模型的基类。

    参数：参考 PreTrainedModel 。

    类别属性：参考 PreTrainedModel 。

    方法：

    • push_to_hub()：参考 PreTrainedModel.push_to_hub() 。

    • compile()：编译模型。

    • create_model_card()：创建一个 model card 。

    • eager_serving(inputs)：用于 model serving 的方法。打算不与 tf.function decorator 一起编译，以便我们以后可以用它来生成多个 signature。

      参数：inputs ：一个字典 Dict[str, tf.Tensor]，用于 saved model 的输入。

    • from_pretrained(pretrained_model_name_or_path, *model_args, **kwargs )：参考 PreTrainedModel.from_pretrained() 。

    • get_bias() -> tf.Variable：关联到 LM head 的、关于 bias 的字典，key 为 bias 属性的名字。

    • get_input_embeddings() -> tf.Variable：参考 PreTrainedModel.get_input_embeddings() 。

    • get_lm_head() -> tf.keras.layers.Layer：获取 LM Head Layer （如果模型只有一个 head layer）或者返回 None 。

      对于拥有 lm head 的所有模型，必须重写该方法。

    • get_output_embeddings()：参考 PreTrainedModel.get_output_embeddings() 。

    • get_output_layer_with_bias() -> tf.keras.layers.Layer：获取 output layer 。

    • get_prefix_bias_name() -> str：获取 bias 的被拼接的 _prefix name 。

    • load_repo_checkpoint(repo_path_or_name) -> dict：从一个 repo 中加载一个 saved checkpoint（包含模型权重和 optimizer state）。

      返回一个字典，该字典包含 extra metadata 信息，例如当前的 epoch 计数。

    • prepare_tf_dataset()：将 HuggingFace Dataset 封装为一个具有 collation 和 batching 的 tf.data.Dataset 。

      该方法用于创建一个 ready-to-use 的 dataset，从而可以直接传递给 Keras 的方法（如 fit()）而无需进一步修改。

      如果数据集的列与模型的 input names 不匹配，那么不匹配的列将从数据集中删除。如果你想指定返回的列名，而不是使用与该模型相匹配的名字，我们建议使用 Dataset.to_tf_dataset() 代替。

    • prune_heads(heads_to_prune )：参考 PreTrainedModel.prune_heads() 方法。

    • register_for_auto_class(auto_class = 'TFAutoModel' )：参考 PreTrainedModel.register_for_auto_class() 方法。

    • resize_token_embeddings(new_num_tokens: typing.Optional[int] = None ) -> tf.Variable or tf.keras.layers.Embedding：参考 PreTrainedModel.resize_token_embeddings() 方法。

    • save_pretrained()：将模型和它的配置文件保存到目录中，以便后续可以使用 from_pretrained() 方法重新加载该模型。

      参数：

      • save_directory/push_to_hub/max_shard_size/safe_serialization/kwargs：参考 PreTrainedModel.save_pretrained() 方法。
      • saved_model：一个布尔值，指定模型是否也必须以 saved model 格式保存。
      • version：一个整数，指定 saved model 的版本。
      • signatures：一个字典或 tf.function，指定用于 serving 的 model's signature。这将被传递给 model.save() 的 signatures 参数。
      • create_pr：一个布尔值，指定是否创建一个 PR 还是直接 commit 。

    • serving(inputs: Dict[str, tf.Tensor])：用于 model serving 的方法。

      参数：inputs：一个从字符串到 tf.Tensor 的字典，给出 saved model 的 input 。

    • serving_output(output: TFBaseModelOutput)：准备 saved model 的 output。每个模型必须实现该方法。

      参数：output：由模型返回的 output 。

    • set_bias(value: Dict[tf.Variable])：设置 LM head 中的所有 bias 。

    • set_input_embeddings(value)：参考 PreTrainedModel.set_input_embeddings() 方法。

    • set_output_embeddings(value)：设置模型的 output embedding 。

    • test_step(data)：对 Keras 默认的 train_step 的修改，为我们的模型正确处理了我们 outputs 与 labels 的匹配，并支持直接在 loss output head 上进行训练。此外，它确保 input keys 在适当的地方被复制到 labels 上。当使用 dummy loss 时，它也会将 label keys 复制到 input dict 中，以确保它们在前向传播过程中对模型可用。

    • train_step(data)：参考 test_step() 。

  4. class transformers.modeling_tf_utils.TFModelUtilsMixin()：用于 tf.keras.Model 的一些工具方法，它被作用 mixin 。

    方法：

    • num_parameters(only_trainable: bool = False) -> int：参考 ModuleUtilsMixin.num_parameters() 。

  5. class transformers.FlaxPreTrainedModel：所有 Flax 模型的基类。

    参数：参考 PreTrainedModel 。

    类别属性：参考 PreTrainedModel 。

    方法：

    • load_flax_sharded_weights(shard_files: List[str]) -> Dict：加载 flax 模型的权重。这种加载是高效的：每个 checkpoint shard 在 RAM 中被逐一加载，并在被加载到模型中之后被删除。

      返回模型参数的嵌套字典，格式为 {'model': {'params': {'...'}}} 。

    • to_bf16(params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict], mask: typing.Any = None) ：将浮点参数强制类型转换为 jax.numpy.bfloat16 。它返回一个新的 prams tree 而不是原地转换。

      参数：

      • params：一个字典或 FrozenDict ，给出了模型参数的 PyTree 。
      • mask：与 params 结构相同的 PyTree，叶子节点为布尔值，表示对应的 params 是否需要强制类型转换。

      该方法可以在 TPU 上使用，从而模型参数显式转换为 bfloat16 精度。

    • to_fp16(params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict], mask: typing.Any = None)：将浮点参数强制类型转换为 jax.numpy.float16 。参考 to_bf16。

      该方法可以在 GPU 上使用，从而模型参数显式转换为 float16 精度。

    • to_fp32(params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict], mask: typing.Any = None)：将浮点参数强制类型转换为 jax.numpy.float32 。参考 to_bf16。

    • 以下方法参考 TFPreTrainedModel：

  6. class transformers.utils.PushToHubMixin()：一个 mixin，它包含一些函数用于 push 一个模型或 tokenizer 到 hub 上。

    方法：

    • push_to_hub()：参考 PreTrainedModel.push_to_hub() 。

  7. transformers.modeling_utils.load_sharded_checkpoint(model: torch.nn.Module, folder: str or os.PathLike, strict = True) -> NamedTuple：与 torch.nn.Module.load_state_dict() 相同，但是该函数用于 sharded checkpoint 。

    这种加载是高效的：每个 checkpoint shard 在 RAM 中被逐一加载，并在被加载到模型中之后被删除。

    参数：

    • model：一个 Module 对象，指定哪个模型需要加载 checkpoint。
    • folder：一个字符串或 os.PathLike对象，指定哪个目录包含 checkpoint。
    • strict：一个布尔值，指定是否严格加载（即，model state dict 和 sharded checkpoint 严格匹配）。

    返回一个命名元组，包含两个字段：

    • missing_keys：包含 missing key 的列表。
    • unexpected_keys：包含 unexpected key 的列表。

四、Model outputs

  1. 所有模型都有 outputs，它们都是 ModelOutput 的子类的实例，是包含了模型返回的所有信息的数据结构。ModelOutput 实例也可以作为元组或字典来使用。

    例如：

    其中 outputs 对象是 SequenceClassifierOutput 实例，它包含一些属性（loss、logits、grad_fn、hidden_states、attentions）。在这里有 loss ，这是因为我们传入了 label 参数；但是没有 hidden_states 和 attentions ，这是因为我们没有传递 output_hidden_states=True 或者 output_attention=True 参数。

    • 当把 output 对象视为元组时，它只考虑那些不是 None 值的属性。例如，这里有两个元素，loss 和 logits ，所以 outputs[:2] 将返回元组 (outputs.loss, outputs.logits) 。
    • 当把 outputs 对象看作字典时，它只考虑那些不是 None 值的属性。例如，这里有两个键，分别是 "loss"和"logits"。

  2. 我们在这里记录了被一个以上的模型类型使用的通用 model outputs 。具体的output 类型在其相应的模型页面上有记录。

4.1 API

  1. class transformers.utils.ModelOutput()：作为所有模型输出的基类。有一个__getitem__ 方法从而允许通过整数或切片（像一个元组）进行索引、或者通过字符串（像一个字典）进行索引，这两种方式都将忽略取值为 None 的属性。

    注意：不能直接解包一个 ModelOutput 对象，而是必须首先通过 .to_tuple() 方法将它转换为一个元组。

    方法：

    • to_tuple()：将当前 ModelOutput 实例转换为包含所有不是 None 的属性值的元组。

  2. class transformers.modeling_outputs.BaseModelOutput：model outputs 的基类，带有 hidden states 和 attentions 。

    参数：

    • last_hidden_state：一个 torch.FloatTensor 张量，张量形状为 (batch_size, sequence_length, hidden_size)，给出模型最后一层输出层的 hidden-state 序列。

    • hidden_states：一个关于torch.FloatTensor 张量的元组，给出模型每一层的 hidden-state 序列。每个张量的形状为 (batch_size, sequence_length, hidden_size)。

      当模型传入 output_hidden_states=True 或者 PretrainedConfig 配置的 config.output_hidden_states=True 时才生效。

      如果模型有 embedding layer，那么也返回 embedding 序列。

    • attentions：一个关于torch.FloatTensor 张量的元组，给出模型每一层每一个 head 的 attention 矩阵（经过了 attention softmax 之后）。 每个张量的形状为 (batch_size, num_heads, sequence_length, sequence_length)。

      当模型传入 output_attentions=True 或者 PretrainedConfig 配置的 config.output_attentions=True 时才生效。

  3. class transformers.modeling_outputs.BaseModelOutputWithPooling：包含 last hidden states 的池化操作的、用于 model outputs 的基类。

    参数：

    • pooler_output：一个 torch.FloatTensor 张量，形状为 (batch_size, hidden_size)，给出序列第一个 token （即，classification token ）在最后一层的 hidden_state （在通过用于辅助预训练任务的层进一步处理之后）。

      例如，对于 BERT 家族的模型，它返回通过线性层和 tanh 激活函数处理之后的 classification token 的 hidden state 。线性层的权重是在预训练期间通过 next sentence prediction 的分类任务目标中训练而来的。

    • 其它参数参考 BaseModelOutput 。

  4. class transformers.modeling_outputs.BaseModelOutputWithCrossAttentions：model outputs 的基类，带有 hidden states 和 attentions 和 cross_attentions 。

    参数：

    • cross_attentions：一个关于torch.FloatTensor 张量的元组，给出解码器的 cross-attention layer 的注意力矩阵（经过了 attention softmax 之后）。每个张量的形状为 (batch_size, num_heads, sequence_length, sequence_length)。

      当模型传入 output_attentions=True 且 PretrainedConfig 配置的 config.add_cross_attention=True ，或者 PretrainedConfig 配置的 config.output_attentions=True 时才生效。

    • 其它参数参考 BaseModelOutput 。

  5. class transformers.modeling_outputs.BaseModelOutputWithPoolingAndCrossAttentions：包含 last hidden states 的池化操作的、用于 model outputs 的基类。

    参数：

    • past_key_values：一个关于torch.FloatTensor 张量的元组的元组，给定预先计算好的 hidden-states （ self-attention blocks 中的 keys 和 values ），可以用来加速序列解码。内层包含两个元组，每个元组的形状都是 (batch_size, num_heads, sequence_length, embed_size_per_head) 从而分别代表 keys 和 values 。

      当模型传入 use_cache=True 或者 PretrainedConfig 配置的 config.use_cache=True 时才生效。

      如果 config.is_encoder_decoder=True 时，内层包含四个元组，除了 keys 和 values 之外，还有两个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的元组。

    • 其它参数参考 BaseModelOutputWithPooling 和 BaseModelOutputWithCrossAttentions 。

  6. class transformers.modeling_outputs.BaseModelOutputWithPast：包含 past key/values 的（用于加速序列解码）、用于 model outputs 的基类。

    参数：参考 BaseModelOutputWithPoolingAndCrossAttentions 。

  7. class transformers.modeling_outputs.BaseModelOutputWithPastAndCrossAttentions：包含 past key/values 的（用于加速序列解码）、用于 model outputs 的基类。

    参数：参考 BaseModelOutputWithPoolingAndCrossAttentions 。

  8. class transformers.modeling_outputs.Seq2SeqModelOutput：用于编码器和解码器的 outputs 的基类。

    参数：

    • last_hidden_state：一个 torch.FloatTensor 张量，张量形状为 (batch_size, sequence_length, hidden_size)，，给出解码器最后一层输出层的 hidden-states 序列。
    • 其它参数参考 BaseModelOutputWithPast，其中这里区分编码器和解码器的输出。

  9. class transformers.modeling_outputs.CausalLMOutput：用于语言模型（或自回归模型）的 outputs 的基类。

    参数：

    • loss：一个 torch.FloatTensor 张量，形状为 (1, )，指定模型损失（next-token prediction 任务），当提供了 labels 的时候生效。
    • logits：一个 torch.FloatTensor 张量，形状为 (batch_size, sequence_length, config.vocab_size)，指定语言模型在每个 vocabulary token 上的预测分（经历 SoftMax 之前）。
    • 其它参数参考 BaseModelOutput 。

  10. class transformers.modeling_outputs.CausalLMOutputWithCrossAttentions：包含 past key/values 的（用于加速序列解码）、用于语言模型（或自回归模型）的 outputs 的基类。

    参数：参考 CausalLMOutput 和 BaseModelOutputWithPastAndCrossAttentions 。

  11. class transformers.modeling_outputs.CausalLMOutputWithPast：包含 past key/values 的（用于加速序列解码）、用于语言模型（或自回归模型）的 outputs 的基类。

    参数：参考 CausalLMOutput 和 BaseModelOutputWithPast 。

  12. class transformers.modeling_outputs.MaskedLMOutput：用于掩码语言模型（即，MLM ）的 outputs 的基类。

    参数：参考 CausalLMOutput，但是这里的 loss 是 MLM 任务的损失。

  13. class transformers.modeling_outputs.NextSentencePredictorOutput：用于 next sentence prediction 模型（即，NSP ）的 outputs 的基类。

    参数：参考 CausalLMOutput，但是这里的 loss 是 NSP 任务的损失，这里 logits 的形状为 (batch_size, 2) 。

  14. class transformers.modeling_outputs.SequenceClassifierOutput：用于句子分类模型的 outputs 的基类。

    参数：参考 CausalLMOutput，但是这里的 loss 是句子分类任务的损失，这里 logits 的形状为 (batch_size, config.num_labels) 。

    注意，如果 config.num_labels = 1，那么就是句子回归任务。

  15. class class transformers.modeling_outputs.Seq2SeqSequenceClassifierOutput：用于 sequence-to-sequence 的句子分类模型的 outputs 的基类。

    参数：参考 CausalLMOutput 和 Seq2SeqModelOutput ，但是这里的 loss 是句子分类任务的损失，这里 logits 的形状为 (batch_size, config.num_labels) 。

    注意，如果 config.num_labels = 1，那么就是句子回归任务。

  16. class transformers.modeling_outputs.MultipleChoiceModelOutput：用于 multiple choice 模型的 outputs 的基类。

    参数：参考 CausalLMOutput ，但是这里的 loss 是 multiple choice 分类任务的损失，这里 logits 的形状为 (batch_size, num_choices) 。

  17. class transformers.modeling_outputs.TokenClassifierOutput：用于 token 分类模型的 outputs 的基类。

    参数：参考 CausalLMOutput ，但是这里的 loss 是 token 分类任务的损失，这里 logits 的形状为 (batch_size, sequence_length, config.num_labels) 。

  18. class transformers.modeling_outputs.QuestionAnsweringModelOutput：用于问答模型的 outputs 的基类。

    参数：

    • loss：一个torch.FloatTensor 张量，形状为 (1,) ，指定模型损失（问答任务），当提供了 labels 的时候生效。

      问答任务的损失是 total span extraction loss，它是针对 start 位置和 end 位置的交叉熵损失之和。

    • start_logits：一个torch.FloatTensor 张量，形状为 (batch_size, sequence_length) ，指定问答任务的 span-start 得分（在通过 SoftMax 之前）。

    • end_logits：一个torch.FloatTensor 张量，形状为 (batch_size, sequence_length) ，指定问答任务的 span-end 得分（在通过 SoftMax 之前）。

    • 其它参数参考 BaseModelOutput 。

  19. class transformers.modeling_outputs.Seq2SeqQuestionAnsweringModelOutput：用于 sequence-to-sequence 的问答模型的 outputs 的基类。

    参数：参考 QuestionAnsweringModelOutput 和 Seq2SeqModelOutput 。

  20. class transformers.modeling_outputs.SemanticSegmenterOutput：用于语义分割模型的 outputs 的基类。

    参数：参考 CausalLMOutput ，但是这里的 loss 是语义分割任务的损失，这里 logits 的形状为 (batch_size, config.num_labels, logits_height, logits_width) 从而指定了每个像素的 classification score 。

    注意，如果 config.num_labels = 1，那么就是回归任务。

    注意，对于语义分割任务，sequence_length 就是 patch_size 。

  21. class transformers.modeling_outputs.ImageClassifierOutput：用于图片分类模型的 outputs 的基类。

    参数：参考 CausalLMOutput ，但是这里的 loss 是图片分类任务的损失，这里 logits 的形状为 (batch_size, config.num_labels) 。

    注意，如果 config.num_labels = 1，那么就是回归任务。

    注意，对于图片分类任务，sequence_length 就是 patch_size 。

  22. class transformers.modeling_outputs.ImageClassifierOutputWithNoAttention：不带 attention 的、用于图片分类模型的 outputs 的基类。

    参数参考 ImageClassifierOutput。

  23. class transformers.modeling_outputs.DepthEstimatorOutput：depth estimation 模型的 outputs 的基类。

    参数：

    • predicted_depth：一个 torch.FloatTensor 张量，形状为 (batch_size, height, width) ，给出了每个像素的 predicted depth 。
    • 其它参数参考 ImageClassifierOutput 。

  24. class transformers.modeling_outputs.Wav2Vec2BaseModelOutput：用于具有 Wav2Vec2 loss 目标所训练的模型的 outputs 的基类。

    参数：

    • extract_features：一个 torch.FloatTensor 张量，形状为 (batch_size, sequence_length, conv_dim[-1])，指定模型最后一个卷积层抽取的特征向量的序列。
    • 其它参数参考 BaseModelOutput 。

  25. class transformers.modeling_outputs.XVectorOutput：Wav2Vec2ForXVector 类型的 output 。

    参数：

    • loss：一个形状为 (1,) 的 torch.FloatTensor 张量，给出分类损失。仅当为模型提供了 labels 时才有效。
    • logits：一个 torch.FloatTensor 张量，形状为 (batch_size, config.xvector_output_dim)，给出了位于 AMSoftmax 之前的 classification hidden states 。
    • embeddigns：一个 torch.FloatTensor 张量，形状为 (batch_size, config.xvector_output_dim)，给出了 embedding 从而用于 similarity-based 的向量检索 。
    • 其它参数参考 BaseModelOutput 。

  26. 针对 Tensorflow 的 Output 基类，它们的详细说明请参考对应的 PyTorch 版本：

  27. 针对 Flax/JAX 的 Output 基类，它们的详细说明请参考对应的 PyTorch 版本：

    其中它们都有一个方法：

    • replace( **updates)：返回一个新的对象，该新对象针对指定的字段用新的值来替代。