Hugging Face 的 LOGO

Transformers 文件

時間序列 Transformer

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

時間序列 Transformer

PyTorch

概述

時間序列 Transformer 模型是一個用於時間序列預測的普通編碼器-解碼器 Transformer。此模型由 kashif 貢獻。

使用技巧

  • 與庫中的其他模型類似，TimeSeriesTransformerModel 是沒有頂部的原始 Transformer，而 TimeSeriesTransformerForPrediction 在前者之上添加了一個分佈頭，可用於時間序列預測。請注意，這是一個所謂的機率預測模型，而不是點預測模型。這意味著模型學習一個分佈，可以從中取樣。模型不直接輸出值。
  • TimeSeriesTransformerForPrediction 由 2 個模組組成：一個編碼器，它接收 context_length 的時間序列值作為輸入（稱為 past_values），以及一個解碼器，它預測未來 prediction_length 的時間序列值（稱為 future_values）。在訓練期間，需要向模型提供（past_values 和 future_values）對。
  • 除了原始的（past_values 和 future_values），通常還會向模型提供額外的特徵。這些特徵可以是以下幾種
    • 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 嵌入，如果您的時間序列是關於鞋子銷售的）。請注意，這些特徵需要對所有資料點（也包括未來的資料點）都已知。
  • 該模型使用“教師強制”進行訓練，類似於 Transformer 用於機器翻譯的訓練方式。這意味著，在訓練期間，將 future_values 向右移動一個位置作為解碼器的輸入，並在前面加上 past_values 的最後一個值。在每個時間步，模型需要預測下一個目標。因此，訓練設定類似於用於語言的 GPT 模型，除了沒有 decoder_start_token_id 的概念（我們只使用上下文的最後一個值作為解碼器的初始輸入）。
  • 在推理時，我們將 past_values 的最終值作為輸入提供給解碼器。接下來，我們可以從模型中取樣以在下一個時間步進行預測，然後將其輸入到解碼器以進行下一個預測（也稱為自迴歸生成）。

資源

官方 Hugging Face 和社群（用 🌎 表示）資源的列表，以幫助您入門。如果您有興趣提交資源以包含在此處，請隨時開啟拉取請求，我們將對其進行審查！該資源應理想地展示一些新內容，而不是重複現有資源。

TimeSeriesTransformerConfig

class transformers.TimeSeriesTransformerConfig

< >

( prediction_length: typing.Optional[int] = None context_length: typing.Optional[int] = None distribution_output: str = 'student_t' loss: str = 'nll' input_size: int = 1 lags_sequence: list = [1, 2, 3, 4, 5, 6, 7] scaling: typing.Union[str, bool, NoneType] = '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: typing.Optional[list[int]] = None embedding_dimension: typing.Optional[list[int]] = None encoder_ffn_dim: int = 32 decoder_ffn_dim: int = 32 encoder_attention_heads: int = 2 decoder_attention_heads: int = 2 encoder_layers: int = 2 decoder_layers: int = 2 is_encoder_decoder: bool = True activation_function: str = 'gelu' d_model: int = 64 dropout: float = 0.1 encoder_layerdrop: float = 0.1 decoder_layerdrop: float = 0.1 attention_dropout: float = 0.1 activation_dropout: float = 0.1 num_parallel_samples: int = 100 init_std: float = 0.02 use_cache = True **kwargs )

引數

  • 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。
  • scaling (string 或 bool, 可選，預設為 "mean") — 是否透過“均值”縮放器、“標準差”縮放器或不使用縮放器（如果為 None）來縮放輸入目標。如果為 True，則縮放器設定為“均值”。
  • lags_sequence (list[int], 可選, 預設為 [1, 2, 3, 4, 5, 6, 7]) — 輸入時間序列的滯後，通常由資料頻率決定。預設值為 [1, 2, 3, 4, 5, 6, 7]，但我們建議根據資料集適當更改。
  • 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], 可選) — 每個靜態分類特徵嵌入的維度。應該是一個整數列表，長度與 num_static_categorical_features 相同。如果 num_static_categorical_features 大於 0，則不能為 None。
  • d_model (int, 可選, 預設為 64) — Transformer 層的維度。
  • encoder_layers (int, 可選, 預設為 2) — 編碼器層數。
  • decoder_layers (int, 可選, 預設為 2) — 解碼器層數。
  • encoder_attention_heads (int, 可選, 預設為 2) — Transformer 編碼器中每個注意力層的注意力頭數量。
  • decoder_attention_heads (int, 可選, 預設為 2) — Transformer 解碼器中每個注意力層的注意力頭數量。
  • encoder_ffn_dim (int, 可選, 預設為 32) — 編碼器中“中間”（通常稱為前饋）層的維度。
  • decoder_ffn_dim (int, 可選, 預設為 32) — 解碼器中“中間”（通常稱為前饋）層的維度。
  • activation_function (str 或 function, 可選, 預設為 "gelu") — 編碼器和解碼器中的非線性啟用函式（函式或字串）。如果是字串，支援 "gelu" 和 "relu"。
  • dropout (float, 可選, 預設為 0.1) — 編碼器和解碼器中所有全連線層的 dropout 機率。
  • encoder_layerdrop (float, 可選, 預設為 0.1) — 每個編碼器層的注意力和全連線層的 dropout 機率。
  • decoder_layerdrop (float, 可選, 預設為 0.1) — 每個解碼器層的注意力和全連線層的 dropout 機率。
  • attention_dropout (float, 可選, 預設為 0.1) — 注意力機率的 dropout 機率。
  • activation_dropout (float, 可選, 預設為 0.1) — 前饋網路的兩個層之間使用的 dropout 機率。
  • num_parallel_samples (int, 可選, 預設為 100) — 每個推理時間步並行生成的樣本數量。
  • init_std (float, 可選, 預設為 0.02) — 截斷正態權重初始化分佈的標準差。
  • use_cache (bool, 可選, 預設為 True) — 是否使用過去的鍵/值注意力（如果適用於模型）來加速解碼。
  • 示例 —

這是一個配置類，用於儲存 TimeSeriesTransformerModel 的配置。它用於根據指定的引數例項化一個時間序列 Transformer 模型，定義模型架構。使用預設值例項化配置將產生與時間序列 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() 方法來載入模型權重。

純時間序列 Transformer 模型，輸出原始隱藏狀態，沒有任何特定的頭部。

該模型繼承自 PreTrainedModel。請檢視超類文件，瞭解庫為所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。

該模型也是 PyTorch torch.nn.Module 的子類。請將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件以瞭解與通用用法和行為相關的所有事項。

前向傳播

< >

( past_values: Tensor past_time_features: Tensor past_observed_mask: Tensor static_categorical_features: typing.Optional[torch.Tensor] = None static_real_features: typing.Optional[torch.Tensor] = None future_values: typing.Optional[torch.Tensor] = None future_time_features: typing.Optional[torch.Tensor] = None decoder_attention_mask: typing.Optional[torch.LongTensor] = None head_mask: typing.Optional[torch.Tensor] = None decoder_head_mask: typing.Optional[torch.Tensor] = None cross_attn_head_mask: typing.Optional[torch.Tensor] = None encoder_outputs: typing.Optional[list[torch.FloatTensor]] = None past_key_values: typing.Optional[list[torch.FloatTensor]] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None use_cache: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None ) → transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

引數

  • past_values (torch.FloatTensor，形狀為 (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.FloatTensor，形狀為 (batch_size, sequence_length, num_features)) — 所需的時間特徵，模型將在內部將其新增到 past_values。這些可以是“月份中的日期”、“一年中的日期”等編碼為向量（例如作為傅立葉特徵）。這些也可以是所謂的“年齡”特徵，它們基本上幫助模型知道時間序列處於“生命中的哪個點”。年齡特徵對於遙遠的過去時間步具有小值，並且隨著我們接近當前時間步而單調增加。假日特徵也是時間特徵的一個很好的例子。

    這些特徵作為輸入的“位置編碼”。因此，與 BERT 這樣的模型不同，BERT 的位置編碼在內部從頭開始作為模型引數學習，時間序列 Transformer 需要提供額外的時間特徵。時間序列 Transformer 只學習 static_categorical_features 的額外嵌入。

    額外的動態實值協變數可以連線到此張量，但需要注意的是，這些特徵必須在預測時已知。

    這裡的 num_features 等於 config.num_time_features+config.num_dynamic_real_features`。

  • past_observed_mask (形狀為 (batch_size, sequence_length) 或 (batch_size, sequence_length, input_size) 的 torch.BoolTensor，可選) — 布林掩碼，指示哪些 past_values 被觀察到，哪些缺失。掩碼值選自 [0, 1]：

    • 1 表示值被**觀察到**，
    • 0 表示值**缺失**（即被零替換的 NaNs）。
  • static_categorical_features (形狀為 (batch_size, 靜態類別特徵數量) 的 torch.LongTensor，可選) — 可選的靜態類別特徵，模型將為其學習嵌入，並將其新增到時間序列的值中。

    靜態類別特徵是在所有時間步中具有相同值的特徵（隨時間保持靜態）。

    靜態類別特徵的典型示例是時間序列 ID。

  • static_real_features (形狀為 (batch_size, 靜態實數特徵數量) 的 torch.FloatTensor，可選) — 可選的靜態實數特徵，模型將將其新增到時間序列的值中。

    靜態實數特徵是在所有時間步中具有相同值的特徵（隨時間保持靜態）。

    靜態實數特徵的典型示例是促銷資訊。

  • future_values (形狀為 (batch_size, prediction_length) 或 (batch_size, prediction_length, input_size) 的 torch.FloatTensor，可選) — 時間序列的未來值，用作模型的標籤。future_values 是 Transformer 在訓練期間需要學習輸出的內容，給定 past_values。

    這裡的序列長度等於 prediction_length。

    有關詳細資訊，請參閱演示筆記本和程式碼片段。

    可選地，在訓練期間，任何缺失值都需要用零替換，並透過 future_observed_mask 指示。

    對於多元時間序列，需要 input_size > 1 維度，並且對應於每個時間步中時間序列的變數數量。

  • future_time_features (形狀為 (batch_size, prediction_length, num_features) 的 torch.FloatTensor) — 預測視窗所需的時序特徵，模型將在內部將其新增到 future_values 中。這些特徵可以是“年份中的月份”、“月份中的日期”等，編碼為向量（例如作為傅立葉特徵）。這些也可以是所謂的“年齡”特徵，它們基本上幫助模型瞭解時間序列處於“生命中的哪個階段”。年齡特徵對於遙遠的過去時間步具有較小的值，並且隨著我們接近當前時間步而單調增加。假日特徵也是時序特徵的一個很好的例子。

    這些特徵作為輸入的“位置編碼”。因此，與 BERT 等模型不同，BERT 中的位置編碼是模型內部從頭開始學習的引數，時間序列 Transformer 需要提供額外的時序特徵。時間序列 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，可選) — 掩碼，用於避免對某些詞元索引執行注意力。預設情況下，將使用因果掩碼，以確保模型只能檢視先前的輸入才能預測未來。
  • head_mask (形狀為 (num_heads,) 或 (num_layers, num_heads) 的 torch.Tensor，可選) — 用於使自注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • decoder_head_mask (形狀為 (decoder_layers, decoder_attention_heads) 的 torch.Tensor，可選) — 用於使解碼器中注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • cross_attn_head_mask (形狀為 (decoder_layers, decoder_attention_heads) 的 torch.Tensor，可選) — 用於使交叉注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • encoder_outputs (tuple(tuple(torch.FloatTensor)，可選) — 元組包含 last_hidden_state、hidden_states（可選）和 attentions（可選）。形狀為 (batch_size, sequence_length, hidden_size) 的 last_hidden_state（可選）是編碼器最後一層輸出的隱藏狀態序列。用於解碼器的交叉注意力。
  • past_key_values (list[torch.FloatTensor], 可選) — 預計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速序列解碼。這通常包含模型在解碼的先前階段返回的 past_key_values，當 use_cache=True 或 config.use_cache=True 時。

    允許兩種格式：

    • Cache 例項，詳見我們的 kv cache 指南；
    • 長度為 config.n_layers 的 tuple(torch.FloatTensor) 元組，每個元組包含 2 個形狀為 (batch_size, num_heads, sequence_length, embed_size_per_head) 的張量。這也稱為傳統快取格式。

    模型將輸出與輸入相同的快取格式。如果未傳入 past_key_values，將返回傳統快取格式。

    如果使用 past_key_values，使用者可以選擇只輸入形狀為 (batch_size, 1) 的最後一個 input_ids（那些沒有將其過去的鍵值狀態提供給此模型的），而不是形狀為 (batch_size, sequence_length) 的所有 input_ids。

  • output_hidden_states (bool，可選) — 是否返回所有層的隱藏狀態。有關更多詳細資訊，請參閱返回張量下的 hidden_states。
  • output_attentions (bool，可選) — 是否返回所有注意力層的注意力張量。有關更多詳細資訊，請參閱返回張量下的 attentions。
  • use_cache (bool，可選) — 如果設定為 True，則返回 past_key_values 鍵值狀態，可用於加速解碼（參見 past_key_values）。
  • return_dict (bool，可選) — 是否返回 ModelOutput 而不是普通元組。
  • cache_position (形狀為 (sequence_length) 的 torch.LongTensor，可選) — 描述輸入序列詞元在序列中位置的索引。與 position_ids 不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整序列長度。

返回

transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

一個 transformers.modeling_outputs.Seq2SeqTSModelOutput 或一個 torch.FloatTensor 元組（如果傳入 return_dict=False 或 config.return_dict=False），包含根據配置 (TimeSeriesTransformerConfig) 和輸入而變化的各種元素。

  • last_hidden_state (torch.FloatTensor，形狀為 (batch_size, sequence_length, hidden_size)) — 模型解碼器最後一層輸出的隱藏狀態序列。

    如果使用了 past_key_values，則只輸出形狀為 (batch_size, 1, hidden_size) 的序列的最後一個隱藏狀態。

  • past_key_values (EncoderDecoderCache，可選，當傳入 use_cache=True 或 config.use_cache=True 時返回) — 它是 EncoderDecoderCache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。

    包含預先計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於（參見 past_key_values 輸入）加速順序解碼。

  • decoder_hidden_states (tuple(torch.FloatTensor)，可選，當傳入 output_hidden_states=True 或 config.output_hidden_states=True 時返回) — torch.FloatTensor 元組（一個用於嵌入層輸出，如果模型有嵌入層，+ 一個用於每個層輸出），形狀為 (batch_size, sequence_length, hidden_size)。

    解碼器在每個層輸出的隱藏狀態，加上可選的初始嵌入輸出。

  • decoder_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    解碼器的注意力權重，在注意力 softmax 之後，用於計算自注意力頭中的加權平均。

  • cross_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    解碼器交叉注意力層的注意力權重，在注意力 softmax 之後，用於計算交叉注意力頭中的加權平均。

  • encoder_last_hidden_state (torch.FloatTensor，形狀為 (batch_size, sequence_length, hidden_size)，可選) — 模型編碼器最後一層輸出的隱藏狀態序列。

  • encoder_hidden_states (tuple(torch.FloatTensor)，可選，當傳入 output_hidden_states=True 或 config.output_hidden_states=True 時返回) — torch.FloatTensor 元組（一個用於嵌入層輸出，如果模型有嵌入層，+ 一個用於每個層輸出），形狀為 (batch_size, sequence_length, hidden_size)。

    編碼器在每個層輸出的隱藏狀態，加上可選的初始嵌入輸出。

  • encoder_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    編碼器的注意力權重，在注意力 softmax 之後，用於計算自注意力頭中的加權平均。

  • loc (形狀為 (batch_size,) 或 (batch_size, input_size) 的 torch.FloatTensor，可選) — 每個時間序列上下文視窗的平移值，用於使模型輸入具有相同的大小，然後用於將其平移回原始大小。

  • scale (形狀為 (batch_size,) 或 (batch_size, input_size) 的 torch.FloatTensor，可選) — 每個時間序列上下文視窗的縮放值，用於使模型輸入具有相同的大小，然後用於將其縮放回原始大小。

  • static_features (torch.FloatTensor，形狀為 (batch_size, feature size)，可選) — 批次中每個時間序列的靜態特徵，在推理時複製到協變數。

TimeSeriesTransformerModel 的 forward 方法，重寫了 __call__ 特殊方法。

儘管前向傳播的配方需要在該函式中定義，但在此之後應呼叫 Module 例項，而不是該函式，因為前者負責執行預處理和後處理步驟，而後者則靜默忽略它們。

示例

>>> 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 模組使用，並參考 PyTorch 文件以瞭解與通用用法和行為相關的所有事項。

前向傳播

 < >

( past_values: Tensor past_time_features: Tensor past_observed_mask: Tensor static_categorical_features: typing.Optional[torch.Tensor] = None static_real_features: typing.Optional[torch.Tensor] = None future_values: typing.Optional[torch.Tensor] = None future_time_features: typing.Optional[torch.Tensor] = None future_observed_mask: typing.Optional[torch.Tensor] = None decoder_attention_mask: typing.Optional[torch.LongTensor] = None head_mask: typing.Optional[torch.Tensor] = None decoder_head_mask: typing.Optional[torch.Tensor] = None cross_attn_head_mask: typing.Optional[torch.Tensor] = None encoder_outputs: typing.Optional[list[torch.FloatTensor]] = None past_key_values: typing.Optional[list[torch.FloatTensor]] = None output_hidden_states: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None use_cache: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None ) → transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

引數

  • past_values (形狀為 (batch_size, sequence_length) 或 (batch_size, sequence_length, input_size) 的 torch.FloatTensor) — 時間序列的過去值，用作預測未來的上下文。此張量的序列大小必須大於模型的 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 (形狀為 (batch_size, sequence_length, num_features) 的 torch.FloatTensor) — 所需的時序特徵，模型將在內部將其新增到 past_values 中。這些特徵可以是“年份中的月份”、“月份中的日期”等，編碼為向量（例如作為傅立葉特徵）。這些也可以是所謂的“年齡”特徵，它們基本上幫助模型瞭解時間序列處於“生命中的哪個階段”。年齡特徵對於遙遠的過去時間步具有較小的值，並且隨著我們接近當前時間步而單調增加。假日特徵也是時序特徵的一個很好的例子。

    這些特徵作為輸入的“位置編碼”。因此，與 BERT 等模型不同，BERT 中的位置編碼是模型內部從頭開始學習的引數，時間序列 Transformer 需要提供額外的時序特徵。時間序列 Transformer 僅為 static_categorical_features 學習額外的嵌入。

    附加的動態實數協變數可以連線到此張量，但需要注意的是，這些特徵必須在預測時已知。

    這裡的 num_features 等於 config.num_time_features + config.num_dynamic_real_features。

  • past_observed_mask (形狀為 (batch_size, sequence_length) 或 (batch_size, sequence_length, input_size) 的 torch.BoolTensor，可選) — 布林掩碼，指示哪些 past_values 被觀察到，哪些缺失。掩碼值選自 [0, 1]：

    • 1 表示值被**觀察到**，
    • 0 表示值**缺失**（即被零替換的 NaNs）。
  • static_categorical_features (形狀為 (batch_size, 靜態類別特徵數量) 的 torch.LongTensor，可選) — 可選的靜態類別特徵，模型將為其學習嵌入，並將其新增到時間序列的值中。

    靜態類別特徵是在所有時間步中具有相同值的特徵（隨時間保持靜態）。

    靜態類別特徵的典型示例是時間序列 ID。

  • static_real_features (形狀為 (batch_size, 靜態實數特徵數量) 的 torch.FloatTensor，可選) — 可選的靜態實數特徵，模型將將其新增到時間序列的值中。

    靜態實數特徵是在所有時間步中具有相同值的特徵（隨時間保持靜態）。

    靜態實數特徵的典型示例是促銷資訊。

  • future_values (形狀為 (batch_size, prediction_length) 或 (batch_size, prediction_length, input_size) 的 torch.FloatTensor，可選) — 時間序列的未來值，用作模型的標籤。future_values 是 Transformer 在訓練期間需要學習輸出的內容，給定 past_values。

    這裡的序列長度等於 prediction_length。

    有關詳細資訊，請參閱演示筆記本和程式碼片段。

    可選地，在訓練期間，任何缺失值都需要用零替換，並透過 future_observed_mask 指示。

    對於多元時間序列，需要 input_size > 1 維度，並且對應於每個時間步中時間序列的變數數量。

  • future_time_features (形狀為 (batch_size, prediction_length, num_features) 的 torch.FloatTensor) — 預測視窗所需的時序特徵，模型將在內部將其新增到 future_values 中。這些特徵可以是“年份中的月份”、“月份中的日期”等，編碼為向量（例如作為傅立葉特徵）。這些也可以是所謂的“年齡”特徵，它們基本上幫助模型瞭解時間序列處於“生命中的哪個階段”。年齡特徵對於遙遠的過去時間步具有較小的值，並且隨著我們接近當前時間步而單調增加。假日特徵也是時序特徵的一個很好的例子。

    這些特徵作為輸入的“位置編碼”。因此，與 BERT 等模型不同，BERT 中的位置編碼是模型內部從頭開始學習的引數，時間序列 Transformer 需要提供額外的時序特徵。時間序列 Transformer 僅為 static_categorical_features 學習額外的嵌入。

    附加的動態實數協變數可以連線到此張量，但需要注意的是，這些特徵必須在預測時已知。

    這裡的 num_features 等於 config.num_time_features + config.num_dynamic_real_features。

  • future_observed_mask (形狀為 (batch_size, sequence_length) 或 (batch_size, sequence_length, input_size) 的 torch.BoolTensor，可選) — 布林掩碼，指示哪些 future_values 被觀察到，哪些缺失。掩碼值選自 [0, 1]：

    • 1 表示值被**觀察到**，
    • 0 表示值**缺失**（即被零替換的 NaNs）。

    此掩碼用於過濾掉缺失值以進行最終損失計算。

  • decoder_attention_mask (形狀為 (batch_size, target_sequence_length) 的 torch.LongTensor，可選) — 掩碼，用於避免對某些詞元索引執行注意力。預設情況下，將使用因果掩碼，以確保模型只能檢視先前的輸入才能預測未來。
  • head_mask (形狀為 (num_heads,) 或 (num_layers, num_heads) 的 torch.Tensor，可選) — 用於使自注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • decoder_head_mask (形狀為 (decoder_layers, decoder_attention_heads) 的 torch.Tensor，可選) — 用於使解碼器中注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • cross_attn_head_mask (形狀為 (decoder_layers, decoder_attention_heads) 的 torch.Tensor，可選) — 用於使交叉注意力模組的選定頭部無效的掩碼。掩碼值選自 [0, 1]：

    • 1 表示頭部**未被掩碼**，
    • 0 表示頭部**被掩碼**。
  • encoder_outputs (tuple(tuple(torch.FloatTensor)，可選) — 元組包含 last_hidden_state、hidden_states（可選）和 attentions（可選）。形狀為 (batch_size, sequence_length, hidden_size) 的 last_hidden_state（可選）是編碼器最後一層輸出的隱藏狀態序列。用於解碼器的交叉注意力。
  • past_key_values (list[torch.FloatTensor]，可選) — 預計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速序列解碼。這通常包含模型在解碼的先前階段返回的 past_key_values，當 use_cache=True 或 config.use_cache=True 時。

    允許兩種格式：

    • Cache 例項，詳見我們的 kv 快取指南；
    • 長度為 config.n_layers 的 tuple(torch.FloatTensor) 元組，每個元組包含 2 個形狀為 (batch_size, num_heads, sequence_length, embed_size_per_head) 的張量。這也稱為傳統快取格式。

    模型將輸出與輸入相同的快取格式。如果未傳入 past_key_values，將返回傳統快取格式。

    如果使用 past_key_values，使用者可以選擇只輸入形狀為 (batch_size, 1) 的最後一個 input_ids（那些沒有將其過去的鍵值狀態提供給此模型的），而不是形狀為 (batch_size, sequence_length) 的所有 input_ids。

  • output_hidden_states (bool，可選) — 是否返回所有層的隱藏狀態。有關更多詳細資訊，請參閱返回張量下的 hidden_states。
  • output_attentions (bool，可選) — 是否返回所有注意力層的注意力張量。有關更多詳細資訊，請參閱返回張量下的 attentions。
  • use_cache (bool，可選) — 如果設定為 True，則返回 past_key_values 鍵值狀態，可用於加速解碼（參見 past_key_values）。
  • return_dict (bool，可選) — 是否返回 ModelOutput 而不是普通元組。
  • cache_position (形狀為 (sequence_length) 的 torch.LongTensor，可選) — 描述輸入序列詞元在序列中位置的索引。與 position_ids 不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整序列長度。

返回

transformers.modeling_outputs.Seq2SeqTSModelOutput 或 tuple(torch.FloatTensor)

一個 transformers.modeling_outputs.Seq2SeqTSModelOutput 或一個 torch.FloatTensor 元組（如果傳入 return_dict=False 或 config.return_dict=False），包含根據配置 (TimeSeriesTransformerConfig) 和輸入而變化的各種元素。

  • last_hidden_state (torch.FloatTensor，形狀為 (batch_size, sequence_length, hidden_size)) — 模型解碼器最後一層輸出的隱藏狀態序列。

    如果使用了 past_key_values，則只輸出形狀為 (batch_size, 1, hidden_size) 的序列的最後一個隱藏狀態。

  • past_key_values (EncoderDecoderCache，可選，當傳入 use_cache=True 或 config.use_cache=True 時返回) — 它是 EncoderDecoderCache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。

    包含預先計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於（參見 past_key_values 輸入）加速順序解碼。

  • decoder_hidden_states (tuple(torch.FloatTensor)，可選，當傳入 output_hidden_states=True 或 config.output_hidden_states=True 時返回) — torch.FloatTensor 元組（一個用於嵌入層輸出，如果模型有嵌入層，+ 一個用於每個層輸出），形狀為 (batch_size, sequence_length, hidden_size)。

    解碼器在每個層輸出的隱藏狀態，加上可選的初始嵌入輸出。

  • decoder_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    解碼器的注意力權重，在注意力 softmax 之後，用於計算自注意力頭中的加權平均。

  • cross_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    解碼器交叉注意力層的注意力權重，在注意力 softmax 之後，用於計算交叉注意力頭中的加權平均。

  • encoder_last_hidden_state (torch.FloatTensor，形狀為 (batch_size, sequence_length, hidden_size)，可選) — 模型編碼器最後一層輸出的隱藏狀態序列。

  • encoder_hidden_states (tuple(torch.FloatTensor)，可選，當傳入 output_hidden_states=True 或 config.output_hidden_states=True 時返回) — torch.FloatTensor 元組（一個用於嵌入層輸出，如果模型有嵌入層，+ 一個用於每個層輸出），形狀為 (batch_size, sequence_length, hidden_size)。

    編碼器在每個層輸出的隱藏狀態，加上可選的初始嵌入輸出。

  • encoder_attentions (tuple(torch.FloatTensor)，可選，當傳入 output_attentions=True 或 config.output_attentions=True 時返回) — torch.FloatTensor 元組（每個層一個），形狀為 (batch_size, num_heads, sequence_length, sequence_length)。

    編碼器的注意力權重，在注意力 softmax 之後，用於計算自注意力頭中的加權平均。

  • loc (形狀為 (batch_size,) 或 (batch_size, input_size) 的 torch.FloatTensor，可選) — 每個時間序列上下文視窗的平移值，用於使模型輸入具有相同的大小，然後用於將其平移回原始大小。

  • scale (形狀為 (batch_size,) 或 (batch_size, input_size) 的 torch.FloatTensor，可選) — 每個時間序列上下文視窗的縮放值，用於使模型輸入具有相同的大小，然後用於將其縮放回原始大小。

  • static_features (torch.FloatTensor，形狀為 (batch_size, feature size)，可選) — 批次中每個時間序列的靜態特徵，在推理時複製到協變數。

TimeSeriesTransformerForPrediction 的 forward 方法，重寫了 __call__ 特殊方法。

儘管前向傳播的配方需要在該函式中定義，但在此之後應呼叫 Module 例項，而不是該函式，因為前者負責執行預處理和後處理步驟，而後者則靜默忽略它們。

示例

>>> 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)
< > 在 GitHub 上更新

←PatchTST TimesFM→
© . This site is unofficial and not affiliated with Hugging Face, Inc.