Hugging Face 的标志

Transformers 文档

PatchTST

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

PatchTST

概述

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

从高层次来看，该模型将时间序列向量化为给定大小的 patches，并通过 Transformer 对生成的向量序列进行编码，然后通过适当的 head 输出预测长度的forecast。该模型如下图所示

model

论文摘要如下

我们为多元时间序列预测和自监督表征学习提出了一种基于 Transformer 的高效模型设计。它基于两个关键组件：（i）将时间序列分割成子序列级别的 patches，这些 patches 用作 Transformer 的输入 tokens；（ii）通道独立性，其中每个通道包含一个单变量时间序列，该时间序列在所有序列中共享相同的嵌入和 Transformer 权重。Patching 设计自然具有三重优势：局部语义信息保留在嵌入中；在相同的回溯窗口下，注意力图的计算和内存使用量呈二次方降低；并且模型可以关注更长的历史记录。与 SOTA 基于 Transformer 的模型相比，我们的通道独立 patch 时间序列 Transformer (PatchTST) 可以显着提高长期预测精度。我们还将我们的模型应用于自监督预训练任务，并获得了出色的微调性能，优于大型数据集上的监督训练。将masked预训练表征从一个数据集转移到其他数据集也能产生 SOTA 预测精度。

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

使用技巧

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

资源

  • 有关深入解释 PatchTST 的博客文章，请访问 这里。该博客也可以在 Google Colab 中打开。

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 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 长度。
  • patch_stride (int, 可选, 默认为 1) — 定义分块过程的步幅。
  • num_hidden_layers (int, 可选, 默认为 3) — 隐藏层数。
  • d_model (int, 可选, 默认为 128) — Transformer 层的维度。
  • num_attention_heads (int, 可选, 默认为 4) — Transformer 编码器中每个注意力层的注意力头数。
  • 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 概率。
  • positional_dropout (float, 可选, 默认为 0.0) — 位置嵌入层中的 dropout 概率。
  • path_dropout (float, 可选, 默认为 0.0) — 残差块中的 dropout 路径。
  • ff_dropout (float, 可选, 默认为 0.0) — 前馈网络的两层之间使用的 dropout 概率。
  • bias (bool, 可选, 默认为 True) — 是否在前馈网络中添加偏置。
  • activation_function (str, 可选, 默认为 "gelu") — Transformer 中的非线性激活函数（字符串）。支持 "gelu" 和 "relu"。
  • pre_norm (bool, 可选, 默认为 True) — 如果 pre_norm 设置为 True，则在自注意力之前应用归一化。否则，归一化在残差块之后应用。
  • positional_encoding_type (str, 可选, 默认为 "sincos") — 位置编码。支持选项 "random" 和 "sincos"。
  • use_cls_token (bool, 可选, 默认为 False) — 是否使用 cls 令牌。
  • 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]) — 每个批次样本末尾要掩盖的 patch 数量。如果它是一个整数，则批次中的所有样本将具有相同数量的掩盖 patch。如果它是一个列表，则批次中的样本将通过列表中定义的数字随机掩盖。此参数仅用于预测预训练。
  • channel_consistent_masking (bool, 可选, 默认为 False) — 如果通道一致性掩码为 True，则所有通道将具有相同的掩码模式。
  • unmasked_channel_indices (list, 可选) — 在预训练期间不进行掩码的通道的索引。列表中的值是 1 到 num_input_channels 之间的数字
  • mask_value (int, 可选, 默认为 0) — 掩码 patch 中的值将由 mask_value 填充。
  • pooling_type (str, 可选, 默认为 "mean") — 嵌入的池化方式。支持 "mean", "max" 和 None。
  • head_dropout (float, 可选, 默认为 0.0) — head 的 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

< >

( config: PatchTSTConfig )

参数

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

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

此模型也是 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 (形状为 (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

< >

( 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 (形状为 (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 (形状为 (bs, forecast_len, num_input_channels) 的 torch.Tensor，可选) — 与 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 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 (形状为 (bs, sequence_length, num_input_channels) 的 torch.Tensor，必需) — 模型的输入序列
  • target_values (torch.Tensor, 可选) — 与 past_values 关联的标签
  • past_observed_mask (形状为 (batch_size, sequence_length, num_input_channels) 的 torch.BoolTensor，可选) — 布尔掩码，用于指示哪些 past_values 是被观察到的，哪些是缺失的。在 [0, 1] 中选择的掩码值：

    • 1 代表观察到的值，
    • 0 代表缺失的值（即被零替换的 NaN）。
  • 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) — 包含模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，仅加载配置。查看 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 代表观察到的值，
    • 0 代表缺失的值（即被零替换的 NaN）。
  • output_hidden_states (bool, 可选) — 是否返回所有层的隐藏状态
  • output_attentions (bool, optional) — 是否返回所有层的注意力输出
  • return_dict (bool, optional) — 是否返回 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) — 带有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型相关的权重，仅加载配置。查看 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，形状为 (bs, num_input_channels)) — 与 past_values 关联的目标值
  • past_observed_mask (torch.BoolTensor，形状为 (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
< > 更新 在 GitHub 上

←PatchTSMixer 时间序列 Transformer→