Hugging Face's logo

Transformers documentation

Informer

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
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→