Transformers documentation

Autoformer

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2021-06-24 在 HF papers 上发布,并于 2023-05-30 贡献至 Hugging Face Transformers。

Autoformer

概述

Autoformer 模型由 Haixu Wu、Jiehui Xu、Jianmin Wang 和 Mingsheng Long 在 Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting 中提出。

该模型将 Transformer 扩展为一种深度分解架构,能够在预测过程中逐步分解趋势和季节性成分。

该论文的摘要如下:

延长预测时间范围是实际应用的迫切需求,例如极端天气预警和长期能源消耗规划。本文研究时间序列的长期预测问题。现有的基于 Transformer 的模型采用各种自注意力机制来发现长程依赖关系。然而,长期未来中复杂的时序模式使得模型难以找到可靠的依赖关系。此外,为了处理长序列的效率,Transformer 必须采用逐点自注意力的稀疏版本,这导致了信息利用的瓶颈。超越 Transformer,我们设计了 Autoformer,这是一种具有 Auto-Correlation 机制的新型分解架构。我们打破了序列分解作为预处理的惯例,将其改造为深度模型的基本内部模块。这一设计赋予 Autoformer 对复杂时间序列进行渐进式分解的能力。此外,受随机过程理论的启发,我们基于序列的周期性设计了 Auto-Correlation 机制,该机制在子序列层面进行依赖关系的发现和表示聚合。Auto-Correlation 在效率和准确性上均优于自注意力。在长期预测任务中,Autoformer 达到了最先进的精度,在涵盖能源、交通、经济、天气和疾病五个实际应用的六个基准测试上实现了 38% 的相对提升。

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

资源

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

AutoformerConfig

类 transformers.AutoformerConfig

< >

( 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] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: float | int = 0.1encoder_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 = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )

参数

  • is_encoder_decoder (bool,可选,默认为 True) — 指示该模型是否用作编码器/解码器。
  • prediction_length (int, 可选) — 解码器的预测长度。换句话说,即模型的预测范围。
  • context_length (int,可选,默认为 prediction_length) — 编码器的上下文长度。如果未设置,上下文长度将与 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 (bool,可选,默认为 True) — 是否对输入目标进行缩放。
  • num_time_features (int,可选,默认为 0) — 输入时间序列中时间特征的数量。
  • num_dynamic_real_features (int,可选,默认为 0) — 动态实值特征的数量。
  • num_static_categorical_features (int,可选,默认为 0) — 静态分类特征的数量。
  • num_static_real_features (int,可选,默认为 0) — 静态实值特征的数量。
  • cardinality (list[int],可选) — 每个静态分类特征的基数(不同取值的数量)。应为整数列表,其长度与 num_static_categorical_features 相同。如果 num_static_categorical_features > 0,则不能为 None。
  • embedding_dimension (list[int],可选) — 嵌入和隐藏状态的维度。
  • d_model (int,可选,默认为 64) — 编码器层和池化层的维度。
  • 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 相同的值。
  • encoder_ffn_dim (int,可选,默认为 32) — 编码器中“中间”(通常称为前馈)层的维度。
  • decoder_ffn_dim (int,可选,默认为 32) — 解码器中“中间”(通常称为前馈)层的维度。
  • activation_function (str,可选,默认为 gelu) — 解码器中的非线性激活函数(函数或字符串)。例如,"gelu"、"relu"、"silu" 等。
  • dropout (Union[float, int],可选,默认为 0.1) — 所有 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 (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 或模型为仅解码器生成式模型时相关。
  • label_length (int,可选,默认为 10) — Autoformer 解码器的起始 token 长度,用于直接多步预测(即非自回归生成)。
  • moving_average (int,可选,默认为 25) — 移动平均的窗口大小。实际上,它是 Decomposition Layer 中 AvgPool1d 的核大小。
  • autocorrelation_factor (int,可选,默认为 3) — “Attention”(即 AutoCorrelation 机制)因子,用于查找前 k 个自相关延迟。 论文建议将其设置为 1 到 5 之间的数值。

这是用于存储 AutoformerModel 配置的类。它根据指定的参数实例化 Autoformer 模型,并定义模型架构。使用默认值实例化配置将得到与 huggingface/autoformer-tourism-monthly 类似的配置。

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

示例:

>>> from transformers import AutoformerConfig, AutoformerModel

>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()

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

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

AutoformerModel

class transformers.AutoformerModel

< >

( config: AutoformerConfig )

参数

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

未添加任何特定头部的裸 Autoformer 模型,直接输出原始隐藏状态。

该模型继承自 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 = Nonecache: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → AutoformerModelOutput or tuple(torch.Tensor)

参数

  • past_values (torch.Tensor 形状为 (batch_size, sequence_length)) — 时间序列的过去值,作为上下文用于预测未来。这些值可能包含滞后项,即从过去添加的额外值,用作“额外上下文”。 past_values 是 Transformer 编码器接收的输入(可包含额外特征,例如 static_categorical_features, static_real_features, past_time_features).

    此处的序列长度等于 context_length + max(config.lags_sequence)。

    缺失值需要用零进行填充。

  • past_time_features (torch.Tensor 形状为 (batch_size, sequence_length, num_features), 可选) — 可选的时间特征,模型内部会将其添加到 past_values. 这些特征可以是“月份”、“日期”等,编码为向量(例如傅里叶特征)。它们也可以是所谓的“年龄”特征,基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步,年龄特征的值较小,并且随着我们接近当前时间步而单调递增。

    这些特征充当输入的“位置编码”。因此,与 BERT 等模型不同(其位置编码作为模型参数从零开始学习),Time Series Transformer 需要提供额外的时间特征。

    Autoformer 仅为 static_categorical_features 学习额外的嵌入。

  • past_observed_mask (torch.BoolTensor 形状为 (batch_size, sequence_length), 可选) — 布尔掩码,用于指示哪些 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)) — 时间序列的未来值,用作模型的标签。 future_values 是 Transformer 在给定 past_values.

    有关详细信息,请参阅演示笔记本和代码片段。

    缺失值需要用零进行填充。

  • future_time_features (torch.Tensor 形状为 (batch_size, prediction_length, num_features), 可选) — 可选的时间特征,模型内部会将其添加到 future_values. 这些特征可以是“月份”、“日期”等,以向量形式编码(例如傅里叶特征)。它们也可以是所谓的“年龄”特征,基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步,年龄特征的值较小,并且随着我们接近当前时间步而单调递增。

    这些特征充当输入的“位置编码”。因此,与 BERT 等模型不同(其位置编码作为模型参数从零开始学习),Time Series Transformer 需要提供额外的特征。

    Autoformer 仅为 static_categorical_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),是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。
  • cache (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常由 cache 在解码的先前阶段返回,当 use_cache=True 或 config.use_cache=True.

    仅允许将 Cache 实例作为输入,请参阅我们的 kv cache 指南。 如果未传入 cache,则默认会初始化 DynamicCache。

    模型将输出与输入相同的缓存格式。

    如果使用 cache,用户应仅输入未处理的 input_ids(即未向该模型提供其过去键值状态的那些),其形状为 (batch_size, unprocessed_length),而不是形状为 (batch_size, sequence_length) 的所有 input_ids。

  • use_cache (bool, 可选) — 如果设置为 True,则会返回 cache 键值状态,可用于加速解码(参见 cache)。

返回值

AutoformerModelOutput 或 tuple(torch.Tensor)

AutoformerModelOutput 或 torch.Tensor 元组(如果传入 return_dict=False 或 config.return_dict=False),包含根据配置(None)和输入而定的各种元素。

AutoformerModel 的 forward 方法重写了 __call__ 特殊方法。

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

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

    如果使用了cache,则仅输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。

  • trend(形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor)— 每个时间序列的趋势张量。

  • cache(Cache,可选,在传入 use_cache=True 或 config.use_cache=True 时返回)—— 它是一个 Cache 实例。更多详情,请参阅我们的 kv cache 指南。

    包含预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于(参见 cache 输入)加速顺序解码。

  • 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),可选): 批次中每个时间序列的静态特征,在推理时会被复制到协变量中。

  • static_features (torch.Tensor,形状为 (batch_size, feature size),可选) — 批次中每个时间序列的静态特征,在推理时会被复制到协变量中。

示例:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerModel

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

>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-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"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state

AutoformerForPrediction

class transformers.AutoformerForPrediction

< >

( config: AutoformerConfig )

参数

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

带有分布头(distribution head)的 Autoformer 模型,用于时间序列预测。

该模型继承自 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 = Nonecache: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)

参数

  • past_values (torch.Tensor 形状为 (batch_size, sequence_length)) — 时间序列的过去值,作为上下文用于预测未来。这些值可能包含滞后项,即从过去添加的额外值,用作“额外上下文”。 past_values 是 Transformer 编码器接收的输入(可包含额外特征,例如 static_categorical_features, static_real_features, past_time_features).

    此处的序列长度等于 context_length + max(config.lags_sequence)。

    缺失值需要用零进行填充。

  • past_time_features (torch.Tensor 形状为 (batch_size, sequence_length, num_features), 可选) — 可选的时间特征,模型内部会将其添加到 past_values. 这些特征可以是“月份”、“日期”等,编码为向量(例如傅里叶特征)。它们也可以是所谓的“年龄”特征,基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步,年龄特征的值较小,并且随着我们接近当前时间步而单调递增。

    这些特征充当输入的“位置编码”。因此,与 BERT 等模型不同(其位置编码作为模型参数从零开始学习),Time Series Transformer 需要提供额外的时间特征。

    Autoformer 仅为 static_categorical_features 学习额外的嵌入。

  • past_observed_mask (torch.BoolTensor 形状为 (batch_size, sequence_length), 可选) — 布尔掩码,用于指示哪些 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)) — 时间序列的未来值,用作模型的标签。 future_values 是 Transformer 在给定 past_values.

    有关详细信息,请参阅演示笔记本和代码片段。

    缺失值需要用零进行填充。

  • future_time_features (torch.Tensor 形状为 (batch_size, prediction_length, num_features), 可选) — 可选的时间特征,模型内部会将其添加到 future_values. 这些特征可以是“月份”、“日期”等,以向量形式编码(例如傅里叶特征)。它们也可以是所谓的“年龄”特征,基本上帮助模型了解时间序列处于“生命周期的哪个阶段”。对于遥远过去的时间步,年龄特征的值较小,并且随着我们接近当前时间步而单调递增。

    这些特征充当输入的“位置编码”。因此,与 BERT 等模型不同(其位置编码作为模型参数从零开始学习),Time Series Transformer 需要提供额外的特征。

    Autoformer 仅为 static_categorical_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),是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力。
  • cache (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常由 cache 在解码的先前阶段返回,当 use_cache=True 或 config.use_cache=True.

    仅允许将 Cache 实例作为输入,请参阅我们的 kv cache 指南。 如果未传入 cache,则默认会初始化 DynamicCache。

    模型将输出与输入相同的缓存格式。

    如果使用 cache,用户应仅输入未处理的 input_ids(即未向该模型提供其过去键值状态的那些),其形状为 (batch_size, unprocessed_length),而不是形状为 (batch_size, sequence_length) 的所有 input_ids。

  • use_cache (bool, 可选) — 如果设置为 True,则会返回 cache 键值状态,可用于加速解码(参见 cache)。

返回值

Seq2SeqTSPredictionOutput 或 tuple(torch.Tensor)

一个 Seq2SeqTSPredictionOutput 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(None)和输入。

AutoformerForPrediction 的 forward 方法重写了 __call__ 特殊方法。

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

  • loss (torch.Tensor,形状为 (1,),可选,在提供 future_values 时返回) — 分布损失。

  • params(形状为 (batch_size, num_samples, num_params) 的 torch.Tensor)— 所选分布的参数。

  • cache(EncoderDecoderCache,可选,在传入 use_cache=True 或 config.use_cache=True 时返回)— 它是一个 EncoderDecoderCache 实例。更多详情,请参阅我们的 kv cache 指南。

    包含预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于(参见 cache 输入)加速顺序解码。

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

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

>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-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"],
...     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"],
...     future_time_features=batch["future_time_features"],
... )

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

AutoformerForPrediction 也可以使用 static_real_features。为此,请根据数据集中此类特征的数量,在 AutoformerConfig 中设置 num_static_real_features(对于 tourism_monthly 数据集,

等于 1),初始化模型并按如下所示调用:

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerConfig, AutoformerForPrediction

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

>>> # check number of static real features
>>> num_static_real_features = batch["static_real_features"].shape[-1]

>>> # load configuration of pretrained model and override num_static_real_features
>>> configuration = AutoformerConfig.from_pretrained(
...     "huggingface/autoformer-tourism-monthly",
...     num_static_real_features=num_static_real_features,
... )
>>> # we also need to update feature_size as it is not recalculated
>>> configuration.feature_size += num_static_real_features

>>> model = AutoformerForPrediction(configuration)

>>> 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"],
... )
Update on GitHub