Transformers 文档

PatchTST

PatchTST

概述

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

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

模型

论文的摘要如下:

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

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

使用提示

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

资源

  • 一篇深入解释PatchTST的博客文章可以在这里找到。该博客也可以在Google Colab中打开。

PatchTSTConfig

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 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: typing.Union[str, bool, NoneType] = 'std' do_mask_input: typing.Optional[bool] = None mask_type: str = 'random' random_mask_ratio: float = 0.5 num_forecast_mask_patches: typing.Union[typing.List[int], int, NoneType] = [2] channel_consistent_masking: typing.Optional[bool] = False unmasked_channel_indices: typing.Optional[typing.List[int]] = None mask_value: int = 0 pooling_type: str = 'mean' head_dropout: float = 0.0 prediction_length: int = 24 num_targets: int = 1 output_range: typing.Optional[typing.List] = None num_parallel_samples: int = 100 **kwargs )

参数

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

transformers.PatchTSTModel

< >

( config: PatchTSTConfig )

参数

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

PatchTST模型输出原始隐藏状态,没有任何特定的头部。 该模型继承自PreTrainedModel。请查看超类文档以了解库为其所有模型实现的通用方法(如下载或保存、调整输入嵌入大小、修剪头部等)。

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

前进

< >

( past_values: Tensor past_observed_mask: typing.Optional[torch.Tensor] = None future_values: typing.Optional[torch.Tensor] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None )

参数

  • past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 模型的输入序列
  • past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码,用于指示哪些past_values被观察到,哪些缺失。掩码值在[0, 1]中选择:
    • 1 表示值是观察到的
    • 0 表示值是缺失的(即被零替换的NaNs)。
  • future_values (torch.BoolTensor of shape (batch_size, prediction_length, num_input_channels), optional) — 与past_values相关的未来目标值
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的输出注意力
  • 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

transformers.PatchTSTForPrediction

< >

( config: PatchTSTConfig )

参数

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

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

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

前进

< >

( 过去的值: Tensor 过去观察到的掩码: typing.Optional[torch.Tensor] = None 未来的值: typing.Optional[torch.Tensor] = None 输出隐藏状态: typing.Optional[bool] = None 输出注意力: typing.Optional[bool] = None 返回字典: typing.Optional[bool] = None )

参数

  • past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 模型的输入序列
  • past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码,用于指示哪些past_values被观察到,哪些缺失。掩码值在[0, 1]中选择:
    • 1 表示被观察到的值,
    • 0 表示缺失的值(即被零替换的NaNs)。
  • future_values (torch.Tensor of shape (bs, forecast_len, num_input_channels), optional) — 与past_values相关的未来目标值
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的输出注意力
  • return_dict (bool, 可选) — 是否返回一个 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

transformers.PatchTSTForClassification

< >

( config: PatchTSTConfig )

参数

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

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

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

前进

< >

( 过去值: Tensor 目标值: Tensor = None 过去观察掩码: typing.Optional[bool] = None 输出隐藏状态: typing.Optional[bool] = None 输出注意力: typing.Optional[bool] = None 返回字典: typing.Optional[bool] = None )

参数

  • past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 模型的输入序列
  • target_values (torch.Tensor, optional) — 与 past_values 关联的标签
  • past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码,用于指示哪些past_values被观察到,哪些缺失。掩码值在[0, 1]中选择:
    • 1 表示值是观察到的
    • 0 表示值是缺失的(即被零替换的NaNs)。
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的输出注意力
  • 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

transformers.PatchTSTForPretraining

< >

( config: PatchTSTConfig )

参数

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

用于预训练模型的PatchTST。 该模型继承自PreTrainedModel。请查看超类文档以了解库为其所有模型实现的通用方法(如下载或保存、调整输入嵌入的大小、修剪头等)。

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

前进

< >

( past_values: Tensor past_observed_mask: typing.Optional[torch.Tensor] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None )

参数

  • past_values (torch.Tensor of shape (bs, sequence_length, num_input_channels), required) — 模型的输入序列
  • past_observed_mask (torch.BoolTensor of shape (batch_size, sequence_length, num_input_channels), optional) — 布尔掩码,用于指示哪些past_values被观察到,哪些缺失。掩码值在[0, 1]中选择:
    • 1 表示值是观察到的
    • 0 表示值是缺失的(即被零替换的NaNs)。
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的输出注意力
  • 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

transformers.PatchTSTForRegression

< >

( config: PatchTSTConfig )

参数

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

用于回归模型的PatchTST。 该模型继承自PreTrainedModel。请查看超类文档以了解库为其所有模型实现的通用方法(如下载或保存、调整输入嵌入大小、修剪头等)。

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

前进

< >

( past_values: Tensor target_values: Tensor = None past_observed_mask: typing.Optional[torch.Tensor] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None return_dict: typing.Optional[bool] = 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 表示值是缺失的(即被零替换的NaNs)。
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的输出注意力
  • return_dict (bool, 可选) — 是否返回一个 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
< > Update on GitHub