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 权重。补丁设计自然具有三重优势：局部语义信息保留在嵌入中；在相同的回溯窗口下，注意力图的计算和内存使用量呈二次方减少；并且模型可以关注更长的历史记录。与 SOTA 基于 Transformer 的模型相比，我们的通道独立补丁时间序列 Transformer (PatchTST) 可以显着提高长期预测的准确性。我们还将我们的模型应用于自监督预训练任务，并获得了出色的微调性能，优于大型数据集上的监督训练。将掩码预训练表示从一个数据集转移到其他数据集也产生了 SOTA 预测准确性。
此模型由 namctin、gsinthong、diepi、vijaye12、wmgifford 和 kashif 贡献。 原始代码可以在这里找到。
使用技巧
该模型也可用于时间序列分类和时间序列回归。 请参阅相应的 PatchTSTForClassification 和 PatchTSTForRegression 类。
资源
- 有关深入解释 PatchTST 的博客文章可以在这里找到。 该博客也可以在 Google Colab 中打开。
PatchTSTConfig
class transformers.PatchTSTConfig
< source >( 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, typing.List[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, 可选, 默认为 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") — 是否通过 “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.configPatchTSTModel
class transformers.PatchTSTModel
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 模型配置类，包含模型的所有参数。使用配置文件初始化不会加载与模型关联的权重，仅加载配置。查看 from_pretrained() 方法以加载模型权重。
裸 PatchTST 模型，输出原始隐藏状态，没有任何特定的 head。此模型继承自 PreTrainedModel。查看超类文档以获取库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝 head 等）。
此模型也是 PyTorch torch.nn.Module 子类。将其用作常规 PyTorch 模块，并参阅 PyTorch 文档以获取与常规用法和行为相关的所有事项。
forward
< 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 (
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 模块，并参阅 PyTorch 文档以获取与常规用法和行为相关的所有事项。
forward
< 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 (
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.Tensor，形状为(bs, forecast_len, 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 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 模块，并参阅 PyTorch 文档以获取与常规用法和行为相关的所有事项。
forward
< source >( past_values: Tensor target_values: 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 )
参数
- past_values (
torch.Tensor，形状为(bs, sequence_length, num_input_channels)，必需) — 模型的输入序列 - target_values (
torch.Tensor，可选) — 与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，可选) — 是否返回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_logitsPatchTSTForPretraining
class transformers.PatchTSTForPretraining
< source >( config: PatchTSTConfig )
参数
- config (PatchTSTConfig) — 具有模型所有参数的模型配置类。使用配置文件初始化不会加载与模型关联的权重，仅加载配置。查看 from_pretrained() 方法以加载模型权重。
PatchTST 预训练模型。此模型继承自 PreTrainedModel。查看超类文档以获取库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
此模型也是 PyTorch torch.nn.Module 子类。将其用作常规 PyTorch 模块，并参阅 PyTorch 文档以获取与常规用法和行为相关的所有事项。
forward
< 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 (
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）。
- 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 模块，并参阅 PyTorch 文档以获取与常规用法和行为相关的所有事项。
forward
< source >( past_values: Tensor target_values: Tensor = None past_observed_mask: typing.Optional[torch.Tensor] = None output_hidden_statesoutput_attentions: typing.Optional[bool] = None return_dict: typing.Optional[bool] = 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，可选) — 是否返回所有层的输出注意力 - 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