Transformers文档

补丁TST

Transformers

加入Hugging Face社区

并获得增强文档体验

合作模型、数据集和Spaces

使用加速推理加快示例速度

切换文档主题

开始使用

PatchTST

概述

该PatchTST模型由Yuqi Nie、Nam H. Nguyen、Phanwadee Sinthong和Jayant Kalagnanam在《一个时间序列值64个词：Transformer的长期预测》一文中提出。[arxiv.org/abs/2211.14730](https://arxiv.org/abs/2211.14730)。

从宏观上看，模型将时间序列向量化为给定大小的块，并使用Transformer将得到的向量序列编码，然后通过适当的头预测预测长度。模型如图所示。

model

论文的摘要如下

我们提出了一种基于Transformer的多元时间序列预测和自监督表示学习的高效模型设计。它基于两个关键组件：(i)将时间序列分割为子序列级块，作为Transformer的输入标记；(ii)通道独立性，其中每个通道包含一个单个的一元时间序列，该时间序列具有相同的嵌入和在所有序列中共享的Transformer权重。链接设计自然具有三重效益：本地语义信息保留在嵌入中；给定相同的回望窗口，注意图的计算和内存使用量二次降低；模型可以关注更长的历史。与SOTA的基于Transformer的模型相比，我们的通道独立的块时间序列Transformer（PatchTST）在长期预测精度方面可以明显改进。我们还应用我们的模型到自监督预训练任务，并获得出色的微调性能，在大型数据集上优于监督训练。将一个数据集上的掩码预训练表示转移到另一个数据集，也产生了SOTA的预测精度。

该模型由namctin、gsinthong、diepi、vijaye12、wmgifford、kashif等贡献。原始代码可以在[这里](https://github.com/yuqinie98/PatchTST)找到。

使用技巧

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

资源

有关 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: 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, 可选, 默认为 1) — 目标变量的大小，对于单变量目标默认为 1。对于多变量目标将为 > 1。
context_length (int, 可选, 默认为 32) — 输入序列的上下文长度。
distribution_output (str, 可选, 默认为 "student_t") — 当损失为“nll”时模型发出的分布。可以是“student_t”、“normal”或“negative_binomial”。
loss (str, 可选，默认为 "mse") — 与 distribution_output 头对应的模型损失函数。对于参数分布它是对数似然负值（“nll”），对于点估计则是均方误差（“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) — 在Transformer中激活通道注意力块，允许通道之间相互关注。
ffn_dim (int, 可选, 默认为 512) — Transformer 编码器中间层（通常称为前馈层）的维度。
norm_type (str , 可选, 默认为 "batchnorm") — Transformer 每层的归一化。可以是 "batchnorm" 或 "layernorm"。
norm_eps (float, 可选, 默认为 1e-05) — 为了归一化的数值稳定性，添加到分母的值。
attention_dropout (float, 可选, 默认为 0.0) — 注意力概率的 dropout 概率。
位置dropout (float, 可选, 默认为0.0) — 位置嵌入层的dropout概率。
路径dropout (float, 可选, 默认为0.0) — 剩余块中的dropout路径。
ff_dropout (float, 可选, 默认为0.0) — 用于前馈网络两层之间的dropout概率。
bias (bool, 可选, 默认为True) — 是否在feed-forward网络中添加偏置。
init_std (float, 可选, 默认为 0.02) — 截断正态权重初始化分布的标准差。
share_projection (bool, 可选, 默认为 True) — 在预测头部的不同通道间共享投影层。
scaling (Union, 可选, 默认为 "std") — 是否通过“mean”缩放器、“std”缩放器或无缩放器（如果为None）对输入目标进行缩放。如果为True，缩放器设置为“mean”。
do_mask_input （bool，可选）—— 在预训练期间应用掩码。
mask_type （str，可选，默认为 "random"）—— 掩码类型。目前支持 "random" 和 "forecast"。
random_mask_ratio （float，可选，默认为 0.5）—— 在随机预训练期间应用掩码的掩码比例。
num_forecast_mask_patches (int 或 list，可选，默认为 [2]）— 每批样本末尾要被遮蔽的补丁数量。如果是整数，则批次中的所有样本都将具有相同数量的遮蔽补丁。如果是列表，则批次中的样本将通过列表中定义的数字随机遮蔽。此参数仅用于预测预训练。
channel_consistent_masking (bool，可选，默认为 False）— 如果频道一致遮蔽为 True，则所有频道都将具有相同的遮蔽模式。
unmasked_channel_indices (list，可选）— 预训练期间未遮蔽的通道索引列表。列表中的值是1和 num_input_channels 之间的数字。
mask_value (int, 可选，默认为 0) — 被遮蔽补丁区域将填充的值为 mask_value。
pooling_type (str, 可选，默认为 "mean") — 嵌入池化类型。支持 "mean"、"max" 和 None。
head_dropout (float, 可选，默认为 0.0) — 头部的 dropout 概率。
prediction_length (int, 可选，默认为 24) — 模型将输出的预测范围。
num_targets (int, 可选, 默认为1) — 回归和分类任务的目标数量。对于分类，它是类数量。
output_range (列表, 可选) — 回归任务的输出范围。可以设置输出值范围来强制模型产生指定范围内的值。
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 文档了解所有与一般使用和行为相关的问题。

forward

< 源代码 >

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

参数

past_values (torch.Tensor 形状 (bs, sequence_length, num_input_channels)，必须) — 输入到模型的序列
past_observed_mask (torch.BoolTensor shapes 为 (batch_size, sequence_length, num_input_channels)，可选) — 标识哪些 past_values 被观察过，哪些缺失的布尔掩码。掩码值选择在 [0, 1]：
- 1 表示 观察到的 值，
- 0 表示 缺失的 值（例如，被零替换的 NaN 值）。
future_values (torch.BoolTensor shapes 为 (batch_size, prediction_length, num_input_channels)，可选) — 与 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

类 transformers.PatchTSTForPrediction

< 源代码 >

( config: PatchTSTConfig )

参数

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

PatchTST 预测模型。此模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头部等）。

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

forward

< source >

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

参数

past_values (torch.Tensor shape (bs, sequence_length, num_input_channels), required) — 模型输入序列
ment见过和缺失的。掩码值选择在 [0, 1] 范围内：
future_values （形状为 的 tensor，可选) — 与 past_values 相关的未来的目标值
output_hidden_states （布尔值，可选) — 是否返回所有层的隐藏状态
output_attentions (bool, 可选) — 是否返回所有层的输出注意力
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
  < source > ( config: PatchTSTConfig  )
   参数 
  config (PatchTSTConfig) — 模型配置类，包含所有模型参数。使用配置文件初始化不会加载与模型关联的权重，只加载配置。检查 from_pretrained() 方法以加载模型权重。 
   
 用于分类的 PatchTST 模型。该模型继承自 PreTrainedModel。查看超级类文档，了解库为所有模型实现的通用方法（如下载或保存，调整输入嵌入的大小，剪枝头部等）。
 此模型也是 PyTorch torch.nn.Module 子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档了解所有与一般使用和行为相关的问题。
  forward
  < source > ( 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, optional) — 与 past_values 关联的标签  
 past_observed_mask （torch.BoolTensor 形状为 (batch_size, sequence_length, num_input_channels)，可选） — 表示哪些 past_values 已观察以及哪些缺失的布尔掩码。掩码值选择在 [0, 1]：
  1 为 已观察 的值，
 0 为 缺失 的值（即被零替换的 NaN）。
 
  
 output_hidden_states （bool，可选） — 是否返回所有层的隐藏状态  
 output_attentions （bool，可选） — 是否返回所有层的输出注意力  
 return_dict (bool, optional) — 是否返回 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
  < source > ( config: PatchTSTConfig  )
   参数 
  config (PatchTSTConfig) — 包含模型所有参数的模型配置类。用配置文件初始化不会加载模型相关的权重，只有配置。请查看from_pretrained() 方法以加载模型权重。  
   
 用于预训练的PatchTST模型。该模型继承自PreTrainedModel。请查看超类文档，了解库为所有模型实现的通用方法（例如下载或保存，调整输入嵌入，剪枝头部等）。
 此模型也是 PyTorch torch.nn.Module 子类。将其用作常规 PyTorch 模块，并参考 PyTorch 文档了解所有与一般使用和行为相关的问题。
  forward
  < 来源 > ( past_values: Tensor past_observed_mask: 可选 = None output_hidden_states: 可选 = None output_attentions: 可选 = None return_dict: 可选 = 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）。
  
 output_hidden_states (布尔值，可选) — 是否返回所有层的隐藏状态  
 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
  类 transformers.PatchTSTForRegression
  < source > ( config: PatchTSTConfig  )
   参数 
  config（《神经网络配置》）— 包含模型所有参数的模型配置类。使用配置文件初始化不加载模型相关的权重，仅加载配置。查看from_pretrained() 方法 以加载模型权重。  
   
 回归模型的 patchTST。此模型继承自 预训练模型。请查看超类文档，了解库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入的大小、剪枝头部等）
 此模型也是 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)，必需） — 模型输入序列  
 target_values (torch.Tensor 的形状为 (bs, num_input_channels)) — 与 past_values 关联的目标值  
 past_observed_mask (torch.BoolTensor 的形状为 (batch_size, sequence_length, num_input_channels)，可选) — 标记哪些 past_values 被观察到和哪些缺失的布尔掩码。掩码值选择在 [0, 1]：
  1 代表观察到的值，
 0 代表缺失的值（即被零替换的 NaN）。
 
  
 output_hidden_states (bool，可选) — 是否返回所有层的隐藏状态  
 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
 < > 在GitHub上更新


				←PatchTSMixer 时间序列变换器→


		



PatchTST 概览 使用技巧 资源 PatchTSTConfig PatchTSTModel PatchTSTForPrediction PatchTSTForClassification PatchTSTForPretraining PatchTSTForRegression