Hugging Face's logo

Transformers documentation

时间序列 Transformer

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

该模型于 2022-09-30 贡献至 Hugging Face Transformers。

时间序列 Transformer

概述

Time Series Transformer 模型是一个用于时间序列预测的原始编码器-解码器 Transformer。 该模型由 kashif 贡献。

使用技巧

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

资源

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

TimeSeriesTransformerConfig

class transformers.TimeSeriesTransformerConfig

< >

( 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: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noneencoder_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'd_model: int = 64dropout: 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 = 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_categorical_features (int，可选，默认为 0) — 静态分类特征的数量。
  • num_static_real_features (int，可选，默认为 0) — 静态实值特征的数量。
  • num_time_features (int，可选，默认为 0) — 输入时间序列中时间特征的数量。
  • cardinality (list[int]，可选) — 每个静态分类特征的基数（不同取值的数量）。应为整数列表，其长度与 num_static_categorical_features 相同。如果 num_static_categorical_features > 0，则不能为 None。
  • embedding_dimension (list[int]，可选) — 嵌入和隐藏状态的维度。
  • encoder_ffn_dim (int，可选，默认为 32) — 编码器中“中间”（通常称为前馈）层的维度。
  • decoder_ffn_dim (int，可选，默认为 32) — 解码器中“中间”（通常称为前馈）层的维度。
  • encoder_attention_heads (int, 可选，默认为 2) — Transformer 编码器中每个注意力层的注意力头数量。
  • decoder_attention_heads (int，可选，默认为 2) — Transformer 解码器中每个注意力层的注意力头数量。
  • encoder_layers (int，可选，默认为 2) — Transformer 编码器中的隐藏层数量。如果未设置，将使用与 num_layers 相同的值。
  • decoder_layers (int, 可选，默认为 2) — Transformer 解码器中的隐藏层数量。如果未设置，将使用与 num_layers 相同的值。
  • activation_function (str，可选，默认为 gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu" 等。
  • d_model (int，可选，默认为 64) — 编码器层和池化层的维度。
  • dropout (Union[float, int]，可选，默认为 0.1) — 所有 dropout 层的比率。
  • encoder_layerdrop (Union[float, int]，可选，默认值为 0.1) — 编码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](参见 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 或模型为仅解码器生成式模型时相关。

这是用于存储 TimeSeriesTransformerModel 配置的类。它根据指定的参数实例化 Time Series Transformer 模型，并定义模型架构。使用默认值实例化配置将得到与 huggingface/time-series-transformer-tourism-monthly 类似的配置。

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

示例：

>>> from transformers import TimeSeriesTransformerConfig, TimeSeriesTransformerModel

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

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

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

TimeSeriesTransformerModel

class transformers.TimeSeriesTransformerModel

< >

( config: TimeSeriesTransformerConfig )

参数

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

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

该模型继承自 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 时），其包含的元素取决于配置（TimeSeriesTransformerConfig）和输入。

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

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

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

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

  • past_key_values（EncoderDecoderCache，可选，在传入 use_cache=True 或 config.use_cache=True 时返回）—— 它是一个 EncoderDecoderCache 实例。更多详情，请参阅我们的 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 TimeSeriesTransformerModel

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

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

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

>>> last_hidden_state = outputs.last_hidden_state

TimeSeriesTransformerForPrediction

class transformers.TimeSeriesTransformerForPrediction

< >

( config: TimeSeriesTransformerConfig )

参数

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

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

该模型继承自 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 时），其包含的元素取决于配置（TimeSeriesTransformerConfig）和输入。

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

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

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

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

  • past_key_values（EncoderDecoderCache，可选，在传入 use_cache=True 或 config.use_cache=True 时返回）—— 它是一个 EncoderDecoderCache 实例。更多详情，请参阅我们的 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 TimeSeriesTransformerForPrediction

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

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

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

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

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

>>> mean_prediction = outputs.sequences.mean(dim=1)
Update on GitHub

←PatchTST TimesFM→