Transformers 4.37 中文文档（九十八）

原文：huggingface.co/docs/transformers

PatchTSMixer

原文链接：huggingface.co/docs/transformers/v4.37.2/en/model_doc/patchtsmixer

概述

PatchTSMixer 模型是由 Vijay Ekambaram、Arindam Jati、Nam Nguyen、Phanwadee Sinthong 和 Jayant Kalagnanam 在TSMixer: Lightweight MLP-Mixer Model for Multivariate Time Series Forecasting中提出的。

PatchTSMixer 是基于 MLP-Mixer 架构的轻量级时间序列建模方法。在这个 HuggingFace 实现中，我们提供了 PatchTSMixer 的功能，以轻松促进跨补丁、通道和隐藏特征的轻量级混合，以实现有效的多变量时间序列建模。它还支持各种注意机制，从简单的门控注意力到更复杂的自注意力块，可以根据需要进行定制。该模型可以进行预训练，随后用于各种下游任务，如预测、分类和回归。

论文摘要如下：

TSMixer 是一种轻量级的神经架构，专门由多层感知器（MLP）模块组成，设计用于修补时间序列上的多变量预测和表示学习。我们的模型受到 MLP-Mixer 模型在计算机视觉中的成功启发。我们展示了将视觉 MLP-Mixer 调整为时间序列时涉及的挑战，并引入了经验验证的组件来提高准确性。这包括一种新颖的设计范式，将在线协调头附加到 MLP-Mixer 骨干上，以明确地建模时间序列的属性，如层次结构和通道相关性。我们还提出了一种混合通道建模方法，以有效处理嘈杂的通道交互和跨多样数据集的泛化，这是现有补丁通道混合方法中的一个常见挑战。此外，在骨干中引入了一个简单的门控注意机制，以优先处理重要特征。通过整合这些轻量级组件，我们显著增强了简单 MLP 结构的学习能力，优于具有最小计算使用的复杂 Transformer 模型。此外，TSMixer 的模块化设计使其与监督和掩蔽自监督学习方法兼容，使其成为时间序列基础模型的有前途的构建模块。TSMixer 在预测方面的表现明显优于最先进的 MLP 和 Transformer 模型，差距为 8-60%。它还在内存和运行时间上优于最新的强大基准 Patch-Transformer 模型（提高了 1-2%），同时显著减少了内存和运行时间（2-3 倍）。

该模型由ajati, vijaye12, gsinthong, namctin, wmgifford, kashif贡献。

示例用法

from transformers import PatchTSMixerConfig, PatchTSMixerForPrediction
from transformers import Trainer, TrainingArguments,

config = PatchTSMixerConfig(context_length = 512, prediction_length = 96)
model = PatchTSMixerForPrediction(config)
trainer = Trainer(model=model, args=training_args, 
            train_dataset=train_dataset,
            eval_dataset=valid_dataset)
trainer.train()
results = trainer.evaluate(test_dataset)

使用提示

该模型还可用于时间序列分类和时间序列回归。请查看相应的 PatchTSMixerForTimeSeriesClassification 和 PatchTSMixerForRegression 类。

PatchTSMixerConfig

class transformers.PatchTSMixerConfig

<来源>

( context_length: int = 32 patch_len: int = 8 num_input_channels: int = 1 patch_stride: int = 8 num_parallel_samples: int = 100 d_model: int = 8 expansion_factor: int = 2 num_layers: int = 3 dropout: float = 0.2 mode: str = 'common_channel' gated_attn: bool = True norm_mlp: str = 'LayerNorm' self_attn: bool = False self_attn_heads: int = 1 use_positional_encoding: bool = False positional_encoding_type: str = 'sincos' scaling: Union = 'std' loss: str = 'mse' init_std: float = 0.02 post_init: bool = False norm_eps: float = 1e-05 mask_type: str = 'random' random_mask_ratio: float = 0.5 num_forecast_mask_patches: Union = [2] mask_value: int = 0 masked_loss: bool = True channel_consistent_masking: bool = True unmasked_channel_indices: Optional = None head_dropout: float = 0.2 distribution_output: str = 'student_t' prediction_length: int = 16 prediction_channel_indices: list = None num_targets: int = 3 output_range: list = None head_aggregation: str = 'max_pool' **kwargs )

参数

• context_length (int, 可选, 默认为 32) — 输入序列的上下文/历史长度。
• patch_len (int, 可选, 默认为 8) — 输入序列的补丁长度。
• num_input_channels (int, 可选, 默认为 1) — 输入变量的数量。对于单变量，将其设置为 1。
• patch_stride (int, optional, 默认为 8) — 确定两个连续补丁之间的重叠。如果我们想要非重叠的补丁，则将其设置为 patch_length（或更大）。
• num_parallel_samples (int, optional, 默认为 100) — 用于概率预测并行生成的样本数量。
• d_model (int, optional, 默认为 8) — 模型的隐藏维度。建议将其设置为 patch_length 的倍数（即 patch_len 的 2-5 倍）。较大的值表示更复杂的模型。
• expansion_factor (int, optional, 默认为 2) — 在 MLP 内部使用的扩展因子。推荐范围为 2-5。较大的值表示更复杂的模型。
• num_layers (int, optional, 默认为 3) — 要使用的层数。推荐范围为 3-15。较大的值表示更复杂的模型。
• dropout (float, optional, 默认为 0.2) — PatchTSMixer主干的丢失概率。推荐范围为 0.2-0.7
• mode (str, optional, 默认为"common_channel") — Mixer 模式。确定如何处理通道。允许的值："common_channel"、“mix_channel”。在"common_channel"模式中，我们遵循独立于通道的建模，没有显式的通道混合。通道混合通过跨通道共享权重以隐式方式发生。（首选第一种方法）在“mix_channel”模式中，我们遇到显式的通道混合以及补丁和特征混合。（当通道相关性对模型非常重要时，首选方法）
• gated_attn (bool, optional, 默认为True) — 启用门控注意力。
• norm_mlp (str, optional, 默认为"LayerNorm") — 归一化层（BatchNorm 或 LayerNorm）。
• self_attn (bool, optional, 默认为False) — 在补丁之间启用小型自注意力。当 Vanilla PatchTSMixer 的门控注意力的输出不理想时，可以启用此功能。启用此功能会导致显式的成对注意力和跨补丁建模。
• self_attn_heads (int, optional, 默认为 1) — 自注意力头的数量。仅当self_attn设置为True时才有效。
• use_positional_encoding (bool, optional, 默认为False) — 启用小型自注意力层的位置嵌入使用。仅当self_attn设置为True时才有效。
• positional_encoding_type (str, optional, 默认为"sincos") — 位置编码。支持选项"random"和"sincos"。仅当use_positional_encoding设置为True时才有效。
• scaling (string或bool, optional, 默认为"std") — 是否通过“mean”缩放器、"std"缩放器或如果为None则不缩放输入目标。如果为True，则缩放器设置为“mean”。
• loss (string, optional, 默认为"mse") — 与distribution_output头对应的模型的损失函数。对于参数分布，它是负对数似然（“nll”），对于点估计，它是均方误差"mse"。
• init_std (float, optional, 默认为 0.02) — 截断正态权重初始化分布的标准差。
• post_init (bool, optional, 默认为False) — 是否使用transformers库中的自定义权重初始化，或者使用PyTorch中的默认初始化。将其设置为False执行PyTorch权重初始化。
• norm_eps (float, optional, 默认为 1e-05) — 用于归一化的分母的数值稳定性的值。
• mask_type (str, optional, 默认为"random") — 用于掩码预训练模式的掩码类型。允许的值为"random"、“forecast”。在随机掩码中，点被随机掩盖。在预测掩码中，点被朝向末尾掩盖。
• random_mask_ratio (float, optional, 默认为 0.5) — 当mask_type为random时使用的掩码比例。较高的值表示更多的掩码。
• num_forecast_mask_patches (int or list, optional, defaults to [2]) — 每个批次样本末尾要屏蔽的补丁数量。如果是整数，则批次中的所有样本将具有相同数量的屏蔽补丁。如果是列表，则批次中的样本将随机屏蔽列表中定义的数字。此参数仅用于预测预训练。
• mask_value (float, optional, defaults to 0.0) — 要使用的屏蔽值。
• masked_loss (bool, optional, defaults to True) — 是否仅在屏蔽部分计算预训练损失，还是在整个输出上计算。
• channel_consistent_masking (bool, optional, defaults to True) — 当为 True 时，屏蔽将在时间序列的所有通道上相同。否则，屏蔽位置将在通道之间变化。
• unmasked_channel_indices (list, optional) — 预训练期间未屏蔽的通道。
• head_dropout (float, optional, defaults to 0.2) — PatchTSMixer 头部的 dropout 概率。
• distribution_output (string, optional, defaults to "student_t") — 当损失为“nll”时，模型的分布发射头。可以是"student_t"、“normal”或“negative_binomial”。
• prediction_length (int, optional, defaults to 16) — 用于预测任务的预测时间步数。也称为预测视野。
• prediction_channel_indices (list, optional) — 要预测的通道索引列表。如果为 None，则预测所有通道。目标数据预期具有所有通道，我们在损失计算之前明确过滤预测和目标中的通道。
• num_targets (int, optional, defaults to 3) — 回归任务的目标数量（回归变量的维度）。
• output_range (list, optional) — 用于限制回归任务的输出范围。默认为 None。
• head_aggregation (str, optional, defaults to "max_pool") — 用于分类或回归任务的聚合模式。允许的值为 None、“use_last”、“max_pool”、“avg_pool”。

这是一个配置类，用于存储 PatchTSMixerModel 的配置。根据指定的参数实例化一个 PatchTSMixer 模型，定义模型架构。使用默认值实例化配置将产生与 PatchTSMixer ibm/patchtsmixer-etth1-pretrain 架构类似的配置。

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

示例：

>>> from transformers import PatchTSMixerConfig, PatchTSMixerModel

>>> # Initializing a default PatchTSMixer configuration
>>> configuration = PatchTSMixerConfig()

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = PatchTSMixerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PatchTSMixerModel

class transformers.PatchTSMixerModel

< source >

( config: PatchTSMixerConfig mask_input: bool = False )

参数

• config (PatchTSMixerConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，只加载配置。查看 from_pretrained() 方法以加载模型权重。
• mask_input (bool, optional, defaults to False) — 如果为 True，则启用屏蔽。否则为 False。

用于时间序列预测的 PatchTSMixer 模型。

此模型继承自 PreTrainedModel。检查超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

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

forward

<来源>

( past_values: Tensor observed_mask: Optional = None output_hidden_states: Optional = False return_dict: Optional = None ) → export const metadata = 'undefined';transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerModelOutput or tuple(torch.FloatTensor)

参数

• past_values (torch.FloatTensor，形状为(batch_size, seq_length, num_input_channels)) — 时间序列的上下文值。对于预训练任务，这表示要预测掩码部分的输入时间序列。对于预测任务，这表示历史/过去的时间序列值。同样，对于分类或回归任务，它表示时间序列的适当上下文值。 对于单变量时间序列，num_input_channels维度应为 1。对于多变量时间序列，它大于 1。
• output_hidden_states (bool，可选) — 是否返回所有层的隐藏状态。
• return_dict (bool, 可选) — 是否返回一个 ModelOutput 而不是一个普通元组。
• observed_mask (torch.FloatTensor，形状为(batch_size, sequence_length, num_input_channels)，可选) — 布尔蒙版，指示哪些past_values是观察到的，哪些是缺失的。蒙版值选择在[0, 1]之间：
  • 1 表示observed的值，
  • 0 表示missing的值（即被零替换的 NaN）。

返回

transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerModelOutput或tuple(torch.FloatTensor)

一个transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerModelOutput或一个torch.FloatTensor元组（如果传递了return_dict=False或当config.return_dict=False时）包含根据配置（PatchTSMixerConfig）和输入的各种元素。

• last_hidden_state (torch.FloatTensor，形状为(batch_size, num_channels, num_patches, d_model)) — 模型最后一层的隐藏状态。
• hidden_states (tuple(torch.FloatTensor)，可选) — 模型在每一层输出的隐藏状态。
• patch_input (torch.FloatTensor，形状为(batch_size, num_channels, num_patches, patch_length)) — 输入到模型的补丁化数据。
• mask: (torch.FloatTensor，形状为(batch_size, num_channels, num_patches)，可选) — 布尔张量，指示掩码补丁中的 True 和其他地方的 False。
• loc: (torch.FloatTensor，形状为(batch_size, 1, num_channels)，可选) — 给出每个通道上下文窗口的均值。如果启用了 revin，则用于模型外的 revin 反归一化。
• scale: (torch.FloatTensor，形状为(batch_size, 1, num_channels)，可选) — 给出每个通道上下文窗口的标准差。如果启用了 revin，则用于模型外的 revin 反归一化。

PatchTSMixerModel 的前向方法，覆盖了__call__特殊方法。

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

PatchTSMixerForPrediction

class transformers.PatchTSMixerForPrediction

<来源>

( config: PatchTSMixerConfig )

参数

• config (PatchTSMixerConfig, required) — 配置。

用于预测应用的 PatchTSMixer。

forward

< source >

( past_values: Tensor observed_mask: Optional = None future_values: Optional = None output_hidden_states: Optional = False return_loss: bool = True return_dict: Optional = None ) → export const metadata = 'undefined';transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForPredictionOutput or tuple(torch.FloatTensor)

参数

• past_values (torch.FloatTensor of shape (batch_size, seq_length, num_input_channels)) — 时间序列的上下文值。对于预训练任务，这表示用于预测被屏蔽部分的输入时间序列。对于预测任务，这表示历史/过去的时间序列值。同样，对于分类或回归任务，它表示时间序列的适当上下文值。 对于单变量时间序列，num_input_channels 维度应为 1。对于多变量时间序列，它大于 1。
• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态。
• return_dict (bool, optional) — 是否返回 ModelOutput 而不是普通元组。
• observed_mask (torch.FloatTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码，指示哪些 past_values 是观察到的，哪些是缺失的。掩码值选在 [0, 1]：
  • 对于 observed 的值为 1，
  • 对于 missing 的值为 0（即被零替换的 NaN）。
• future_values (torch.FloatTensor of shape (batch_size, target_len, num_input_channels) 用于预测， — (batch_size, num_targets) 用于回归，或 (batch_size,) 用于分类， optional): 时间序列的目标值，作为模型的标签。future_values 是训练期间 Transformer 需要的，以学习在给定 past_values 时输出。请注意，这对于预训练任务并非必需。 对于预测任务，形状为 (batch_size, target_len, num_input_channels)。即使我们想通过在 prediction_channel_indices 参数中设置索引来仅预测特定通道，也要传递带有所有通道的目标数据，因为在损失计算之前，预测和目标的通道过滤将手动应用。
• return_loss (bool, optional) — 是否在 forward 调用中返回损失。

返回

transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForPredictionOutput 或 tuple(torch.FloatTensor)

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

• prediction_outputs (torch.FloatTensor of shape (batch_size, prediction_length, num_input_channels)) — 预测头部的预测输出。
• last_hidden_state (torch.FloatTensor of shape (batch_size, num_input_channels, num_patches, d_model)) — 通过头部之前的主干嵌入。
• hidden_states (tuple(torch.FloatTensor), optional) — 模型在每一层输出处的隐藏状态，加上可选的初始嵌入输出。
• loss (optional, 当提供 y 时返回，形状为 () 的 torch.FloatTensor) — 总损失。
• loc (torch.FloatTensor, optional of shape (batch_size, 1, num_input_channels)) — 输入均值
• scale (torch.FloatTensor, optional of shape (batch_size, 1, num_input_channels)) — 输入标准差

PatchTSMixerForPrediction 的前向方法，覆盖了 __call__ 特殊方法。

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

PatchTSMixerForTimeSeriesClassification

class transformers.PatchTSMixerForTimeSeriesClassification

<来源>

( config: PatchTSMixerConfig )

参数

• config (PatchTSMixerConfig, 必需) — 配置。

用于分类应用的PatchTSMixer。

forward

<来源>

( past_values: Tensor future_values: Tensor = None output_hidden_states: Optional = False return_loss: bool = True return_dict: Optional = None ) → export const metadata = 'undefined';transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForTimeSeriesClassificationOutput or tuple(torch.FloatTensor)

参数

• past_values (torch.FloatTensor of shape (batch_size, seq_length, num_input_channels)) — 时间序列的上下文值。对于预训练任务，这表示要预测掩码部分的输入时间序列。对于预测任务，这表示历史/过去的时间序列值。类似地，对于分类或回归任务，它表示时间序列的适当上下文值。 对于单变量时间序列，num_input_channels维度应为 1。对于多变量时间序列，它大于 1。
• output_hidden_states (bool, 可选) — 是否返回所有层的隐藏状态。
• return_dict (bool, 可选) — 是否返回一个 ModelOutput 而不是一个普通元组。
• future_values (torch.FloatTensor of shape (batch_size, target_len, num_input_channels) 用于预测，— (batch_size, num_targets) 用于回归，或 (batch_size,) 用于分类，可选): 时间序列的目标值，作为模型的标签。future_values是 Transformer 在训练期间需要的，以便学习如何输出，给定past_values。请注意，这对于预训练任务并不是必需的。 对于预测任务，形状为(batch_size, target_len, num_input_channels)。即使我们只想通过在prediction_channel_indices参数中设置索引来预测特定通道，也要传递带有所有通道的目标数据，因为在计算损失之前，预测和目标的通道过滤将手动应用。 对于分类任务，形状为(batch_size,)。 对于回归任务，形状为(batch_size, num_targets)。
• return_loss (bool, 可选) — 是否在forward调用中返回损失。

返回

transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForTimeSeriesClassificationOutput 或 tuple(torch.FloatTensor)

一个transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForTimeSeriesClassificationOutput或一个torch.FloatTensor元组（如果传递了return_dict=False或当config.return_dict=False时）包含根据配置（PatchTSMixerConfig）和输入的各种元素。

• prediction_outputs (torch.FloatTensor of shape (batch_size, num_labels)) — 分类头部的预测输出。
• last_hidden_state (torch.FloatTensor of shape (batch_size, num_input_channels, num_patches, d_model)) — 通过头部之前的主干嵌入。
• hidden_states (tuple(torch.FloatTensor), 可选) — 模型在每一层输出的隐藏状态加上可选的初始嵌入输出。
• loss (可选, 当提供y时返回, torch.FloatTensor of shape ()) — 总损失。

PatchTSMixerForTimeSeriesClassification 的前向方法，覆盖了__call__特殊方法。

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

PatchTSMixerForPretraining

class transformers.PatchTSMixerForPretraining

<来源>

( config: PatchTSMixerConfig )

参数

• config（PatchTSMixerConfig，必需）— 配置。

PatchTSMixer用于掩码预训练。

forward

<来源>

( past_values: Tensor observed_mask: Optional = None output_hidden_states: Optional = False return_loss: bool = True return_dict: Optional = None ) → export const metadata = 'undefined';transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForPreTrainingOutput or tuple(torch.FloatTensor)

参数

• past_values（形状为(batch_size, seq_length, num_input_channels)的torch.FloatTensor）— 时间序列的上下文值。对于预训练任务，这表示要预测掩码部分的输入时间序列。对于预测任务，这表示历史/过去的时间序列值。同样，对于分类或回归任务，它表示时间序列的适当上下文值。 对于单变量时间序列，num_input_channels维度应为 1。对于多变量时间序列，它大于 1。
• output_hidden_states（bool，可选）— 是否返回所有层的隐藏状态。
• return_dict（bool，可选）— 是否返回 ModelOutput 而不是普通元组。
• observed_mask（形状为(batch_size, sequence_length, num_input_channels)的torch.FloatTensor，可选）— 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：
  • 1 表示observed的值，
  • 0 表示missing的值（即被零替换的 NaN）。
• return_loss（bool，可选）— 是否在forward调用中返回损失。

返回

transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForPreTrainingOutput或tuple(torch.FloatTensor)

一个transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForPreTrainingOutput或一个torch.FloatTensor元组（如果传递了return_dict=False或当config.return_dict=False时）包含各种元素，取决于配置（PatchTSMixerConfig）和输入。

• prediction_outputs（形状为(batch_size, num_input_channels, num_patches, patch_length)的torch.FloatTensor）— 来自预训练头部的预测输出。
• hidden_states（tuple(torch.FloatTensor)，可选）— 模型在每一层输出的隐藏状态。
• last_hidden_state（形状为(batch_size, num_input_channels, num_patches, d_model)的torch.FloatTensor）— 通过头部之前的主干嵌入。
• loss（可选，在提供y时返回，形状为()的torch.FloatTensor）— 总损失

PatchTSMixerForPretraining 的前向方法，覆盖了__call__特殊方法。

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

PatchTSMixerForRegression

class transformers.PatchTSMixerForRegression

<来源>

( config: PatchTSMixerConfig )

参数

• config（PatchTSMixerConfig，必需）— 配置。

PatchTSMixer用于回归应用。

forward

<来源>

( past_values: Tensor future_values: Tensor = None output_hidden_states: Optional = False return_loss: bool = True return_dict: Optional = None ) → export const metadata = 'undefined';transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForRegressionOutput or tuple(torch.FloatTensor)

参数

• past_values（形状为(batch_size, seq_length, num_input_channels)的torch.FloatTensor）：时间序列的上下文值。对于预训练任务，这表示要预测掩码部分的输入时间序列。对于预测任务，这表示历史/过去的时间序列值。同样，对于分类或回归任务，它表示时间序列的适当上下文值。 对于单变量时间序列，num_input_channels维度应为 1。对于多变量时间序列，它大于 1。
• output_hidden_states（bool，可选）：是否返回所有层的隐藏状态。
• return_dict（bool，可选）：是否返回一个 ModelOutput 而不是一个普通的元组。
• future_values（形状为(batch_size, target_len, num_input_channels)的torch.FloatTensor用于预测，形状为(batch_size, num_targets)用于回归，或形状为(batch_size,)用于分类，可选）：时间序列的目标值，作为模型的标签。future_values是 Transformer 在训练期间需要的，以便学习在给定past_values时输出。请注意，这对于预训练任务是不需要的。 对于一个预测任务，形状应为(batch_size, target_len, num_input_channels)。即使我们只想通过在prediction_channel_indices参数中设置索引来预测特定通道，也要传递带有所有通道的目标数据，因为在损失计算之前，预测和目标的通道过滤将手动应用。 对于分类任务，形状为(batch_size,)。 对于回归任务，形状为(batch_size, num_targets)。
• return_loss（bool，可选）：是否在forward调用中返回损失。

返回值

transformers.models.patchtsmixer.modeling_patchtsmixer.PatchTSMixerForRegressionOutput或tuple(torch.FloatTensor)

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

• prediction_outputs（形状为(batch_size, num_targets)的torch.FloatTensor）：回归头部的预测输出。
• last_hidden_state（形状为(batch_size, num_input_channels, num_patches, d_model)的torch.FloatTensor）：通过头部之前的主干嵌入。
• hidden_states（tuple(torch.FloatTensor)，可选）：模型在每一层输出的隐藏状态以及可选的初始嵌入输出。
• loss（可选，在提供y时返回，形状为()的torch.FloatTensor）：总损失。

PatchTSMixerForRegression 的前向方法，覆盖了__call__特殊方法。

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

PatchTST

原文链接：huggingface.co/docs/transformers/v4.37.2/en/model_doc/patchtst

概述

PatchTST 模型由 Yuqi Nie、Nam H. Nguyen、Phanwadee Sinthong 和 Jayant Kalagnanam 在A Time Series is Worth 64 Words: Long-term Forecasting with Transformers中提出。

在高层次上，该模型将时间序列向量化为给定大小的补丁，并通过一个 Transformer 对生成的向量序列进行编码，然后通过适当的头部输出预测长度的预测。该模型如下图所示：

model

论文摘要如下：

我们提出了一种用于多变量时间序列预测和自监督表示学习的基于 Transformer 的模型的高效设计。它基于两个关键组件：(i) 将时间序列分割为子系列级别的补丁，这些补丁作为输入标记提供给 Transformer；(ii) 通道独立性，其中每个通道包含一个单变量时间序列，共享相同的嵌入和 Transformer 权重。补丁设计自然具有三重好处：在嵌入中保留局部语义信息；在给定相同回顾窗口的情况下，注意力图的计算和内存使用量呈二次减少；模型可以关注更长的历史。我们的通道独立补丁时间序列 Transformer（PatchTST）可以显著提高长期预测的准确性，与 SOTA 基于 Transformer 的模型相比。我们还将我们的模型应用于自监督预训练任务，并获得出色的微调性能，优于大型数据集上的监督训练。将一个数据集上的掩码预训练表示转移到其他数据集也会产生 SOTA 的预测准确性。

该模型由namctin、gsinthong、diepi、vijaye12、wmgifford和kashif贡献。原始代码可在此处找到。

使用提示

该模型还可用于时间序列分类和时间序列回归。请参阅相应的 PatchTSTForClassification 和 PatchTSTForRegression 类。

PatchTSTConfig

class transformers.PatchTSTConfig

<来源>

( num_input_channels: int = 1 context_length: int = 32 distribution_output: str = 'student_t' loss: str = 'mse' patch_length: int = 1 patch_stride: int = 1 num_hidden_layers: int = 3 d_model: int = 128 num_attention_heads: int = 4 share_embedding: bool = True channel_attention: bool = False ffn_dim: int = 512 norm_type: str = 'batchnorm' norm_eps: float = 1e-05 attention_dropout: float = 0.0 dropout: float = 0.0 positional_dropout: float = 0.0 path_dropout: float = 0.0 ff_dropout: float = 0.0 bias: bool = True activation_function: str = 'gelu' pre_norm: bool = True positional_encoding_type: str = 'sincos' use_cls_token: bool = False init_std: float = 0.02 share_projection: bool = True scaling: Union = 'std' do_mask_input: Optional = None mask_type: str = 'random' random_mask_ratio: float = 0.5 num_forecast_mask_patches: Union = [2] channel_consistent_masking: Optional = False unmasked_channel_indices: Optional = None mask_value: int = 0 pooling_type: str = 'mean' head_dropout: float = 0.0 prediction_length: int = 24 num_targets: int = 1 output_range: Optional = None num_parallel_samples: int = 100 **kwargs )

参数

• num_input_channels (int, optional, 默认为 1) — 目标变量的大小，默认情况下为单变量目标的 1。在多变量目标的情况下会大于 1。
• context_length (int, optional, 默认为 32) — 输入序列的上下文长度。
• distribution_output (str, optional, 默认为"student_t") — 当损失为“nll”时，模型的分布发射头。可以是"student_t"、“normal”或“negative_binomial”之一。
• loss (str, optional, 默认为"mse") — 与distribution_output头部对应的模型损失函数。对于参数分布，为负对数似然（“nll”），对于点估计，为均方误差"mse"。
• patch_length (int, optional, 默认为 1) — 定义补丁化过程的补丁长度。
• patch_stride (int, optional, 默认为 1) — 定义补丁化过程的步幅。
• num_hidden_layers (int, optional, 默认为 3) — 隐藏层的数量。
• d_model (int, optional, 默认为 128) — Transformer 层的维度。
• num_attention_heads (int, optional, 默认为 4) — Transformer 编码器中每个注意力层的注意力头数。
• share_embedding (bool, optional, 默认为True) — 在所有通道之间共享输入嵌入。
• channel_attention (bool, optional, 默认为False) — 激活 Transformer 中的通道注意力块，允许通道相互关注。
• ffn_dim (int, optional, 默认为 512) — Transformer 编码器中“中间”（通常称为前馈）层的维度。
• norm_type (str , optional, 默认为"batchnorm") — 每个 Transformer 层的归一化。可以是"batchnorm"或"layernorm"。
• norm_eps (float, optional, 默认为 1e-05) — 添加到归一化分母以提高数值稳定性的值。
• attention_dropout (float, optional, 默认为 0.0) — 注意力概率的 dropout 概率。
• dropout (float, optional, 默认为 0.0) — Transformer 中所有全连接层的 dropout 概率。
• positional_dropout (float, optional, 默认为 0.0) — 位置嵌入层中的 dropout 概率。
• path_dropout (float, optional, 默认为 0.0) — 残差块中的路径 dropout。
• ff_dropout (float, optional, 默认为 0.0) — 在前馈网络的两层之间使用的 dropout 概率。
• bias (bool, optional, 默认为True) — 是否在前馈网络中添加偏置。
• activation_function (str, optional, 默认为"gelu") — Transformer 中的非线性激活函数（字符串）。支持"gelu"和"relu"。
• pre_norm (bool, optional, 默认为True) — 如果pre_norm设置为True，则在自注意力之前应用归一化。否则，在残差块之后应用归一化。
• positional_encoding_type (str, optional, 默认为"sincos") — 位置编码。支持选项"random"和"sincos"。
• use_cls_token (bool, optional, 默认为False) — 是否使用 cls 标记。
• init_std (float, optional, 默认为 0.02) — 截断正态权重初始化分布的标准差。
• share_projection (bool, optional, 默认为True) — 在预测头部中跨不同通道共享投影层。
• scaling (Union, optional, 默认为"std") — 是否通过“mean”缩放器、"std"缩放器或如果为None则不缩放来缩放输入目标。如果为True，则缩放器设置为“mean”。
• do_mask_input (bool, optional) — 在预训练期间应用屏蔽。
• mask_type (str, optional, 默认为"random") — 屏蔽类型。目前仅支持"random"和"forecast"。
• random_mask_ratio (float, optional, 默认为 0.5) — 用于在随机预训练期间屏蔽输入数据的屏蔽比例。
• num_forecast_mask_patches (int或list, optional, 默认为[2]) — 每个批次样本末尾要屏蔽的补丁数量。如果是整数，则批次中的所有样本将具有相同数量的屏蔽补丁。如果是列表，则批次中的样本将被随机屏蔽，屏蔽数量由列表中定义。此参数仅用于预测预训练。
• channel_consistent_masking (bool, optional, 默认为False) — 如果通道一致屏蔽为 True，则所有通道将具有相同的屏蔽模式。
• unmasked_channel_indices (list, optional) — 未在预训练期间屏蔽的通道索引。列表中的值为 1 到num_input_channels之间的数字。
• mask_value (int, optional, 默认为 0) — 屏蔽补丁中的值将被mask_value填充。
• pooling_type (str, optional, 默认为"mean") — 嵌入的池化。支持"mean"、"max"和None。
• head_dropout (float, optional, 默认为 0.0) — 头部的 dropout 概率。
• prediction_length（int，可选，默认为 24）— 模型将输出的预测时间范围。
• num_targets（int，可选，默认为 1）— 回归和分类任务的目标数量。对于分类，它是类的数量。
• output_range（list，可选）— 回归任务的输出范围。可以设置输出值的范围以强制模型生成在范围内的值。
• num_parallel_samples（int，可选，默认为 100）— 并行生成的样本数，用于概率预测。

这是配置类，用于存储 PatchTSTModel 的配置。它用于根据指定的参数实例化 PatchTST 模型，定义模型架构。ibm/patchtst 架构。

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

>>> from transformers import PatchTSTConfig, PatchTSTModel

>>> # Initializing an PatchTST configuration with 12 time steps for prediction
>>> configuration = PatchTSTConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = PatchTSTModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

PatchTSTModel

class transformers.PatchTSTModel

< source >

( config: PatchTSTConfig )

参数

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

裸 PatchTST 模型输出原始隐藏状态，没有特定的头。该模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

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

forward

< source >

( past_values: Tensor past_observed_mask: Optional = None future_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values（形状为 (bs, sequence_length, num_input_channels) 的 torch.Tensor，必需）— 输入序列到模型
• past_observed_mask（形状为 (batch_size, sequence_length, num_input_channels) 的 torch.BoolTensor，可选）— 布尔掩码，指示哪些 past_values 被观察到，哪些是缺失的。掩码值选在 [0, 1]：
  • 1 表示 观察到 的值，
  • 0 表示 缺失 的值（即被零替换的 NaN）。
• future_values（形状为 (batch_size, prediction_length, num_input_channels) 的 torch.BoolTensor，可选）— 与 past_values 相关的未来目标值
• output_hidden_states（bool，可选）— 是否返回所有层的隐藏状态
• output_attentions（bool，可选）— 是否返回所有层的输出注意力
• return_dict（bool，可选）— 是否返回 ModelOutput 而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = PatchTSTModel.from_pretrained("namctin/patchtst_etth1_pretrain")

>>> # during training, one provides both past and future values
>>> outputs = model(
...     past_values=batch["past_values"],
...     future_values=batch["future_values"],
... )

>>> last_hidden_state = outputs.last_hidden_state

PatchTSTForPrediction

class transformers.PatchTSTForPrediction

< source >

( config: PatchTSTConfig )

参数

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

用于预测的 PatchTST 模型。该模型继承自 PreTrainedModel。查看超类文档，了解库实现的所有模型的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

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

forward

<来源>

( past_values: Tensor past_observed_mask: Optional = None future_values: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor，形状为(bs, sequence_length, num_input_channels)，required) — 输入序列到模型
• past_observed_mask (torch.BoolTensor，形状为(batch_size, sequence_length, num_input_channels)，optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]范围内：
  • 1 表示观察到的值，
  • 0 表示缺失的值（即用零替换的 NaN）。
• future_values (torch.Tensor，形状为(bs, forecast_len, num_input_channels)，optional) — 与past_values相关联的未来目标值
• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
• output_attentions (bool, optional) — 是否返回所有层的注意力输出
• return_dict (bool, optional) — 是否返回ModelOutput而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTConfig, PatchTSTForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # Prediction task with 7 input channels and prediction length is 96
>>> model = PatchTSTForPrediction.from_pretrained("namctin/patchtst_etth1_forecast")

>>> # during training, one provides both past and future values
>>> outputs = model(
...     past_values=batch["past_values"],
...     future_values=batch["future_values"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values, the model outputs future values
>>> outputs = model(past_values=batch["past_values"])
>>> prediction_outputs = outputs.prediction_outputs

PatchTSTForClassification

class transformers.PatchTSTForClassification

<来源>

( config: PatchTSTConfig )

参数

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

用于分类的 PatchTST 模型。该模型继承自 PreTrainedModel。查看超类文档，了解库实现的所有模型的通用方法（如下载或保存、调整输入嵌入、修剪头等）。

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

forward

<来源>

( past_values: Tensor target_values: Tensor = None past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor，形状为(bs, sequence_length, num_input_channels)，required) — 输入序列到模型
• target_values (torch.Tensor, optional) — 与past_values相关联的标签
• past_observed_mask (torch.BoolTensor，形状为(batch_size, sequence_length, num_input_channels)，optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]范围内：
  • 1 表示值是observed，
  • 对于missing的值（即被零替换的 NaN）为 0。
• output_hidden_states（bool，可选）-是否返回所有层的隐藏状态
• output_attentions（bool，可选）-是否返回所有层的输出注意力
• return_dict（bool，可选）-是否返回ModelOutput而不是普通元组。

示例：

>>> from transformers import PatchTSTConfig, PatchTSTForClassification

>>> # classification task with two input channel2 and 3 classes
>>> config = PatchTSTConfig(
...     num_input_channels=2,
...     num_targets=3,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     use_cls_token=True,
... )
>>> model = PatchTSTForClassification(config=config)

>>> # during inference, one only provides past values
>>> past_values = torch.randn(20, 512, 2)
>>> outputs = model(past_values=past_values)
>>> labels = outputs.prediction_logits

PatchTSTForPretraining

class transformers.PatchTSTForPretraining

<来源>

( config: PatchTSTConfig )

参数

• config（PatchTSTConfig](/docs/transformers/v4.37.2/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)方法以加载模型权重。

用于预训练模型的 PatchTST。此模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存，调整输入嵌入，修剪头等）。

此模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以了解所有与一般使用和行为相关的事项。

forward

<来源>

( past_values: Tensor past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values（形状为(bs, sequence_length, num_input_channels)的torch.Tensor，必需）-输入序列到模型
• past_observed_mask（形状为(batch_size, sequence_length, num_input_channels)的torch.BoolTensor，可选）-布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]中：
  • 1 表示值是observed，
  • 对于missing的值（即被零替换的 NaN）为 0。
• output_hidden_states（bool，可选）-是否返回所有层的隐藏状态
• output_attentions（bool，可选）-是否返回所有层的输出注意力
• return_dict（bool，可选）-是否返回ModelOutput而不是普通元组。

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import PatchTSTConfig, PatchTSTForPretraining

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/etth1-hourly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> # Config for random mask pretraining
>>> config = PatchTSTConfig(
...     num_input_channels=7,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     mask_type='random',
...     random_mask_ratio=0.4,
...     use_cls_token=True,
... )
>>> # Config for forecast mask pretraining
>>> config = PatchTSTConfig(
...     num_input_channels=7,
...     context_length=512,
...     patch_length=12,
...     stride=12,
...     mask_type='forecast',
...     num_forecast_mask_patches=5,
...     use_cls_token=True,
... )
>>> model = PatchTSTForPretraining(config)

>>> # during training, one provides both past and future values
>>> outputs = model(past_values=batch["past_values"])

>>> loss = outputs.loss
>>> loss.backward()

PatchTSTForRegression

class transformers.PatchTSTForRegression

<来源>

( config: PatchTSTConfig )

参数

• config（PatchTSTConfig](/docs/transformers/v4.37.2/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)方法以加载模型权重。

用于回归模型的 PatchTST。此模型继承自 PreTrainedModel。查看超类文档以了解库为所有模型实现的通用方法（如下载或保存，调整输入嵌入，修剪头等）。

此模型也是 PyTorch torch.nn.Module子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档以了解所有与一般使用和行为相关的事项。

forward

<来源>

( past_values: Tensor target_values: Tensor = None past_observed_mask: Optional = None output_hidden_states: Optional = None output_attentions: Optional = None return_dict: Optional = None )

参数

• past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 输入模型的序列
• target_values (torch.Tensor of shape (bs, num_input_channels)) — 与past_values相关联的目标值
• past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码，指示哪些past_values是观察到的，哪些是缺失的。掩码值选在[0, 1]之间：
  • 1 表示观察到的值，
  • 0 表示缺失的值（即被零替换的 NaN）。
• output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
• output_attentions (bool, optional) — 是否返回所有层的输出注意力
• return_dict (bool, optional) — 是否返回一个ModelOutput而不是一个普通的元组。

示例：

>>> from transformers import PatchTSTConfig, PatchTSTForRegression

>>> # Regression task with 6 input channels and regress 2 targets
>>> model = PatchTSTForRegression.from_pretrained("namctin/patchtst_etth1_regression")

>>> # during inference, one only provides past values, the model outputs future values
>>> past_values = torch.randn(20, 512, 6)
>>> outputs = model(past_values=past_values)
>>> regression_outputs = outputs.regression_outputs

时间序列 Transformer

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

概述

时间序列 Transformer 模型是用于时间序列预测的基本编码器-解码器 Transformer。此模型由kashif贡献。

使用提示

• 与库中其他模型类似，TimeSeriesTransformerModel 是没有顶部头部的原始 Transformer，而 TimeSeriesTransformerForPrediction 在前者的顶部添加了一个分布头部，可用于时间序列预测。请注意，这是一种所谓的概率预测模型，而不是点预测模型。这意味着模型学习一个分布，可以从中进行采样。该模型不直接输出值。
• TimeSeriesTransformerForPrediction 由 2 个模块组成：编码器，接受时间序列值的context_length作为输入（称为past_values），解码器，预测未来的prediction_length时间序列值（称为future_values）。在训练过程中，需要向模型提供（past_values和future_values）的配对数据。
• 除了原始的（past_values和future_values）之外，通常还向模型提供其他特征。这些可以是以下内容：
  • past_time_features：模型将添加到past_values的时间特征。这些作为 Transformer 编码器的“位置编码”。例如，“月份的日期”，“年份的月份”等作为标量值（然后堆叠在一起形成向量）。例如，如果给定的时间序列值是在 8 月 11 日获得的，则可以将[11, 8]作为时间特征向量（11 代表“月份的日期”，8 代表“年份的月份”）。
  • future_time_features：模型将添加到future_values的时间特征。这些作为 Transformer 解码器的“位置编码”。例如，“月份的日期”，“年份的月份”等作为标量值（然后堆叠在一起形成向量）。例如，如果给定的时间序列值是在 8 月 11 日获得的，则可以将[11, 8]作为时间特征向量（11 代表“月份的日期”，8 代表“年份的月份”）。
  • static_categorical_features：随时间保持不变的分类特征（即所有past_values和future_values具有相同的值）。一个例子是标识给定时间序列的商店 ID 或地区 ID。请注意，这些特征需要对所有数据点（包括未来的数据点）都是已知的。
  • static_real_features：随时间保持不变的实值特征（即所有past_values和future_values具有相同的值）。一个例子是产品的图像表示，您拥有该产品的时间序列值（比如关于鞋子销售的时间序列的 ResNet 嵌入的“鞋子”图片）。请注意，这些特征需要对所有数据点（包括未来的数据点）都是已知的。
• 该模型使用“teacher-forcing”进行训练，类似于 Transformer 用于机器翻译的训练方式。这意味着在训练过程中，将future_values向右移动一个位置作为解码器的输入，前面加上past_values的最后一个值。在每个时间步骤，模型需要预测下一个目标。因此，训练的设置类似于用于语言的 GPT 模型，只是没有decoder_start_token_id的概念（我们只使用上下文的最后一个值作为解码器的初始输入）。
• 在推断时，我们将past_values的最终值作为输入传递给解码器。接下来，我们可以从模型中进行采样，以在下一个时间步骤进行预测，然后将其馈送给解码器以进行下一个预测（也称为自回归生成）。

资源

一系列官方 Hugging Face 和社区（由🌎表示）资源，可帮助您入门。如果您有兴趣提交资源以包含在此处，请随时打开一个 Pull Request，我们将进行审查！资源应该展示一些新内容，而不是重复现有资源。

• 在 HuggingFace 博客中查看时间序列 Transformer 博文：使用🤗 Transformers 进行概率时间序列预测

TimeSeriesTransformerConfig

class transformers.TimeSeriesTransformerConfig

< source >

( prediction_length: Optional = None context_length: Optional = None distribution_output: str = 'student_t' loss: str = 'nll' input_size: int = 1 lags_sequence: List = [1, 2, 3, 4, 5, 6, 7] scaling: Union = 'mean' num_dynamic_real_features: int = 0 num_static_categorical_features: int = 0 num_static_real_features: int = 0 num_time_features: int = 0 cardinality: Optional = None embedding_dimension: Optional = None encoder_ffn_dim: int = 32 decoder_ffn_dim: int = 32 encoder_attention_heads: int = 2 decoder_attention_heads: int = 2 encoder_layers: int = 2 decoder_layers: int = 2 is_encoder_decoder: bool = True activation_function: str = 'gelu' d_model: int = 64 dropout: float = 0.1 encoder_layerdrop: float = 0.1 decoder_layerdrop: float = 0.1 attention_dropout: float = 0.1 activation_dropout: float = 0.1 num_parallel_samples: int = 100 init_std: float = 0.02 use_cache = True **kwargs )

参数

• prediction_length (int) — 解码器的预测长度。换句话说，模型的预测范围。此值通常由数据集决定，我们建议适当设置。
• context_length (int, 可选, 默认为prediction_length) — 编码器的上下文长度。如果为None，上下文长度将与prediction_length相同。
• distribution_output (string, 可选, 默认为"student_t") — 模型的分布发射头。可以是"student_t"、“normal”或“negative_binomial”之一。
• loss (string, 可选, 默认为"nll") — 与distribution_output头对应的模型损失函数。对于参数分布，它是负对数似然（nll）- 目前是唯一支持的损失函数。
• input_size (int, 可选, 默认为 1) — 目标变量的大小，默认情况下对于单变量目标为 1。对于多变量目标，将大于 1。
• scaling (string或bool, 可选, 默认为"mean") — 是否通过"mean"缩放器、“std”缩放器或如果为None则不进行缩放来缩放输入目标。如果为True，则缩放器设置为"mean"。
• lags_sequence (list[int], 可选, 默认为[1, 2, 3, 4, 5, 6, 7]) — 输入时间序列的滞后作为协变量的滞后，通常由数据的频率决定。默认为[1, 2, 3, 4, 5, 6, 7]，但我们建议根据数据集适当地进行更改。
• num_time_features (int, 可选, 默认为 0) — 输入时间序列中的时间特征数量。
• num_dynamic_real_features (int, 可选, 默认为 0) — 动态实值特征的数量。
• num_static_categorical_features (int, 可选, 默认为 0) — 静态分类特征的数量。
• num_static_real_features (int, 可选, 默认为 0) — 静态实值特征的数量。
• cardinality (list[int], 可选) — 每个静态分类特征的基数（不同值的数量）。应该是一个整数列表，长度与num_static_categorical_features相同。如果num_static_categorical_features大于 0，则不能为None。
• embedding_dimension (list[int], 可选) — 每个静态分类特征的嵌入维度。应该是一个整数列表，长度与num_static_categorical_features相同。如果num_static_categorical_features大于 0，则不能为None。
• d_model (int, 可选, 默认为 64) — Transformer 层的维度。
• encoder_layers (int, 可选, 默认为 2) — 编码器层数。
• decoder_layers (int, 可选, 默认为 2) — 解码器层数。
• encoder_attention_heads (int, 可选, 默认为 2) — Transformer 编码器中每个注意力层的注意力头数。
• decoder_attention_heads (int, optional, defaults to 2) — Transformer 解码器中每个注意力层的注意力头数。
• encoder_ffn_dim (int, optional, defaults to 32) — 编码器中“中间”（通常称为前馈）层的维度。
• decoder_ffn_dim (int, optional, defaults to 32) — 解码器中“中间”（通常称为前馈）层的维度。
• activation_function (str or function, optional, defaults to "gelu") — 编码器和解码器中的非线性激活函数（函数或字符串）。如果是字符串，支持"gelu"和"relu"。
• dropout (float, optional, defaults to 0.1) — 编码器和解码器中所有全连接层的 dropout 概率。
• encoder_layerdrop (float, optional, defaults to 0.1) — 每个编码器层的注意力和全连接层的 dropout 概率。
• decoder_layerdrop (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 概率。
• num_parallel_samples (int, optional, defaults to 100) — 每个推理时间步生成的并行样本数。
• init_std (float, optional, defaults to 0.02) — 截断正态权重初始化分布的标准差。
• use_cache (bool, optional, defaults to True) — 是否使用过去的键/值注意力（如果适用于模型）以加速解码。 示例 —

这是用于存储 TimeSeriesTransformerModel 配置的配置类。根据指定的参数实例化一个时间序列 Transformer 模型，定义模型架构。使用默认值实例化配置将产生类似于 Time Series Transformer huggingface/time-series-transformer-tourism-monthly架构的配置。

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

>>> from transformers import TimeSeriesTransformerConfig, TimeSeriesTransformerModel

>>> # Initializing a Time Series Transformer configuration with 12 time steps for prediction
>>> configuration = TimeSeriesTransformerConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = TimeSeriesTransformerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

TimeSeriesTransformerModel

class transformers.TimeSeriesTransformerModel

< source >

( config: TimeSeriesTransformerConfig )

参数

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

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

  此蒙版用于过滤最终损失计算中的缺失值。

• attention_mask（形状为(batch_size, sequence_length)的torch.Tensor，可选）— 用于避免在某些标记索引上执行注意力的蒙版。蒙版值选在[0, 1]范围内：
  • 1 表示未被蒙版的标记，
  • 0 表示被蒙版的标记。

  什么是注意力蒙版？

• decoder_attention_mask（形状为(batch_size, target_sequence_length)的torch.LongTensor，可选）— 用于避免在某些标记索引上执行注意力的蒙版。默认情况下，将使用因果蒙版，以确保模型只能查看以前的输入以预测未来。
• head_mask（形状为(encoder_layers, encoder_attention_heads)的torch.Tensor，可选）— 用于使编码器中注意力模块的特定头部失效的蒙版。蒙版值选在[0, 1]范围内：
  • 1 表示头部未被蒙版，
  • 0 表示头部被蒙版。
• decoder_head_mask（形状为(decoder_layers, decoder_attention_heads)的torch.Tensor，可选）— 用于使解码器中注意力模块的特定头部失效的蒙版。蒙版值选在[0, 1]范围内：
  • 1 表示头部未被蒙版，
  • 0 表示头部被蒙版。
• cross_attn_head_mask（形状为(decoder_layers, decoder_attention_heads)的torch.Tensor，可选）— 用于使交叉注意力模块的特定头部失效的蒙版。蒙版值选在[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时返回，类型为tuple(tuple(torch.FloatTensor))，长度为config.n_layers，每个元组包含 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，用户可以选择仅输入形状为(batch_size, 1)的最后一个decoder_input_ids（这些没有将其过去的键值状态提供给此模型）而不是形状为(batch_size, sequence_length)的所有decoder_input_ids。
• inputs_embeds (torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)，可选） — 可选地，您可以直接传递嵌入表示而不是传递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 (torch.FloatTensor，形状为(batch_size, sequence_length, hidden_size)) — 模型解码器最后一层的隐藏状态序列。 如果仅使用past_key_values，则输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。
• past_key_values (tuple(tuple(torch.FloatTensor)), optional, returned when use_cache=True is passed or when config.use_cache=True) — 当传递use_cache=True或config.use_cache=True时返回，类型为tuple(tuple(torch.FloatTensor))，长度为config.n_layers，每个元组包含 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`, 可选) — 每个时间序列的静态特征，在推断时复制到协变量中。

TimeSeriesTransformerModel 的前向方法，覆盖了__call__特殊方法。

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

示例：

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = TimeSeriesTransformerModel.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"],
... )

>>> last_hidden_state = outputs.last_hidden_state

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 )

内部助手

自定义层和实用工具

原文链接：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时）包含根据配置（<class 'transformers.configuration_utils.PretrainedConfig'>）和输入的不同元素。

• 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 中处理动态形状。