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

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

TimeSeriesTransformerForPrediction

class transformers.TimeSeriesTransformerForPrediction

< source >

( config: TimeSeriesTransformerConfig )

参数

• config (TimeSeriesTransformerConfig) — 模型的配置类，包含所有模型的参数。使用配置文件初始化不会加载与模型相关的权重，只会加载配置。查看 from_pretrained()方法以加载模型权重。

带有时间序列预测分布头的时间序列变换器模型。此模型继承自 PreTrainedModel。查看超类文档以获取库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

这个模型也是一个 PyTorch torch.nn.Module子类。将其用作常规的 PyTorch 模块，并参考 PyTorch 文档以获取与一般用法和行为相关的所有内容。

forward

<来源>

( past_values: Tensor past_time_features: Tensor past_observed_mask: Tensor static_categorical_features: Optional = None static_real_features: Optional = None future_values: Optional = None future_time_features: Optional = None future_observed_mask: Optional = None decoder_attention_mask: Optional = None head_mask: Optional = None decoder_head_mask: Optional = None cross_attn_head_mask: Optional = None encoder_outputs: Optional = None past_key_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None use_cache: Optional = None return_dict: Optional = None ) → export const metadata = 'undefined';transformers.modeling_outputs.Seq2SeqTSModelOutput or tuple(torch.FloatTensor)

参数

• past_values（形状为(batch_size, sequence_length)或(batch_size, sequence_length, input_size)的torch.FloatTensor） — 时间序列的过去值，用作上下文以预测未来。此张量的序列大小必须大于模型的context_length，因为模型将使用较大的大小来构建滞后特征，即从过去添加的额外值，以充当“额外上下文”。
  这里的sequence_length等于config.context_length + max(config.lags_sequence)，如果没有配置lags_sequence，则等于config.context_length + 7（默认情况下，config.lags_sequence中最大的回顾索引为 7）。属性_past_length返回过去的实际长度。
  past_values是 Transformer 编码器作为输入的内容（带有可选的附加特征，如static_categorical_features、static_real_features、past_time_features和滞后）。
  可选地，缺失值需要用零替换，并通过past_observed_mask指示。
  对于多变量时间序列，需要input_size > 1 维，并对应于每个时间步长中时间序列的变量数量。
  
• past_time_features（形状为(batch_size, sequence_length, num_features)的torch.FloatTensor） — 必需的时间特征，模型内部将其添加到past_values中。这些可能是诸如“年份中的月份”、“月份中的日期”等编码为向量（例如作为傅立叶特征）的内容。这也可以是所谓的“年龄”特征，基本上帮助模型知道时间序列处于“生活中的哪个阶段”。年龄特征对于远处的过去时间步具有较小的值，并且随着我们接近当前时间步而单调增加。假期特征也是时间特征的一个很好的例子。
  这些特征用作输入的“位置编码”。与像 BERT 这样的模型相反，BERT 中的位置编码是从头开始内部作为模型的参数学习的，而时间序列变换器需要提供额外的时间特征。时间序列变换器仅为static_categorical_features学习额外的嵌入。
  可以将额外的动态实际协变量连接到此张量中，但需要注意的是这些特征必须在预测时已知。
  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。
  
• past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length) or (batch_size, sequence_length, input_size), optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：

• 1 表示“观察到”的值，
  
• 0 表示“缺失”的值（即被零替换的 NaN）。
  

• static_categorical_features (torch.LongTensor of shape (batch_size, number of static categorical features), optional) — 模型将学习嵌入这些静态分类特征，并将其添加到时间序列的值中。
  静态分类特征是所有时间步的值都相同的特征（随时间保持静态）。
  静态分类特征的典型示例是时间序列 ID。
  
• static_real_features (torch.FloatTensor of shape (batch_size, number of static real features), optional) — 可选的静态实数特征，模型将把这些特征添加到时间序列的值中。
  静态实数特征是所有时间步的值都相同的特征（随时间保持静态）。
  静态实数特征的典型示例是促销信息。
  
• future_values (torch.FloatTensor of shape (batch_size, prediction_length) or (batch_size, prediction_length, input_size), optional) — 时间序列的未来值，作为模型的标签。future_values是 Transformer 在训练期间需要学习输出的内容，给定past_values。
  这里的序列长度等于prediction_length。
  有关详细信息，请参阅演示笔记本和代码片段。
  在训练期间，任何缺失值都需要用零替换，并通过future_observed_mask指示。
  对于多变量时间序列，需要input_size > 1 维，并且对应于时间序列每个时间步中的变量数量。
  
• future_time_features (torch.FloatTensor of shape (batch_size, prediction_length, num_features)) — 模型在内部将这些特征添加到future_values中，这些特征是预测窗口所需的时间特征。这些特征可以是诸如“年份中的月份”、“月份中的日期”等编码为向量（例如傅立叶特征）的内容。这些也可以是所谓的“年龄”特征，基本上帮助模型了解时间序列处于“生命中的哪个阶段”。年龄特征对于远处的过去时间步具有较小的值，并且随着我们接近当前时间步而单调增加。假期特征也是时间特征的一个很好的例子。
  这些特征作为输入的“位置编码”。与 BERT 等模型不同，BERT 的位置编码是从头开始内部作为模型的参数学习的，时间序列 Transformer 需要提供额外的时间特征。时间序列 Transformer 仅为static_categorical_features学习额外的嵌入。
  可以将额外的动态实数协变量连接到这个张量中，但需要注意这些特征必须在预测时已知。
  这里的num_features等于config.num_time_features+config.num_dynamic_real_features。
  
• future_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length) or (batch_size, sequence_length, input_size), optional) — 布尔掩码，指示哪些future_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：

• 1 表示“观察到”的值，
  
• 0 表示“缺失”的值（即被零替换的 NaN）。
  

• 这个掩码用于在最终损失计算中过滤缺失值。
  
• attention_mask (torch.Tensor of shape (batch_size, sequence_length), optional) — 用于避免在某些标记索引上执行注意力的掩码。掩码值选在[0, 1]之间：

• 1 表示“未被掩码”的标记，
  
• 0 表示“被掩码”的标记。
  

• 什么是注意力掩码？
  
• decoder_attention_mask (torch.LongTensor of shape (batch_size, target_sequence_length), optional) — 用于避免在某些标记索引上执行注意力的掩码。默认情况下，将使用因果掩码，以确保模型只能查看以前的输入以预测未来。
  
• head_mask (torch.Tensor of shape (encoder_layers, encoder_attention_heads), optional) — 用于将编码器中注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

• 1 表示头部未被屏蔽，
  
• 0 表示头部被屏蔽。
  

• decoder_head_mask (torch.Tensor of shape (decoder_layers, decoder_attention_heads), optional) — 用于将解码器中注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

• 1 表示头部未被屏蔽，
  
• 0 表示头部被屏蔽。
  

• cross_attn_head_mask (torch.Tensor of shape (decoder_layers, decoder_attention_heads), optional) — 用于将交叉注意力模块中选择的头部置零的掩码。掩码值在 [0, 1] 中选择：

• 1 表示头部未被屏蔽，
  
• 0 表示头部被屏蔽。
  

• encoder_outputs (tuple(tuple(torch.FloatTensor), optional) — 元组包括 last_hidden_state、hidden_states（可选）和 attentions（可选）last_hidden_state 的形状为 (batch_size, sequence_length, hidden_size)（可选）是编码器最后一层的输出的隐藏状态序列。用于解码器的交叉注意力。
  
• past_key_values (tuple(tuple(torch.FloatTensor)), optional, 当传递 use_cache=True 或 config.use_cache=True 时返回) — 长度为 config.n_layers 的 tuple(torch.FloatTensor) 元组，每个元组包含 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量和 2 个额外的形状为 (batch_size, num_heads, encoder_sequence_length, embed_size_per_head) 的张量。
  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见 past_key_values 输入）。
  如果使用了 past_key_values，用户可以选择仅输入最后的 decoder_input_ids（这些没有将其过去的键值状态提供给此模型）的形状为 (batch_size, 1)，而不是所有形状为 (batch_size, sequence_length) 的 decoder_input_ids。
  
• inputs_embeds (torch.FloatTensor of shape (batch_size, sequence_length, hidden_size), optional) — 可选地，可以直接传递嵌入表示，而不是传递 input_ids。如果您想要更多控制权，以便将 input_ids 索引转换为相关向量，而不是模型的内部嵌入查找矩阵，则这很有用。
  
• use_cache (bool, optional) — 如果设置为 True，则返回 past_key_values 键值状态，可用于加速解码（参见 past_key_values）。
  
• output_attentions (bool, optional) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参阅返回张量中的 attentions。
  
• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的 hidden_states。
  
• return_dict (bool, optional) — 是否返回 ModelOutput 而不是普通元组。
  

返回

transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

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

• last_hidden_state（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor）- 模型解码器最后一层的隐藏状态序列。
  如果使用past_key_values，则只输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。
  
• past_key_values（tuple(tuple(torch.FloatTensor))，可选，当传递use_cache=True或config.use_cache=True时返回）- 长度为config.n_layers的tuple(torch.FloatTensor)元组，每个元组有 2 个形状为(batch_size, num_heads, sequence_length, embed_size_per_head)的张量和 2 个额外的形状为(batch_size, num_heads, encoder_sequence_length, embed_size_per_head)的张量。
  包含预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码（参见past_key_values输入）。
  
• decoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）- 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入输出的一个加上每一层的输出）。
  解码器在每一层的输出的隐藏状态以及可选的初始嵌入输出。
  
• decoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。
  解码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。
  
• cross_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。
  解码器的交叉注意力层的注意力权重，在注意力 softmax 之后，用于计算交叉注意力头中的加权平均值。
  
• encoder_last_hidden_state（形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor，可选）- 模型编码器最后一层的隐藏状态序列。
  
• encoder_hidden_states（tuple(torch.FloatTensor)，可选，当传递output_hidden_states=True或config.output_hidden_states=True时返回）- 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则为嵌入输出的一个加上每一层的输出）。
  编码器在每一层的输出的隐藏状态以及可选的初始嵌入输出。
  
• encoder_attentions（tuple(torch.FloatTensor)，可选，当传递output_attentions=True或config.output_attentions=True时返回）- 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。
  编码器的注意力权重，在注意力 softmax 之后，用于计算自注意力头中的加权平均值。
  
• loc（形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor，可选）- 用于将每个时间序列的上下文窗口的值移位，以便为模型提供相同数量级的输入，然后用于将其移位回原始数量级。
  
• scale（形状为(batch_size,)或(batch_size, input_size)的torch.FloatTensor，可选）- 用于将每个时间序列的上下文窗口的缩放值移位，以便为模型提供相同数量级的输入，然后用于重新缩放回原始数量级。
  
• static_features（形状为(batch_size, feature size)的torch.FloatTensor，可选）- 每个时间序列在批处理中的静态特征，在推断时将复制到协变量中。
  

TimeSeriesTransformerForPrediction 的前向方法重写了__call__特殊方法。

虽然前向传递的步骤需要在此函数中定义，但应该在此之后调用Module实例，而不是在此之后调用，因为前者会负责运行预处理和后处理步骤，而后者会默默地忽略它们。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerForPrediction
>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = TimeSeriesTransformerForPrediction.from_pretrained(
...     "huggingface/time-series-transformer-tourism-monthly"
... )
>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )
>>> loss = outputs.loss
>>> loss.backward()
>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )
>>> mean_prediction = outputs.sequences.mean(dim=1)

图模型

Graphormer

原始文本：huggingface.co/docs/transformers/v4.37.2/en/model_doc/graphormer

概述

Graphormer 模型是由 Chengxuan Ying、Tianle Cai、Shengjie Luo、Shuxin Zheng、Guolin Ke、Di He、Yanming Shen 和 Tie-Yan Liu 在Do Transformers Really Perform Bad for Graph Representation?中提出的。这是一个图形变换器模型，经过修改以允许在图形上进行计算，而不是文本序列，通过在预处理和整理过程中生成感兴趣的嵌入和特征，然后使用修改后的注意力。

论文摘要如下：

变压器架构已经成为许多领域的主要选择，如自然语言处理和计算机视觉。然而，与主流 GNN  变体相比，它在流行的图级预测排行榜上并没有取得竞争性表现。因此，变压器如何在图形表示学习中表现良好仍然是一个谜。在本文中，我们通过提出  Graphormer 来解决这个谜团，它建立在标准 Transformer  架构之上，并且在广泛的图形表示学习任务中取得了出色的结果，特别是在最近的 OGB 大规模挑战赛上。我们利用 Transformer  在图中的关键见解是有效地将图的结构信息编码到模型中。为此，我们提出了几种简单而有效的结构编码方法，以帮助 Graphormer  更好地建模图结构化数据。此外，我们数学地刻画了 Graphormer 的表达能力，并展示了通过我们的方式对图的结构信息进行编码，许多流行的  GNN 变体可以被覆盖为 Graphormer 的特殊情况。

该模型由clefourrier贡献。原始代码可以在这里找到。

使用提示

这个模型在大型图上（超过 100 个节点/边）效果不佳，因为会导致内存爆炸。您可以减小批量大小，增加 RAM，或者减小 algos_graphormer.pyx 中的UNREACHABLE_NODE_DISTANCE参数，但很难超过 700 个节点/边。

该模型不使用分词器，而是在训练过程中使用特殊的整理器。

GraphormerConfig

class transformers.GraphormerConfig

<来源>

( num_classes: int = 1 num_atoms: int = 4608 num_edges: int = 1536 num_in_degree: int = 512 num_out_degree: int = 512 num_spatial: int = 512 num_edge_dis: int = 128 multi_hop_max_dist: int = 5 spatial_pos_max: int = 1024 edge_type: str = 'multi_hop' max_nodes: int = 512 share_input_output_embed: bool = False num_hidden_layers: int = 12 embedding_dim: int = 768 ffn_embedding_dim: int = 768 num_attention_heads: int = 32 dropout: float = 0.1 attention_dropout: float = 0.1 activation_dropout: float = 0.1 layerdrop: float = 0.0 encoder_normalize_before: bool = False pre_layernorm: bool = False apply_graphormer_init: bool = False activation_fn: str = 'gelu' embed_scale: float = None freeze_embeddings: bool = False num_trans_layers_to_freeze: int = 0 traceable: bool = False q_noise: float = 0.0 qn_block_size: int = 8 kdim: int = None vdim: int = None bias: bool = True self_attention: bool = True pad_token_id = 0 bos_token_id = 1 eos_token_id = 2 **kwargs )

参数

• num_classes (int, optional, defaults to 1) — 目标类别或标签的数量，设置为 n 用于 n 个任务的二元分类。
  
• num_atoms (int, optional, defaults to 512*9) — 图中节点类型的数量。
  
• num_edges (int, optional, defaults to 512*3) — 图中边的类型数量。
  
• num_in_degree (int, optional, defaults to 512) — 输入图中的入度类型数量。
  
• num_out_degree (int, optional, defaults to 512) — 输入图中的出度类型数量。
  
• num_edge_dis (int, optional, defaults to 128) — 输入图中的边缘 dis 数量。
  
• multi_hop_max_dist (int, optional, defaults to 20) — 两个节点之间多跳边的最大距离。
  
• spatial_pos_max (int, optional, defaults to 1024) — 图注意力偏置矩阵中节点之间的最大距离，在预处理和整理过程中使用。
  
• edge_type (str, optional, defaults to multihop) — 选择的边关系类型。
  
• max_nodes (int, optional, defaults to 512) — 可以解析的输入图中的最大节点数。
  
• share_input_output_embed (bool, optional, defaults to False) — 在编码器和解码器之间共享嵌入层 - 注意，True 未实现。
  
• num_layers (int, optional, defaults to 12) — 层数。
  
• embedding_dim (int, optional, defaults to 768) — 编码器中嵌入层的维度。
  
• ffn_embedding_dim (int, optional, defaults to 768) — 编码器中“中间”（通常称为前馈）层的维度。
  
• num_attention_heads (int, optional, defaults to 32) — 编码器中的注意力头数。
  
• self_attention (bool, optional, defaults to True) — 模型是自注意的（False 未实现）。
  
• activation_function (str or function, optional, defaults to "gelu") — 编码器和池化器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"、"relu"、"silu"和"gelu_new"。
  
• dropout (float, optional, defaults to 0.1) — 嵌入层、编码器和池化器中所有全连接层的 dropout 概率。
  
• attention_dropout (float, optional, defaults to 0.1) — 注意力权重的 dropout 概率。
  
• activation_dropout (float, optional, defaults to 0.1) — 线性变换器层激活的 dropout 概率。
  
• layerdrop (float, optional, defaults to 0.0) — 编码器的 LayerDrop 概率。有关更多详细信息，请参阅 LayerDrop paper)。
  
• bias (bool, optional, defaults to True) — 在注意力模块中使用偏置 - 目前不支持。
  
• embed_scale(float, optional, defaults to None) — 节点嵌入的缩放因子。
  
• num_trans_layers_to_freeze (int, optional, defaults to 0) — 要冻结的 Transformer 层数。
  
• encoder_normalize_before (bool, optional, defaults to False) — 在对图进行编码之前对特征进行归一化。
  
• pre_layernorm (bool, optional, defaults to False) — 在自注意力和前馈网络之前应用层归一化。如果没有这个，将使用后层归一化。
  
• apply_graphormer_init (bool, optional, defaults to False) — 在训练之前对模型应用自定义的 graphormer 初始化。
  
• freeze_embeddings (bool, optional, defaults to False) — 冻结嵌入层，或者与模型一起训练。
  
• encoder_normalize_before (bool, optional, defaults to False) — 在每个编码器块之前应用层归一化。
  
• q_noise (float, optional, defaults to 0.0) — 量化噪声的量（参见“使用量化噪声进行极端模型压缩”）。 （更多细节，请参阅 fairseq 关于 quant_noise 的文档）。
  
• qn_block_size (int, optional, defaults to 8) — 用于后续 iPQ 量化的块的大小（参见 q_noise）。
  
• kdim (int, optional, defaults to None) — 注意力中键的维度，如果与其他值不同。
  
• vdim (int, optional, defaults to None) — 注意力中值的维度，如果与其他值不同。
  
• use_cache (bool, optional, defaults to True) — 模型是否应返回最后的键/值注意力（并非所有模型都使用）。
  
• traceable (bool, optional, defaults to False) — 将编码器的 inner_state 的返回值更改为堆叠的张量。
  示例 —
  

这是一个配置类，用于存储~GraphormerModel 的配置。它用于根据指定的参数实例化一个 Graphormer 模型，定义模型架构。使用默认值实例化配置将产生类似于 Graphormer graphormer-base-pcqm4mv1架构的配置。

配置对象继承自 PretrainedConfig，可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

GraphormerModel

class transformers.GraphormerModel

< source >

( config: GraphormerConfig )

Graphormer 模型是一个图编码器模型。

它将一个图转换为其表示。如果您想将模型用于下游分类任务，请改用  GraphormerForGraphClassification。对于任何其他下游任务，请随意添加一个新类，或将此模型与您选择的下游模型结合，按照  GraphormerForGraphClassification 中的示例进行操作。

forward

< source >

( input_nodes: LongTensor input_edges: LongTensor attn_bias: Tensor in_degree: LongTensor out_degree: LongTensor spatial_pos: LongTensor attn_edge_type: LongTensor perturb: Optional = None masked_tokens: None = None return_dict: Optional = None **unused )

GraphormerForGraphClassification

class transformers.GraphormerForGraphClassification

< source >

( config: GraphormerConfig )

这个模型可以用于图级分类或回归任务。

可以在以下链接上进行训练

• 回归（通过将 config.num_classes 设置为 1）；每个图应有一个浮点类型标签
  
• 单任务分类（通过将 config.num_classes 设置为类别数）；每个图应有一个整数标签
  
• 二元多任务分类（通过将 config.num_classes 设置为标签数）；每个图应有一个整数标签列表。
  

forward

< source >

( input_nodes: LongTensor input_edges: LongTensor attn_bias: Tensor in_degree: LongTensor out_degree: LongTensor spatial_pos: LongTensor attn_edge_type: LongTensor labels: Optional = None return_dict: Optional = None **unused )

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