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 的输入 token；(ii) 通道独立性，其中每个通道包含一个单变量时间序列，并在所有序列中共享相同的嵌入和 Transformer 权重。补丁设计自然具有三重优势：局部语义信息保留在嵌入中；在相同的回溯窗口下，注意力图的计算和内存使用量呈二次减少；模型可以关注更长的历史。我们的通道独立补丁时间序列 Transformer (PatchTST) 与 SOTA 基于 Transformer 的模型相比，可以显著提高长期预测的准确性。我们还将我们的模型应用于自监督预训练任务，并获得出色的微调性能，这优于大型数据集上的监督训练。将掩码预训练表示从一个数据集转移到其他数据集也产生了 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: 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[int, list[int], NoneType] = [2] channel_consistent_masking: typing.Optional[bool] = False unmasked_channel_indices: typing.Optional[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[list] = 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) — 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 token。 - init_std (
float, 可选, 默认为 0.02) — 截断正态权重初始化分布的标准差。 - share_projection (
bool, 可选, 默认为True) — 在预测头部的不同通道之间共享投影层。 - scaling (
Union, 可选, 默认为"std") — 是否通过“均值”缩放器、“标准差”缩放器或不使用缩放器（如果为None）来缩放输入目标。如果为True，则缩放器设置为“均值”。 - 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 (
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.configPatchTSTModel
class transformers.PatchTSTModel
< 来源 >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件实例化模型不会加载与模型相关的权重，仅加载配置。请查看 from_pretrained() 方法来加载模型权重。
裸 PatchTST 模型，输出原始隐藏状态，不带任何特定头部。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch Module 使用，并参考 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，形状为(bs, sequence_length, num_input_channels)，必需) — 模型的输入序列。 - past_observed_mask (
torch.BoolTensor，形状为(batch_size, sequence_length, num_input_channels)，可选) — 布尔掩码，指示哪些past_values被观察到，哪些缺失。掩码值选择在[0, 1]：- 1 表示**观察到的**值，
- 0 表示**缺失**的值（即被零替换的 NaN）。
- future_values (
torch.BoolTensor，形状为(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_statePatchTSTForPrediction
class transformers.PatchTSTForPrediction
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查看 from_pretrained() 方法来加载模型权重。
用于预测的 PatchTST 模型。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch Module 使用，并参考 PyTorch 文档中与一般用法和行为相关的所有事项。
前向传播
< source >( 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 (形状为
(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_outputsPatchTSTForClassification
class transformers.PatchTSTForClassification
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查看 from_pretrained() 方法来加载模型权重。
用于分类的 PatchTST 模型。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch Module 使用，并参考 PyTorch 文档中与一般用法和行为相关的所有事项。
前向传播
< source >( past_values: Tensor target_values: typing.Optional[torch.Tensor] = None past_observed_mask: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None ) → transformers.models.patchtst.modeling_patchtst.PatchTSTForClassificationOutput 或 tuple(torch.FloatTensor)
参数
- 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，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回张量下的hidden_states。 - output_attentions (
bool，可选) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回张量下的attentions。 - return_dict (
bool，可选) — 是否返回 ModelOutput 而不是普通元组。
返回
transformers.models.patchtst.modeling_patchtst.PatchTSTForClassificationOutput 或 tuple(torch.FloatTensor)
一个 transformers.models.patchtst.modeling_patchtst.PatchTSTForClassificationOutput 或一个 torch.FloatTensor 元组（如果传递 return_dict=False 或 config.return_dict=False），包含根据配置 (PatchTSTConfig) 和输入的不同元素。
-
loss (
*可选*，在提供labels时返回，形状为(1,)的torch.FloatTensor) — 总损失，是掩码语言模型损失和下一个序列预测（分类）损失的总和。 -
prediction_logits (形状为
(batch_size, num_targets)的torch.FloatTensor) — PatchTST 建模头的预测分数（SoftMax 之前的分数）。 -
hidden_states (
tuple[torch.FloatTensor]，可选，在传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则包括嵌入层输出，加上每层输出）。模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
-
attentions (
tuple[torch.FloatTensor]，可选，在传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
PatchTSTForClassification 的前向方法，覆盖了 __call__ 特殊方法。
尽管前向传递的定义需要在此函数中进行，但之后应调用 Module 实例，而不是此函数，因为前者负责运行预处理和后处理步骤，而后者会默默地忽略它们。
示例
>>> 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_logitsPatchTSTForPretraining
class transformers.PatchTSTForPretraining
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查看 from_pretrained() 方法来加载模型权重。
用于预训练的 PatchTST 模型。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch Module 使用，并参考 PyTorch 文档中与一般用法和行为相关的所有事项。
前向传播
< source >( 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 (形状为
(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，可选) — 是否返回所有层的注意力输出 - 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
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查看 from_pretrained() 方法来加载模型权重。
用于回归的 PatchTST 模型。
该模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（如下载或保存、调整输入嵌入大小、修剪头部等）。
该模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch Module 使用，并参考 PyTorch 文档中与一般用法和行为相关的所有事项。
前向传播
< source >( past_values: Tensor target_values: typing.Optional[torch.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 ) → transformers.models.patchtst.modeling_patchtst.PatchTSTForRegressionOutput 或 tuple(torch.FloatTensor)
参数
- past_values (形状为
(bs, sequence_length, num_input_channels)的torch.Tensor，必填) — 模型的输入序列 - target_values (形状为
(bs, num_input_channels)的torch.Tensor) — 与past_values相关的目标值 - past_observed_mask (形状为
(batch_size, sequence_length, num_input_channels)的torch.BoolTensor，可选) — 布尔掩码，用于指示哪些past_values被观测到，哪些是缺失的。掩码值选择在[0, 1]之间：- 1 表示**观测到的**值，
- 0 表示**缺失的**值（即被零替换的 NaN）。是否返回
ModelOutput而不是普通元组。
- output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参见返回张量下的hidden_states。 - output_attentions (
bool，可选) — 是否返回所有注意力层的注意力张量。有关更多详细信息，请参见返回张量下的attentions。 - return_dict (
bool，可选) — 是否返回 ModelOutput 而不是普通元组。
返回
transformers.models.patchtst.modeling_patchtst.PatchTSTForRegressionOutput 或 tuple(torch.FloatTensor)
一个 transformers.models.patchtst.modeling_patchtst.PatchTSTForRegressionOutput 或一个 torch.FloatTensor 元组（如果传递 return_dict=False 或 config.return_dict=False），包含根据配置 (PatchTSTConfig) 和输入的不同元素。
-
loss (
*可选*，在提供labels时返回，形状为(1,)的torch.FloatTensor) — 均方误差损失。 -
regression_outputs (形状为
(batch_size, num_targets)的torch.FloatTensor) — 时间序列建模头的回归输出。 -
hidden_states (
tuple[torch.FloatTensor]，可选，在传递output_hidden_states=True或config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（如果模型有嵌入层，则包括嵌入层输出，加上每层输出）。模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
-
attentions (
tuple[torch.FloatTensor]，可选，在传递output_attentions=True或config.output_attentions=True时返回) — 形状为(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元组（每层一个）。注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
PatchTSTForRegression 的前向方法，覆盖了 __call__ 特殊方法。
尽管前向传递的定义需要在此函数中进行，但之后应调用 Module 实例，而不是此函数，因为前者负责运行预处理和后处理步骤，而后者会默默地忽略它们。
示例
>>> 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