Transformers 文件
TimesFM
並獲得增強的文件體驗
開始使用
TimesFM
概述
TimesFM (Time Series Foundation Model) 是由 Abhimanyu Das、Weihao Kong、Rajat Sen 和 Yichen Zhou 在《用於時間序列預測的僅解碼器基礎模型》中提出的預訓練時間序列基礎模型。它是一個僅解碼器模型，使用時間序列資料的非重疊補丁作為輸入，並以自迴歸方式輸出一定輸出補丁長度的預測。
論文摘要如下：
受自然語言處理 (NLP) 中大型語言模型最新進展的啟發，我們設計了一個用於預測的時間序列基礎模型，其在各種公共資料集上的開箱即用零樣本效能接近每個獨立資料集最先進的監督預測模型的準確性。我們的模型基於在大型時間序列語料庫上預訓練的補丁解碼器風格注意力模型，並且可以很好地適用於不同的預測歷史長度、預測長度和時間粒度。
使用模型
import torch
from transformers import TimesFmModelForPrediction
model = TimesFmModelForPrediction.from_pretrained(
"google/timesfm-2.0-500m-pytorch",
torch_dtype=torch.bfloat16,
attn_implementation="sdpa",
device_map="cuda" if torch.cuda.is_available() else None
)
# Create dummy inputs
forecast_input = [
np.sin(np.linspace(0, 20, 100)),
np.sin(np.linspace(0, 20, 200)),
np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]
# Convert inputs to sequence of tensors
forecast_input_tensor = [
torch.tensor(ts, dtype=torch.bfloat16).to("cuda" if torch.cuda.is_available() else "cpu")
for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(
"cuda" if torch.cuda.is_available() else "cpu"
)
# Get predictions from the pre-trained model
with torch.no_grad():
outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()TimesFmConfig
class transformers.TimesFmConfig
< source >( patch_length: int = 32 context_length: int = 512 horizon_length: int = 128 freq_size: int = 3 num_hidden_layers: int = 50 hidden_size: int = 1280 intermediate_size: int = 1280 head_dim: int = 80 num_attention_heads: int = 16 tolerance: float = 1e-06 rms_norm_eps: float = 1e-06 quantiles: list = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9] pad_val: float = 1123581321.0 attention_dropout: float = 0.0 use_positional_embedding: bool = False initializer_range: float = 0.02 min_timescale: int = 1 max_timescale: int = 10000 **kwargs )
引數
- patch_length (
int, 可選, 預設為 32) — 輸入序列中一個補丁的長度。 - context_length (
int, 可選, 預設為 512) — 輸入上下文的長度。 - horizon_length (
int, 可選, 預設為 128) — 預測範圍的長度。 - freq_size (
int, 可選, 預設為 3) — 頻率嵌入的數量。 - num_hidden_layers (
int, 可選, 預設為 50) — Transformer 層的數量。 - hidden_size (
int, 可選, 預設為 1280) — 前饋網路中隱藏層的大小。 - intermediate_size (
int, 可選, 預設為 1280) — MLP 表示的維度。 - head_dim (
int, 可選, 預設為 80) — 每個注意力頭的鍵、查詢、值投影的大小。投影層的inner_dim將定義為num_attention_heads * head_dim。 - num_attention_heads (
int, 可選, 預設為 16) — Transformer 編碼器中每個注意力層的注意力頭數量。 - tolerance (
float, 可選, 預設為 1e-06) — 分位數損失的容差。 - rms_norm_eps (
float, 可選, 預設為 1e-06) — RMS 歸一化層使用的 epsilon。 - quantiles (
list[float], 可選, 預設為[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — 要預測的分位數。 - pad_val (
float, 可選, 預設為 1123581321.0) — 用於填充預測的值。 - attention_dropout (
float, 可選, 預設為 0.0) — 注意力分數的 dropout 機率。 - use_positional_embedding (
bool, 可選, 預設為False) — 是否新增位置嵌入。 - initializer_range (
float, 可選, 預設為 0.02) — 用於初始化所有權重矩陣的截斷正態分佈初始化器的標準差。 - min_timescale (
int, 可選, 預設為 1) — 幾何位置索引的起始。決定了新增訊號的週期性。 - max_timescale (
int, 可選, 預設為 10000) — 幾何位置索引的結束。決定了新增訊號的頻率。
這是用於儲存 TimesFmModelForPrediction 或 TFTimesFmModel 配置的配置類。它用於根據指定引數例項化 TimesFM 模型，定義模型架構。使用預設值例項化配置將產生與 TimesFM google/timesfm-2.0-500m-pytorch 架構類似的配置。
配置物件繼承自 PretrainedConfig，可用於控制模型輸出。有關更多資訊，請參閱 PretrainedConfig 的文件。
TimesFmModel
class transformers.TimesFmModel
< source >( config: TimesFmConfig )
引數
- config (TimesFmConfig) — 模型配置類，包含模型的所有引數。使用配置檔案例項化不會載入與模型相關的權重，只加載配置。請檢視 from_pretrained() 方法以載入模型權重。
裸 Timesfm 模型，輸出原始隱藏狀態，不帶任何特定頭部。
該模型繼承自 PreTrainedModel。請檢視超類文件以瞭解庫為其所有模型實現的一般方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
該模型也是 PyTorch torch.nn.Module 子類。將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件中所有與一般用法和行為相關的內容。
forward
< source >( past_values: Tensor past_values_padding: LongTensor freq: Tensor output_attentions: bool = False output_hidden_states: bool = False ) → transformers.models.timesfm.modeling_timesfm.TimesFmOutput 或 tuple(torch.FloatTensor)
引數
- past_values (
torch.FloatTensor，形狀為(batch_size, sequence_length)) — 作為模型輸入的時間序列的歷史值。 - past_values_padding (
torch.LongTensor，形狀為(batch_size, sequence_length)) — 時間序列的填充指示器。 - freq (
torch.LongTensor，形狀為(batch_size,)) — 時間序列資料的頻率索引。 - output_attentions (
bool, 預設為False) — 是否返回所有注意力層的注意力張量。更多詳細資訊請參閱返回張量中的attentions。 - output_hidden_states (
bool, 預設為False) — 是否返回所有層的隱藏狀態。更多詳細資訊請參閱返回張量中的hidden_states。
返回
transformers.models.timesfm.modeling_timesfm.TimesFmOutput 或 tuple(torch.FloatTensor)
一個 transformers.models.timesfm.modeling_timesfm.TimesFmOutput 或一個 torch.FloatTensor 的元組（如果傳入 return_dict=False 或 config.return_dict=False），包含根據配置 (TimesFmConfig) 和輸入的不同元素。
-
last_hidden_state (形狀為
(batch_size, sequence_length, hidden_size)的torch.FloatTensor, 可選) — 模型最後一層輸出的隱藏狀態序列。 -
hidden_states (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) —torch.FloatTensor的元組（一個用於嵌入層的輸出，如果模型有嵌入層，+ 每個層的輸出一個），形狀為(batch_size, sequence_length, hidden_size)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) —torch.FloatTensor的元組（每個層一個），形狀為(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
-
loc (
torch.Tensor，形狀為(batch_size, )) — 時間序列輸入的均值。 -
scale (
torch.Tensor，形狀為(batch_size,)) — 時間序列輸入的尺度。
TimesFmModel 的 forward 方法，覆蓋了 __call__ 特殊方法。
雖然前向傳播的實現需要在該函式中定義，但之後應該呼叫 Module 例項而不是該函式，因為前者會處理預處理和後處理步驟，而後者會默默忽略它們。
TimesFmModelForPrediction
用於分位數和平均值預測的 TimesFM 模型。
forward
< source >( past_values: Sequence freq: typing.Optional[collections.abc.Sequence[typing.Union[torch.Tensor, int]]] = None window_size: typing.Optional[int] = None future_values: typing.Optional[torch.Tensor] = None forecast_context_len: typing.Optional[int] = None return_forecast_on_context: bool = False truncate_negative: bool = False output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None ) → transformers.models.timesfm.modeling_timesfm.TimesFmOutputForPrediction 或 tuple(torch.FloatTensor)
引數
- past_values (
torch.FloatTensor，形狀為(batch_size, sequence_length)) — 作為模型輸入的時間序列的歷史值。 - freq (
torch.LongTensor，形狀為(batch_size,)) — 時間序列資料的頻率索引。 - window_size (
int, 可選) — 趨勢 + 殘差分解的視窗大小。如果為 None，則不進行分解。 - future_values (
torch.Tensor, 可選) — 用於損失計算的可選未來時間序列值。 - forecast_context_len (
int, 可選) — 可選的最大上下文長度。 - return_forecast_on_context (
bool, 可選) — 如果為 True，則在可用時（即在第一個輸入補丁之後）返回上下文上的預測。 - truncate_negative (
bool, 可選) — 如果任何上下文包含非負值，則截斷為僅非負值，否則不執行任何操作。 - output_attentions (
bool, 可選) — 是否輸出注意力。 - output_hidden_states (
bool, 可選) — 是否輸出隱藏狀態。
返回
transformers.models.timesfm.modeling_timesfm.TimesFmOutputForPrediction 或 tuple(torch.FloatTensor)
一個 transformers.models.timesfm.modeling_timesfm.TimesFmOutputForPrediction 或一個 torch.FloatTensor 的元組（如果傳入 return_dict=False 或 config.return_dict=False），包含根據配置 (TimesFmConfig) 和輸入的不同元素。
-
last_hidden_state (形狀為
(batch_size, sequence_length, hidden_size)的torch.FloatTensor, 可選) — 模型最後一層輸出的隱藏狀態序列。 -
hidden_states (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) —torch.FloatTensor的元組（一個用於嵌入層的輸出，如果模型有嵌入層，+ 每個層的輸出一個），形狀為(batch_size, sequence_length, hidden_size)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) —torch.FloatTensor的元組（每個層一個），形狀為(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
-
mean_predictions (
torch.Tensor，形狀為(batch_size, sequence_length)) — 時間序列的平均值預測。 -
full_predictions (
torch.Tensor，形狀為(batch_size, sequence_length)) — 時間序列的完整預測，包括平均值和分位數。 -
loss (
torch.Tensor，形狀為(1,), 可選, 當提供future_values時返回) — TimesFM 模型的損失。
TimesFmModelForPrediction 的 forward 方法，覆蓋了 __call__ 特殊方法。
雖然前向傳播的實現需要在該函式中定義，但之後應該呼叫 Module 例項而不是該函式，因為前者會處理預處理和後處理步驟，而後者會默默忽略它們。
示例
>>> from transformers import TimesFmModelForPrediction
>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")
>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)
>>> # Generate
>>> with torch.no_grad():
>>> outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>> point_forecast_conv = outputs.mean_predictions
>>> quantile_forecast_conv = outputs.full_predictions