# 时间序列 Transformer

## 概述

Time Series Transformer 模型是一个用于时间序列预测的原始编码器-解码器 Transformer。该模型由 [kashif](https://huggingface.co/kashif) 贡献。

## 使用技巧

- 与库中的其他模型类似，[TimeSeriesTransformerModel](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerModel) 是不带任何头部的原始 Transformer，而 [TimeSeriesTransformerForPrediction](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction)
在原有模型之上添加了一个分布头，可用于时间序列预测。请注意，这是一个所谓的概率预测模型，而非点预测模型。这意味着模型学习的是一个分布，可以从该分布中进行采样。模型不会直接输出数值。
- [TimeSeriesTransformerForPrediction](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction) 由两个模块组成：一个编码器，它接收长度为 `context_length` 的时间序列值作为输入（称为 `past_values`），
以及一个解码器，用于预测未来 `prediction_length` 个时间步的时间序列值（称为 `future_values`）。在训练期间，需要向模型提供（`past_values` 和 `future_values`）的配对数据。
- 除了原始数据（`past_values` 和 `future_values`）之外，通常还会向模型提供额外的特征。这些特征可以是：
  - `past_time_features`：模型将添加到 `past_values` 中的时间特征。这些特征充当 Transformer 编码器的“位置编码”。示例包括“当月日期”、“当年月份”等，以标量值表示（然后堆叠为一个向量）。例如，如果某个时间序列值是在 8 月 11 日获取的，则时间特征向量可以是 [11, 8]（11 表示“当月日期”，8 表示“当年月份”）。
  - `future_time_features`：模型将添加到 `future_values` 中的时间特征。这些特征充当 Transformer 解码器的“位置编码”。示例包括“当月日期”、“当年月份”等，以标量值表示（然后堆叠为一个向量）。例如，如果某个时间序列值是在 8 月 11 日获取的，则时间特征向量可以是 [11, 8]（11 表示“当月日期”，8 表示“当年月份”）。
  - `static_categorical_features`：随时间保持不变的类别特征（即所有 `past_values` 和 `future_values` 中的值均相同）。例如，用于标识特定时间序列的门店 ID 或区域 ID。请注意，这些特征必须对所有数据点（包括未来数据点）都是已知的。
  - `static_real_features`：随时间保持不变的实值特征（即所有 `past_values` 和 `future_values` 的值均相同）。一个示例是产品图像表示，即你拥有其时间序列值的产品（例如，如果你的时间序列是关于鞋子销售的，那么“鞋子”图片的 [ResNet](resnet) 嵌入就是一个例子）。请注意，这些特征必须对所有数据点（包括未来的数据点）都是已知的。
- 模型采用“教师强制”（teacher-forcing）进行训练，类似于 Transformer 在机器翻译中的训练方式。这意味着在训练过程中，
将`future_values`向右移动一位作为解码器的输入，并在前面拼接`past_values`的最后一个值。在每个时间步，模型都需要预测下一个目标。因此，训练的设置与用于语言的 GPT 模型类似，只是没有`decoder_start_token_id`的概念（我们直接使用上下文的最后一个值作为解码器的初始输入）。
- 在推理时，我们将 `past_values` 的最终值作为解码器的输入。接下来，我们可以从模型中采样，以预测下一个时间步，
然后将其输入解码器以进行下一步预测（也称为自回归生成）。

## 资源

一份来自 Hugging Face 官方和社区（以 🌎 标识）的资源列表，旨在帮助你快速上手。如果你希望提交资源以收录于此，欢迎随时发起 Pull Request，我们将进行审核！理想情况下，该资源应展示一些新内容，而非重复现有资源。

- 查看 HuggingFace 博客上的 Time Series Transformer 博客文章：[使用 🤗 Transformers 进行概率时间序列预测](https://huggingface.co/blog/time-series-transformers)

## TimeSeriesTransformerConfig[[transformers.TimeSeriesTransformerConfig]]

#### transformers.TimeSeriesTransformerConfig[[transformers.TimeSeriesTransformerConfig]]

```python
transformers.TimeSeriesTransformerConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, prediction_length: int | None = None, context_length: int | None = None, distribution_output: str = 'student_t', loss: str = 'nll', input_size: int = 1, lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7), scaling: str | bool | None = 'mean', num_dynamic_real_features: int = 0, num_static_categorical_features: int = 0, num_static_real_features: int = 0, num_time_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, encoder_ffn_dim: int = 32, decoder_ffn_dim: int = 32, encoder_attention_heads: int = 2, decoder_attention_heads: int = 2, encoder_layers: int = 2, decoder_layers: int = 2, activation_function: str = 'gelu', d_model: int = 64, dropout: float | int = 0.1, encoder_layerdrop: float | int = 0.1, decoder_layerdrop: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, num_parallel_samples: int = 100, init_std: float = 0.02, use_cache: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/configuration_time_series_transformer.py#L24)

**参数：**

is_encoder_decoder (`bool`，*可选*，默认为 `True`)：模型是否用作编码器/解码器。

prediction_length (`int`, *optional*) : 解码器的预测长度。换句话说，即模型的预测范围。该值通常由数据集决定，我们建议将其设置为合适的值。

context_length (`int`, *可选*，默认为 `prediction_length`)：编码器的上下文长度。如果为 `None`，则上下文长度与 `prediction_length` 相同。

distribution_output (`string`，*可选*，默认为 `"student_t"`)：模型的分布发射头。可以是 "student_t"、"normal" 或 "negative_binomial"。

loss (`string`，*可选*，默认为 `"nll"`)：与 `distribution_output` 头对应的模型的损失函数。对于参数化分布，它是负对数似然（nll）——目前这是唯一支持的选项。

input_size (`int`，*可选*，默认为 1)：目标变量的大小，对于单变量目标，默认值为 1。对于多变量目标，该值将大于 1。

lags_sequence (`list[int]`，*可选*，默认为 `[1, 2, 3, 4, 5, 6, 7]`)：作为协变量的输入时间序列的滞后项，通常由数据的频率决定。默认值为 `[1, 2, 3, 4, 5, 6, 7]`，但我们建议根据数据集适当调整。

scaling (`string` 或 `bool`，*可选*，默认为 `"mean"`)：是否通过 "mean" 缩放器、"std" 缩放器对输入目标进行缩放，若为 `None` 则不进行缩放。若为 `True`，则缩放器设置为 "mean"。

num_dynamic_real_features (`int`，*可选*，默认为 0)：动态实值特征的数量。

num_static_categorical_features (`int`，*可选*，默认为 0)：静态类别特征的数量。

num_static_real_features (`int`，*可选*，默认为 0)：静态实值特征的数量。

num_time_features (`int`，*可选*，默认为 0)：输入时间序列中时间特征的数量。

cardinality (`list[int]`, *可选*) : 每个静态分类特征的基数（不同值的数量）。应为整数列表，长度与 `num_static_categorical_features` 相同。如果 `num_static_categorical_features` > 0，则不能为 `None`。

embedding_dimension (`list[int]`, *可选*) : 嵌入和隐藏状态的维度。

encoder_ffn_dim (`int`, *可选*，默认为 `32`)：编码器中“中间”（通常称为前馈）层的维度。

decoder_ffn_dim (`int`，*可选*，默认为 `32`)：解码器中“中间”（通常称为前馈）层的维度。

encoder_attention_heads (`int`，*可选*，默认为 `2`)：Transformer 编码器中每个注意力层的注意力头数量。

decoder_attention_heads (`int`，*可选*，默认为 `2`)：Transformer 解码器中每个注意力层的注意力头数量。

encoder_layers (`int`，*可选*，默认为 `2`)：Transformer 编码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

decoder_layers (`int`，*可选*，默认为 `2`)：Transformer 解码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

activation_function (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

d_model (`int`，*可选*，默认为 `64`)：编码器层和池化层的大小。

dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。

encoder_layerdrop (`Union[float, int]`，*可选*，默认值为 `0.1`)：编码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

decoder_layerdrop (`Union[float, int]`，*可选*，默认值为 `0.1`)：解码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.1`)：注意力概率的 dropout 比率。

activation_dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：全连接层内部激活值的 dropout 比率。

num_parallel_samples (`int`，*可选*，默认为 100)：推理过程中每个时间步并行生成的样本数量。

init_std (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

这是用于存储 TimeSeriesTransformerModel 配置的类。它根据指定的参数实例化时间序列 Transformer 模型，并定义模型架构。使用默认值实例化配置将得到与 [huggingface/time-series-transformer-tourism-monthly](https://huggingface.co/huggingface/time-series-transformer-tourism-monthly) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import TimeSeriesTransformerConfig, TimeSeriesTransformerModel

>>> # Initializing a Time Series Transformer configuration with 12 time steps for prediction
>>> configuration = TimeSeriesTransformerConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = TimeSeriesTransformerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## TimeSeriesTransformerModel[[transformers.TimeSeriesTransformerModel]]

#### transformers.TimeSeriesTransformerModel[[transformers.TimeSeriesTransformerModel]]

```python
transformers.TimeSeriesTransformerModel(config: TimeSeriesTransformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L782)

**参数：**

config ([TimeSeriesTransformerConfig](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

输出原始隐藏状态、顶部未附加任何特定头部的裸 Time Series Transformer 模型。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.TimeSeriesTransformerModel.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L920)

**参数：**

past_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)` 或 `(batch_size, sequence_length, input_size)`)：时间序列的过去值，作为上下文用于预测未来。该张量的序列大小必须大于模型的 `context_length`，因为模型将使用更大的大小来构建滞后特征，即从过去添加的额外值，用作“额外上下文”。此处的 `sequence_length` 等于 `config.context_length` + `max(config.lags_sequence)`；如果未配置 `lags_sequence`，则等于 `config.context_length` + 7（因为默认情况下，`config.lags_sequence` 中最大的回看索引为 7）。属性 `_past_length` 返回过去的实际长度。`past_values` 是 Transformer 编码器接收的输入（可包含额外特征，例如 `static_categorical_features`、`static_real_features`、`past_time_features` 和滞后值）。可选地，缺失值需要用零替换，并通过 `past_observed_mask` 进行指示。对于多变量时间序列，需要 `input_size` > 1 的维度，该维度对应于每个时间步中时间序列的变量数量。

past_time_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, num_features)`)：必需的时间特征，模型内部会将其添加到 `past_values` 中。这些特征可以是“一年中的月份”、“一个月中的日期”等，并以向量形式编码（例如作为傅里叶特征）。这些特征也可以是所谓的“年龄”特征，其基本作用是帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步，年龄特征的值较小，并且随着我们接近当前时间步而单调递增。节假日特征也是时间特征的一个良好示例。这些特征充当输入的“位置编码”。因此，与 BERT 等模型不同（后者的位置编码是作为模型参数从零开始内部学习的），Time Series Transformer 要求提供额外的时间特征。Time Series Transformer 仅为 `static_categorical_features` 学习额外的嵌入。可以将额外的动态实值协变量拼接到此张量中，但需注意这些特征必须在预测时已知。此处的 `num_features` 等于 `config.`num_time_features` + `config.num_dynamic_real_features`。

past_observed_mask (`torch.BoolTensor`，形状为 `(batch_size, sequence_length)` 或 `(batch_size, sequence_length, input_size)`，*可选*)：布尔掩码，用于指示哪些 `past_values` 是被观测到的，哪些是缺失的。掩码值在 `[0, 1]` 中选取： - 1 表示 **已观测** 的值， - 0 表示 **缺失** 的值（即被零替换的 NaN）。

static_categorical_features (`torch.LongTensor`，形状为 `(batch_size, number of static categorical features)`，*可选*)：可选的静态类别特征，模型将为其学习嵌入，并将其添加到时间序列的值中。静态类别特征是指在所有时间步上具有相同值的特征（即随时间保持静态）。静态类别特征的一个典型示例是时间序列 ID。

static_real_features (`torch.Tensor`，形状为 `(batch_size, number of static real features)`，*可选*)：可选的静态实值特征，模型会将其添加到时间序列的值中。静态实值特征是指在所有时间步上具有相同值的特征（即随时间保持静态）。静态实值特征的一个典型示例是促销信息。

future_values (`torch.Tensor`，形状为 `(batch_size, prediction_length)` 或 `(batch_size, prediction_length, input_size)`，*可选*) : 时间序列的未来值，用作模型的标签。`future_values` 是 Transformer 在训练期间需要学习输出的内容，其输入为 `past_values`。 此处的序列长度等于 `prediction_length`。 有关详细信息，请参阅演示笔记本和代码片段。 可选地，在训练期间，任何缺失值都需要用零替换，并通过 `future_observed_mask` 进行指示。 对于多元时间序列，需要 `input_size` > 1 维度，该维度对应于每个时间步中时间序列的变量数量。

future_time_features (`torch.Tensor`，形状为 `(batch_size, prediction_length, num_features)`)：预测窗口所需的时间特征，模型内部会将其添加到 `future_values` 中。这些特征可以是“一年中的月份”、“一个月中的日期”等，并以向量形式编码（例如作为傅里叶特征）。它们也可以是所谓的“年龄”特征，基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步，年龄特征的值较小，并且随着我们接近当前时间步而单调递增。节假日特征也是时间特征的一个良好示例。这些特征充当输入的“位置编码”。因此，与 BERT 等模型不同（其位置编码作为模型参数从内部从头学习），Time Series Transformer 需要额外提供时间特征。Time Series Transformer 仅为 `static_categorical_features` 学习额外的嵌入。可以将额外的动态实值协变量拼接到此张量中，但前提是这些特征在预测时必须已知。此处的 `num_features` 等于 `config.`num_time_features` + `config.num_dynamic_real_features`。

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : 元组由 `last_hidden_state`、`hidden_states`（*optional*）和 `attentions`（*optional*）组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`（*optional*），是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** [Seq2SeqTSModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `tuple(torch.Tensor)`

一个 [Seq2SeqTSModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[TimeSeriesTransformerConfig](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)）和输入。

[TimeSeriesTransformerModel](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型解码器最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/main/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  解码器在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  编码器每层输出处的隐藏状态，以及可选的初始嵌入输出。
- **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **loc** (`torch.Tensor`，形状为 `(batch_size,)` 或 `(batch_size, input_size)`，*可选*) -- 用于平移每个时间序列上下文窗口的值，以便为模型提供量级相同的输入，随后再平移回原始量级。
- **scale** (`torch.Tensor`，形状为 `(batch_size,)` 或 `(batch_size, input_size)`，*可选*) -- 用于缩放每个时间序列上下文窗口的值，以便为模型提供量级相同的输入，随后再用于将输出缩放回原始量级。
- **static_features** (`torch.Tensor`，形状为 `(batch_size, feature size)`，*可选*) -- 批次中每个时间序列的静态特征，在推理时会被复制到协变量中。

示例：

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = TimeSeriesTransformerModel.from_pretrained("huggingface/time-series-transformer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state
```

## TimeSeriesTransformerForPrediction[[transformers.TimeSeriesTransformerForPrediction]]

#### transformers.TimeSeriesTransformerForPrediction[[transformers.TimeSeriesTransformerForPrediction]]

```python
transformers.TimeSeriesTransformerForPrediction(config: TimeSeriesTransformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L1114)

**参数：**

config ([TimeSeriesTransformerConfig](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

带有分布头的时间序列 Transformer 模型，用于时间序列预测。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.TimeSeriesTransformerForPrediction.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, future_observed_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/time_series_transformer/modeling_time_series_transformer.py#L1148)

**参数：**

past_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)` 或 `(batch_size, sequence_length, input_size)`)：时间序列的过去值，作为上下文用于预测未来。该张量的序列大小必须大于模型的 `context_length`，因为模型将使用更大的大小来构建滞后特征，即从过去添加的额外值，用作“额外上下文”。此处的 `sequence_length` 等于 `config.context_length` + `max(config.lags_sequence)`；如果未配置 `lags_sequence`，则等于 `config.context_length` + 7（因为默认情况下，`config.lags_sequence` 中最大的回看索引为 7）。属性 `_past_length` 返回过去的实际长度。`past_values` 是 Transformer 编码器接收的输入（可包含额外特征，例如 `static_categorical_features`、`static_real_features`、`past_time_features` 和滞后值）。可选地，缺失值需要用零替换，并通过 `past_observed_mask` 进行指示。对于多变量时间序列，需要 `input_size` > 1 的维度，该维度对应于每个时间步中时间序列的变量数量。

past_time_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, num_features)`)：必需的时间特征，模型内部会将其添加到 `past_values` 中。这些特征可以是“一年中的月份”、“一个月中的日期”等，并以向量形式编码（例如作为傅里叶特征）。这些特征也可以是所谓的“年龄”特征，其基本作用是帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步，年龄特征的值较小，并且随着我们接近当前时间步而单调递增。节假日特征也是时间特征的一个良好示例。这些特征充当输入的“位置编码”。因此，与 BERT 等模型不同（后者的位置编码是作为模型参数从零开始内部学习的），Time Series Transformer 要求提供额外的时间特征。Time Series Transformer 仅为 `static_categorical_features` 学习额外的嵌入。可以将额外的动态实值协变量拼接到此张量中，但需注意这些特征必须在预测时已知。此处的 `num_features` 等于 `config.`num_time_features` + `config.num_dynamic_real_features`。

past_observed_mask (`torch.BoolTensor`，形状为 `(batch_size, sequence_length)` 或 `(batch_size, sequence_length, input_size)`，*可选*)：布尔掩码，用于指示哪些 `past_values` 是被观测到的，哪些是缺失的。掩码值在 `[0, 1]` 中选取： - 1 表示 **已观测** 的值， - 0 表示 **缺失** 的值（即被零替换的 NaN）。

static_categorical_features (`torch.LongTensor`，形状为 `(batch_size, number of static categorical features)`，*可选*)：可选的静态类别特征，模型将为其学习嵌入，并将其添加到时间序列的值中。静态类别特征是指在所有时间步上具有相同值的特征（即随时间保持静态）。静态类别特征的一个典型示例是时间序列 ID。

static_real_features (`torch.Tensor`，形状为 `(batch_size, number of static real features)`，*可选*)：可选的静态实值特征，模型会将其添加到时间序列的值中。静态实值特征是指在所有时间步上具有相同值的特征（即随时间保持静态）。静态实值特征的一个典型示例是促销信息。

future_values (`torch.Tensor`，形状为 `(batch_size, prediction_length)` 或 `(batch_size, prediction_length, input_size)`，*可选*) : 时间序列的未来值，用作模型的标签。`future_values` 是 Transformer 在训练期间需要学习输出的内容，其输入为 `past_values`。 此处的序列长度等于 `prediction_length`。 有关详细信息，请参阅演示笔记本和代码片段。 可选地，在训练期间，任何缺失值都需要用零替换，并通过 `future_observed_mask` 进行指示。 对于多元时间序列，需要 `input_size` > 1 维度，该维度对应于每个时间步中时间序列的变量数量。

future_time_features (`torch.Tensor`，形状为 `(batch_size, prediction_length, num_features)`)：预测窗口所需的时间特征，模型内部会将其添加到 `future_values` 中。这些特征可以是“一年中的月份”、“一个月中的日期”等，并以向量形式编码（例如作为傅里叶特征）。它们也可以是所谓的“年龄”特征，基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步，年龄特征的值较小，并且随着我们接近当前时间步而单调递增。节假日特征也是时间特征的一个良好示例。这些特征充当输入的“位置编码”。因此，与 BERT 等模型不同（其位置编码作为模型参数从内部从头学习），Time Series Transformer 需要额外提供时间特征。Time Series Transformer 仅为 `static_categorical_features` 学习额外的嵌入。可以将额外的动态实值协变量拼接到此张量中，但前提是这些特征在预测时必须已知。此处的 `num_features` 等于 `config.`num_time_features` + `config.num_dynamic_real_features`。

future_observed_mask (`torch.BoolTensor`，形状为 `(batch_size, sequence_length)` 或 `(batch_size, sequence_length, input_size)`，*可选*) : 布尔掩码，用于指示哪些 `future_values` 是被观测到的，哪些是缺失的。掩码值在 `[0, 1]` 中选取： - 1 表示 **已观测** 的值， - 0 表示 **缺失** 的值（即被零替换的 NaN）。 此掩码用于在最终损失计算中过滤掉缺失值。

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : 元组由 `last_hidden_state`、`hidden_states`（*optional*）和 `attentions`（*optional*）组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`（*optional*），是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** [Seq2SeqTSModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `tuple(torch.Tensor)`

一个 [Seq2SeqTSModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[TimeSeriesTransformerConfig](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerConfig)）和输入。

[TimeSeriesTransformerForPrediction](/docs/transformers/main/zh/model_doc/time_series_transformer#transformers.TimeSeriesTransformerForPrediction) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型解码器最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/main/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **decoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  解码器在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **decoder_attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  编码器每层输出处的隐藏状态，以及可选的初始嵌入输出。
- **encoder_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **loc** (`torch.Tensor`，形状为 `(batch_size,)` 或 `(batch_size, input_size)`，*可选*) -- 用于平移每个时间序列上下文窗口的值，以便为模型提供量级相同的输入，随后再平移回原始量级。
- **scale** (`torch.Tensor`，形状为 `(batch_size,)` 或 `(batch_size, input_size)`，*可选*) -- 用于缩放每个时间序列上下文窗口的值，以便为模型提供量级相同的输入，随后再用于将输出缩放回原始量级。
- **static_features** (`torch.Tensor`，形状为 `(batch_size, feature size)`，*可选*) -- 批次中每个时间序列的静态特征，在推理时会被复制到协变量中。

示例：

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import TimeSeriesTransformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = TimeSeriesTransformerForPrediction.from_pretrained(
...     "huggingface/time-series-transformer-tourism-monthly"
... )

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)
```