Hugging Face's logo

Transformers documentation

Informer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2020-12-14 在 HF papers 上发表，并于 2023-03-08 贡献至 Hugging Face Transformers。

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 中提出。

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

该论文的摘要如下：

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

该模型由 elisim 和 kashif 贡献。 原始代码可在此处找到。

资源

以下是来自 Hugging Face 官方和社区（以 🌎 标识）的资源列表，可帮助你快速上手。如果你希望提交资源以收录在此处，欢迎随时发起 Pull Request，我们将进行审查！该资源最好能展示一些新内容，而不是重复现有资源。

InformerConfig

class transformers.InformerConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | None = Nonescaling: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_real_features: int = 0num_static_categorical_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2activation_function: str = 'gelu'dropout: float | int = 0.05encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = Trueattention_type: str = 'prob'sampling_factor: int = 5distil: bool = True )

参数

  • is_encoder_decoder (bool，可选，默认为 True) — 指示该模型是否用作编码器/解码器。
  • prediction_length (int, 可选) — 解码器的预测长度。换句话说，即模型的预测范围。该值通常由数据集决定，我们建议将其设置为合适的值。
  • 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 论文](参见 https://huggingface.co/papers/1909.11556)。
  • decoder_layerdrop (Union[float, int]，可选，默认值为 0.1) — 解码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](参见 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 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

示例：

>>> 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

class transformers.InformerModel

< >

( config: InformerConfig )

参数

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

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

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

参数

  • 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]:
    • 对于已观测的值，
    • 对于值为 缺失（即被零替换的 NaN）的情况，值为 0。
  • 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（形状为 (batch_size, target_sequence_length) 的 torch.LongTensor，可选） — 用于避免对特定 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 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入 past_key_values，则默认会初始化 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 或 tuple(torch.Tensor)

一个 Seq2SeqTSModelOutput 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（InformerConfig）和输入。

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 实例。更多详情，请参阅我们的 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)，可选) — 批次中每个时间序列的静态特征，在推理时会被复制到协变量中。

示例：

>>> 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

class transformers.InformerForPrediction

< >

( config: InformerConfig )

参数

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

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

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

参数

  • 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]:
    • 对于已观测的值，
    • 对于值为 缺失（即被零替换的 NaN）的情况，值为 0。
  • 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]:
    • 对于已观测的值，
    • 对于值为 缺失（即被零替换的 NaN）的情况，值为 0。

    此掩码用于在最终损失计算中过滤掉缺失值。

  • decoder_attention_mask（形状为 (batch_size, target_sequence_length) 的 torch.LongTensor，可选） — 用于避免对特定 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 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入 past_key_values，则默认会初始化 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 或 tuple(torch.Tensor)

一个 Seq2SeqTSModelOutput 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（InformerConfig）和输入。

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 实例。更多详情，请参阅我们的 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)，可选) — 批次中每个时间序列的静态特征，在推理时会被复制到协变量中。

示例：

>>> 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)
Update on GitHub

←Autoformer PatchTSMixer→