Transformers 4.37 中文文档（九十八）（5）

Transformers 4.37 中文文档（九十八）（4）https://developer.aliyun.com/article/1563871

内部助手

自定义层和实用工具

原文链接：huggingface.co/docs/transformers/v4.37.2/en/internal/modeling_utils

此页面列出了库中使用的所有自定义层，以及为建模提供的实用函数。

大多数情况下，这些只有在研究库中模型的代码时才有用。

Pytorch 自定义模块

class transformers.Conv1D

<源代码>

( nf nx )

参数

• nf（int）- 输出特征的数量。
  
• nx（int）- 输入特征的数量。
  

由 Radford 等人为 OpenAI GPT（也用于 GPT-2）定义的一维卷积层。

基本上像一个线性层，但权重是转置的。

class transformers.modeling_utils.PoolerStartLogits

<源代码>

( config: PretrainedConfig )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size。

从序列隐藏状态计算 SQuAD 开始 logits。

forward

<源代码>

( hidden_states: FloatTensor p_mask: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。
  
• p_mask（形状为(batch_size, seq_len)的torch.FloatTensor，可选）- 用于无效位置的标记的掩码，例如查询和特殊符号（PAD，SEP，CLS）。1.0 表示应该屏蔽标记。
  

返回

torch.FloatTensor

SQuAD 的开始 logits。

class transformers.modeling_utils.PoolerEndLogits

<源代码>

( config: PretrainedConfig )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size和要使用的layer_norm_eps。

从序列隐藏状态计算 SQuAD 结束 logits。

forward

<源代码>

( hidden_states: FloatTensor start_states: Optional = None start_positions: Optional = None p_mask: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。
  
• start_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor，可选）- 标记跨度的第一个标记的隐藏状态。
  
• start_positions（形状为(batch_size,)的torch.LongTensor，可选）- 标记跨度的第一个标记的位置。
  
• p_mask（形状为(batch_size, seq_len)的torch.FloatTensor，可选）- 用于无效位置的标记的掩码，例如查询和特殊符号（PAD，SEP，CLS）。1.0 表示应该屏蔽标记。
  

返回

torch.FloatTensor

SQuAD 的结束 logits。

start_states或start_positions中的一个应该不是None。如果两者都设置了，start_positions会覆盖start_states。

class transformers.modeling_utils.PoolerAnswerClass

<源代码>

( config )

参数

• config（PretrainedConfig）- 模型使用的配置，将用于获取模型的hidden_size。

从分类和开始标记的隐藏状态计算 SQuAD 2.0 答案类。

forward

<源代码>

( hidden_states: FloatTensor start_states: Optional = None start_positions: Optional = None cls_index: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为(batch_size, seq_len, hidden_size)的torch.FloatTensor）- 模型的最终隐藏状态。
  
• start_states (torch.FloatTensor of shape (batch_size, seq_len, hidden_size), optional) — 标记范围内第一个标记的隐藏状态。
  
• start_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内第一个标记的位置。
  
• cls_index (torch.LongTensor of shape (batch_size,), optional) — 每个句子中 CLS 标记的位置。如果为None，则取最后一个标记。
  

返回

torch.FloatTensor

SQuAD 2.0 答案类。

start_states或start_positions中的一个应该不是None。如果两者都设置了，start_positions会覆盖start_states。

class transformers.modeling_utils.SquadHeadOutput

<来源>

( loss: Optional = None start_top_log_probs: Optional = None start_top_index: Optional = None end_top_log_probs: Optional = None end_top_index: Optional = None cls_logits: Optional = None )

参数

• loss (torch.FloatTensor of shape (1,), optional, 如果提供了start_positions和end_positions则返回) — 分类损失，作为起始标记、结束标记（如果提供了 is_impossible 则包括）分类损失的总和。
  
• start_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前 config.start_n_top 个起始标记可能性的对数概率（beam-search）。
  
• start_top_index (torch.LongTensor of shape (batch_size, config.start_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前 config.start_n_top 个起始标记可能性的索引（beam-search）。
  
• end_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前config.start_n_top * config.end_n_top个结束标记可能性的对数概率（beam-search）。
  
• end_top_index (torch.LongTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, 如果未提供start_positions或end_positions则返回) — 前config.start_n_top * config.end_n_top个结束标记可能性的索引（beam-search）。
  
• cls_logits (torch.FloatTensor of shape (batch_size,), optional, 如果未提供start_positions或end_positions则返回) — 答案的is_impossible标签的对数概率。
  

用于使用 SQuADHead 的问答模型输出的基类。

class transformers.modeling_utils.SQuADHead

<来源>

( config )

参数

• config (PretrainedConfig) — 模型使用的配置，将用于获取模型的hidden_size和要使用的layer_norm_eps。

受 XLNet 启发的 SQuAD 头部。

forward

<来源>

( hidden_states: FloatTensor start_positions: Optional = None end_positions: Optional = None cls_index: Optional = None is_impossible: Optional = None p_mask: Optional = None return_dict: bool = False ) → export const metadata = 'undefined';transformers.modeling_utils.SquadHeadOutput or tuple(torch.FloatTensor)

参数

• hidden_states (torch.FloatTensor of shape (batch_size, seq_len, hidden_size)) — 模型在序列标记上的最终隐藏状态。
  
• start_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内第一个标记的位置。
  
• end_positions (torch.LongTensor of shape (batch_size,), optional) — 标记范围内最后一个标记的位置。
  
• cls_index (torch.LongTensor of shape (batch_size,), optional) — 每个句子中 CLS 标记的位置。如果为None，则取最后一个标记。
  
• is_impossible (torch.LongTensor of shape (batch_size,), optional) — 问题在段落中是否有可能回答。
  
• p_mask (torch.FloatTensor of shape (batch_size, seq_len), optional) — 用于无效位置的标记的掩码，例如查询和特殊符号（PAD、SEP、CLS）。1.0 表示应该屏蔽标记。
  
• return_dict (bool, optional, 默认为False) — 是否返回 ModelOutput 而不是普通元组。
  

返回

transformers.modeling_utils.SquadHeadOutput 或tuple(torch.FloatTensor)

一个 transformers.modeling_utils.SquadHeadOutput 或一个torch.FloatTensor元组（如果传递了return_dict=False或当config.return_dict=False时）包含根据配置（）和输入的不同元素。

• loss (torch.FloatTensor of shape (1,), optional, returned if both start_positions and end_positions are provided) — 分类损失，作为开始令牌、结束令牌（如果提供）的分类损失之和。
  
• start_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top), optional, returned if start_positions or end_positions is not provided) — 前端令牌可能性的前config.start_n_top个的对数概率（波束搜索）。
  
• start_top_index (torch.LongTensor of shape (batch_size, config.start_n_top), optional, returned if start_positions or end_positions is not provided) — 前config.start_n_top个开始令牌可能性的索引（波束搜索）。
  
• end_top_log_probs (torch.FloatTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, returned if start_positions or end_positions is not provided) — 顶部config.start_n_top * config.end_n_top结束令牌可能性的对数概率（波束搜索）。
  
• end_top_index (torch.LongTensor of shape (batch_size, config.start_n_top * config.end_n_top), optional, returned if start_positions or end_positions is not provided) — 顶部config.start_n_top * config.end_n_top结束令牌可能性的索引（波束搜索）。
  
• cls_logits (torch.FloatTensor of shape (batch_size,), optional, returned if start_positions or end_positions is not provided) — 答案的is_impossible标签的对数概率。
  

class transformers.modeling_utils.SequenceSummary

< source >

( config: PretrainedConfig )

参数

• config (PretrainedConfig) — 模型使用的配置。模型的配置类中的相关参数为（请参考您的模型的实际配置类以查看其使用的默认值）：

• summary_type (str) — 用于制作摘要的方法。接受的值为：

• "last" — 获取最后一个令牌的隐藏状态（类似于 XLNet）
  
• "first" — 获取第一个令牌的隐藏状态（类似于 Bert）
  
• "mean" — 取所有令牌隐藏状态的平均值
  
• "cls_index" — 提供分类令牌位置的张量（GPT/GPT-2）
  
• "attn" — 目前未实现，使用多头注意力
  

• summary_use_proj (bool) — 在向量提取后添加一个投影。
  
• summary_proj_to_labels (bool) — 如果为True，则投影输出到config.num_labels类（否则为config.hidden_size）。
  
• summary_activation (Optional[str]) — 设置为"tanh"以在输出中添加 tanh 激活，另一个字符串或None将不添加激活。
  
• summary_first_dropout (float) — 投影和激活之前的可选丢弃概率。
  
• summary_last_dropout (float)— 投影和激活后的可选丢弃概率。
  

计算序列隐藏状态的单个向量摘要。

forward

< source >

( hidden_states: FloatTensor cls_index: Optional = None ) → export const metadata = 'undefined';torch.FloatTensor

参数

• hidden_states（形状为[batch_size, seq_len, hidden_size]的torch.FloatTensor）- 最后一层的隐藏状态。
  
• cls_index（形状为[batch_size]或[batch_size, ...]的torch.LongTensor，其中…是hidden_states的可选前导维度，可选）- 如果summary_type == "cls_index"，则用于将序列的最后一个标记作为分类标记。
  

返回

torch.FloatTensor

序列隐藏状态的摘要。

计算序列隐藏状态的单个向量摘要。

PyTorch 辅助函数

transformers.apply_chunking_to_forward

<来源>

( forward_fn: Callable chunk_size: int chunk_dim: int *input_tensors ) → export const metadata = 'undefined';torch.Tensor

参数

• forward_fn（Callable[..., torch.Tensor]）- 模型的前向函数。
  
• chunk_size（int）- 分块张量的块大小：num_chunks = len(input_tensors[0]) / chunk_size。
  
• chunk_dim（int）- 应该对input_tensors进行分块的维度。
  
• input_tensors（Tuple[torch.Tensor]）- forward_fn的输入张量，将被分块
  

返回

torch.Tensor

一个与应用forward_fn后给出的forward_fn相同形状的张量。

此函数将input_tensors分块为大小为chunk_size的较小输入张量部分，沿着维度chunk_dim。然后独立地对每个块应用层forward_fn以节省内存。

如果forward_fn在chunk_dim上独立，这个函数将产生与直接将forward_fn应用于input_tensors相同的结果。

示例：

# rename the usual forward() fn to forward_chunk()
def forward_chunk(self, hidden_states):
    hidden_states = self.decoder(hidden_states)
    return hidden_states
# implement a chunked forward function
def forward(self, hidden_states):
    return apply_chunking_to_forward(self.forward_chunk, self.chunk_size_lm_head, self.seq_len_dim, hidden_states)

transformers.pytorch_utils.find_pruneable_heads_and_indices

<来源>

( heads: List n_heads: int head_size: int already_pruned_heads: Set ) → export const metadata = 'undefined';Tuple[Set[int], torch.LongTensor]

参数

• heads（List[int]）- 要修剪的头的索引列表。
  
• n_heads（int）- 模型中头的数量。
  
• head_size（int）- 每个头的大小。
  
• already_pruned_heads（Set[int]）- 一个已经修剪的头的集合。
  

返回

Tuple[Set[int], torch.LongTensor]

一个元组，其中包括要修剪的头的索引（考虑already_pruned_heads）和要在层权重中保留的行/列的索引。

找到头和它们的索引，考虑already_pruned_heads。

transformers.prune_layer

<来源>

( layer: Union index: LongTensor dim: Optional = None ) → export const metadata = 'undefined';torch.nn.Linear or Conv1D

参数

• layer（Union[torch.nn.Linear, Conv1D]）- 要修剪的层。
  
• index（torch.LongTensor）- 要在层中保留的索引。
  
• dim（int，可选）- 保留索引的维度。
  

返回

torch.nn.Linear或 Conv1D

将修剪后的层作为一个新的层，requires_grad=True。

修剪一个 Conv1D 或线性层，只保留索引中的条目。

用于移除头。

transformers.pytorch_utils.prune_conv1d_layer

<来源>

( layer: Conv1D index: LongTensor dim: int = 1 ) → export const metadata = 'undefined';Conv1D

参数

• layer（Conv1D）- 要修剪的层。
  
• index（torch.LongTensor）- 要在层中保留的索引。
  
• dim（int，可选，默认为 1）- 保留索引的维度。
  

返回

Conv1D

将修剪后的层作为一个新的层，requires_grad=True。

修剪一个 Conv1D 层，只保留索引中的条目。Conv1D 作为一个线性层工作（参见例如 BERT），但权重是转置的。

用于移除头。

transformers.pytorch_utils.prune_linear_layer

<来源>

( layer: Linear index: LongTensor dim: int = 0 ) → export const metadata = 'undefined';torch.nn.Linear

参数

• layer（torch.nn.Linear）- 要修剪的层。
  
• index（torch.LongTensor）- 要在层中保留的索引。
  
• dim（int，可选，默认为 0）- 保留索引的维度。
  

返回

torch.nn.Linear

修剪的层作为一个新层，requires_grad=True。

修剪线性层以仅保留索引中的条目。

用于移除头部。

TensorFlow 自定义层

class transformers.modeling_tf_utils.TFConv1D

<来源>

( nf nx initializer_range = 0.02 **kwargs )

参数

• nf（int）— 输出特征的数量。
  
• nx（int）— 输入特征的数量。
  
• initializer_range（float，可选，默认为 0.02）— 用于初始化权重的标准差。
  
• kwargs（Dict[str, Any]，可选）— 传递给tf.keras.layers.Layer的__init__的额外关键字参数。
  

由 Radford 等人为 OpenAI GPT 定义的一维卷积层（也用于 GPT-2）。

基本上像一个线性层，但权重是转置的。

class transformers.TFSequenceSummary

<来源>

( config: PretrainedConfig initializer_range: float = 0.02 **kwargs )

参数

• config（PretrainedConfig）— 模型使用的配置。模型的配置类中的相关参数为（请参考您的模型的实际配置类以获取其使用的默认值）：

• summary_type（str）— 用于生成此摘要的方法。接受的值为：

• "last" — 获取最后一个标记的隐藏状态（类似于 XLNet）
  
• "first" — 获取第一个标记的隐藏状态（类似于 Bert）
  
• "mean" — 获取所有标记的隐藏状态的平均值
  
• "cls_index" — 提供一个分类标记位置的张量（GPT/GPT-2）
  
• "attn" — 目前未实现，使用多头注意力
  

• summary_use_proj（bool）— 在向量提取后添加投影。
  
• summary_proj_to_labels（bool）— 如果为True，则投影输出到config.num_labels类（否则到config.hidden_size）。
  
• summary_activation（Optional[str]）— 设置为"tanh"以在输出中添加 tanh 激活，另一个字符串或None将不添加激活。
  
• summary_first_dropout（float）— 投影和激活之前的可选丢弃概率。
  
• summary_last_dropout（float）— 投影和激活之后的可选丢弃概率。
  

• initializer_range（float，默认为 0.02）— 用于初始化权重的标准差。
  
• kwargs（Dict[str, Any]，可选）— 传递给tf.keras.layers.Layer的__init__的额外关键字参数。
  

计算序列隐藏状态的单个向量摘要。

TensorFlow 损失函数

class transformers.modeling_tf_utils.TFCausalLanguageModelingLoss

<来源>

( )

适用于因果语言建模（CLM）的损失函数，即猜测下一个标记的任务。

任何标签为-100 的将在损失计算中被忽略（以及相应的对数）。

class transformers.modeling_tf_utils.TFMaskedLanguageModelingLoss

<来源>

( )

适用于掩码语言建模（MLM）的损失函数，即猜测掩码标记的任务。

任何标签为-100 的将在损失计算中被忽略（以及相应的对数）。

class transformers.modeling_tf_utils.TFMultipleChoiceLoss

<来源>

( )

适用于多项选择任务的损失函数。

class transformers.modeling_tf_utils.TFQuestionAnsweringLoss

<来源>

( )

适用于问答的损失函数。

class transformers.modeling_tf_utils.TFSequenceClassificationLoss

<来源>

( )

适用于序列分类的损失函数。

class transformers.modeling_tf_utils.TFTokenClassificationLoss

<来源>

( )

适用于标记分类的损失函数。

任何标签为-100 的将在损失计算中被忽略（以及相应的 logits）。

TensorFlow 辅助函数

transformers.modeling_tf_utils.get_initializer

<来源>

( initializer_range: float = 0.02 ) → export const metadata = 'undefined';tf.keras.initializers.TruncatedNormal

参数

• initializer_range（float，默认为 0.02）- 初始化器范围的标准差。

返回

tf.keras.initializers.TruncatedNormal

截断正态初始化器。

使用给定范围创建一个tf.keras.initializers.TruncatedNormal。

transformers.modeling_tf_utils.keras_serializable

<来源>

( )

参数

• cls（一个tf.keras.layers.Layers 子类）- 通常在这个项目中是一个TF.MainLayer类，一般必须接受一个config参数作为其初始化器。

装饰一个 Keras Layer 类以支持 Keras 序列化。

这是通过以下方式完成的：

1. 在get_config中的 Keras 配置字典中添加一个transformers_config字典（由 Keras 在序列化时调用）。
   
2. 包装__init__以接受transformers_config字典（由 Keras 在反序列化时传递）并将其转换为实际层初始化器的配置对象。
   
3. 在 Keras 中将类注册为自定义对象（如果 Tensorflow 版本支持），这样在调用tf.keras.models.load_model时就不需要在custom_objects中提供它。
   

transformers.shape_list

<来源>

( tensor: Union ) → export const metadata = 'undefined';List[int]

参数

• tensor（tf.Tensor或np.ndarray）- 我们想要形状的张量。

返回

List[int]

作为列表的张量形状。

在 tensorflow 中处理动态形状。

`

<来源>

( )

适用于多项选择任务的损失函数。

class transformers.modeling_tf_utils.TFQuestionAnsweringLoss

<来源>

( )

适用于问答的损失函数。

class transformers.modeling_tf_utils.TFSequenceClassificationLoss

<来源>

( )

适用于序列分类的损失函数。

class transformers.modeling_tf_utils.TFTokenClassificationLoss

<来源>

( )

适用于标记分类的损失函数。

任何标签为-100 的将在损失计算中被忽略（以及相应的 logits）。

TensorFlow 辅助函数

transformers.modeling_tf_utils.get_initializer

<来源>

( initializer_range: float = 0.02 ) → export const metadata = 'undefined';tf.keras.initializers.TruncatedNormal

参数

• initializer_range（float，默认为 0.02）- 初始化器范围的标准差。

返回

tf.keras.initializers.TruncatedNormal

截断正态初始化器。

使用给定范围创建一个tf.keras.initializers.TruncatedNormal。

transformers.modeling_tf_utils.keras_serializable

<来源>

( )

参数

• cls（一个tf.keras.layers.Layers 子类）- 通常在这个项目中是一个TF.MainLayer类，一般必须接受一个config参数作为其初始化器。

装饰一个 Keras Layer 类以支持 Keras 序列化。

这是通过以下方式完成的：

1. 在get_config中的 Keras 配置字典中添加一个transformers_config字典（由 Keras 在序列化时调用）。
   
2. 包装__init__以接受transformers_config字典（由 Keras 在反序列化时传递）并将其转换为实际层初始化器的配置对象。
   
3. 在 Keras 中将类注册为自定义对象（如果 Tensorflow 版本支持），这样在调用tf.keras.models.load_model时就不需要在custom_objects中提供它。
   

transformers.shape_list

<来源>

( tensor: Union ) → export const metadata = 'undefined';List[int]

参数

• tensor（tf.Tensor或np.ndarray）- 我们想要形状的张量。

返回

List[int]

作为列表的张量形状。

在 tensorflow 中处理动态形状。