TimesFM

概述

TimesFM (Time Series Foundation Model) 是由 Abhimanyu Das、Weihao Kong、Rajat Sen 和 Yichen Zhou 在《用于时间序列预测的仅解码器基础模型》中提出的预训练时间序列基础模型。它是一个仅解码器模型，使用时间序列数据的非重叠补丁作为输入，并以自回归方式输出一定输出补丁长度的预测。

论文摘要如下：

受自然语言处理 (NLP) 中大型语言模型最新进展的启发，我们设计了一个用于预测的时间序列基础模型，其在各种公共数据集上的开箱即用零样本性能接近每个独立数据集最先进的监督预测模型的准确性。我们的模型基于在大型时间序列语料库上预训练的补丁解码器风格注意力模型，并且可以很好地适用于不同的预测历史长度、预测长度和时间粒度。

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

使用模型

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

class transformers.TimesFmModelForPrediction

< source >

( config: TimesFmConfig )

用于分位数和平均值预测的 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

< > 在 GitHub 上更新

Transformers

TimesFM

概述

TimesFmConfig

class transformers.TimesFmConfig

TimesFmModel

class transformers.TimesFmModel

forward

TimesFmModelForPrediction

class transformers.TimesFmModelForPrediction

forward