# Informer

## 概述

Informer 模型由 Haoyi Zhou、Shanghang Zhang、Jieqi Peng、Shuai Zhang、Jianxin Li、Hui Xiong 和 Wancai Zhang 在 [Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting](https://huggingface.co/papers/2012.07436) 中提出。

该方法引入了一种概率注意力机制，用于选择“活跃”查询而非“惰性”查询，从而提供了一种稀疏 Transformer，缓解了标准注意力机制的二次方计算和内存需求。

该论文的摘要如下：

*许多实际应用需要对长序列时间序列进行预测，例如电力消耗规划。长序列时间序列预测（LSTF）要求模型具备高预测能力，即高效地捕捉输出与输入之间精确的长程依赖耦合。近期研究表明，Transformer 在提升预测能力方面具有潜力。然而，Transformer 存在若干严重问题，使其无法直接应用于 LSTF，包括二次时间复杂度、高内存占用以及编码器-解码器架构的固有局限性。为解决这些问题，我们设计了一种用于 LSTF 的高效基于 Transformer 的模型，命名为 Informer，它具有三个显著特征：(i) ProbSparse 自注意力机制，在时间复杂度和内存占用上均达到 O(L logL)，并且在序列依赖对齐方面具有可比的性能。(ii) 自注意力蒸馏通过级联层输入减半来突出主导注意力，并高效处理极长的输入序列。(iii) 生成式解码器，虽然概念简单，但通过一次前向操作而非逐步方式预测长时间序列，从而大幅提升了长序列预测的推理速度。在四个大规模数据集上的大量实验表明，Informer 显著优于现有方法，并为 LSTF 问题提供了一种新的解决方案。*

该模型由 [elisim](https://huggingface.co/elisim) 和 [kashif](https://huggingface.co/kashif) 贡献。原始代码可在[此处](https://github.com/zhouhaoyi/Informer2020)找到。

## 资源

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

- 查看 HuggingFace 博客上的 Informer 博文：[使用 Informer 进行多元概率时间序列预测](https://huggingface.co/blog/informer)

## InformerConfig[[transformers.InformerConfig]]

#### transformers.InformerConfig[[transformers.InformerConfig]]

```python
transformers.InformerConfig(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] | None = None, scaling: str | bool | None = 'mean', num_dynamic_real_features: int = 0, num_static_real_features: int = 0, num_static_categorical_features: int = 0, num_time_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, d_model: int = 64, 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', dropout: float | int = 0.05, 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, attention_type: str = 'prob', sampling_factor: int = 5, distil: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/configuration_informer.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_real_features (`int`，*可选*，默认为 0)：静态实值特征的数量。

num_static_categorical_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]`, *可选*) : 每个静态分类特征的嵌入维度。应为整数列表，其长度与 `num_static_categorical_features` 相同。如果 `num_static_categorical_features` > 0，则不能为 `None`。

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

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"` 等。

dropout (`Union[float, int]`，*可选*，默认值为 `0.05`)：所有 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 (`float`, *可选*，默认为 0.1)：前馈网络两层之间使用的 dropout 概率。

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

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

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

attention_type (`str`, *可选*, 默认为 "prob") : 编码器中使用的注意力机制。可以设置为 "prob"（Informer 的 ProbAttention）或 "full"（标准 Transformer 的常规自注意力）。

sampling_factor (`int`, *可选*，默认为 5)：ProbSparse 采样因子（仅在 `attention_type`="prob" 时生效）。用于控制缩减后的查询矩阵（Q_reduce）的输入长度。

distil (`bool`, *可选*, 默认为 `True`) : 是否在编码器中使用蒸馏。

这是用于存储 InformerModel 配置的类。它根据指定的参数实例化 Informer 模型，并定义模型架构。使用默认值实例化配置将生成与 [huggingface/informer-tourism-monthly](https://huggingface.co/huggingface/informer-tourism-monthly) 类似的配置。

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

示例：

```python
>>> from transformers import InformerConfig, InformerModel

>>> # Initializing an Informer configuration with 12 time steps for prediction
>>> configuration = InformerConfig(prediction_length=12)

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

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

## InformerModel[[transformers.InformerModel]]

#### transformers.InformerModel[[transformers.InformerModel]]

```python
transformers.InformerModel(config: InformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L994)

**参数：**

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

未附加任何特定头部的裸 Informer 模型，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/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.InformerModel.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/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1132)

**参数：**

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/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/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/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `tuple(torch.Tensor)`

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

[InformerModel](/docs/transformers/v5.23.0/zh/model_doc/informer#transformers.InformerModel) 的 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/v5.23.0/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 InformerModel

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

>>> model = InformerModel.from_pretrained("huggingface/informer-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
```

## InformerForPrediction[[transformers.InformerForPrediction]]

#### transformers.InformerForPrediction[[transformers.InformerForPrediction]]

```python
transformers.InformerForPrediction(config: InformerConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1357)

**参数：**

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

用于时间序列预测的 Informer 模型，其顶部带有分布头。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/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.InformerForPrediction.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/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1392)

**参数：**

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/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/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/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) 或 `tuple(torch.Tensor)`

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

[InformerForPrediction](/docs/transformers/v5.23.0/zh/model_doc/informer#transformers.InformerForPrediction) 的 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/v5.23.0/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 InformerForPrediction

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

>>> model = InformerForPrediction.from_pretrained(
...     "huggingface/informer-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)
```

