Transformers documentation
TimesFM
该模型于 2023-10-14 在 HF papers 上发布，并于 2025-04-16 贡献至 Hugging Face Transformers。
TimesFM
概述
TimesFM（Time Series Foundation Model，时间序列基础模型）是由 Abhimanyu Das、Weihao Kong、Rajat Sen 和 Yichen Zhou 在 A decoder-only foundation model for time-series forecasting 中提出的一种预训练时间序列基础模型。它是一个仅包含解码器的模型，以时间序列数据的非重叠块（patch）作为输入，并以自回归方式输出指定长度的预测块。
该论文的摘要如下：
受自然语言处理（NLP）领域大语言模型近期进展的启发，我们设计了一个用于预测的时间序列基础模型。该模型在多种公开数据集上的开箱即用零样本性能，已接近针对每个单独数据集训练的最先进监督预测模型的精度。我们的模型基于在大规模时间序列语料库上预训练一个补丁解码器风格的注意力模型，并且能够在不同的预测历史长度、预测长度和时间粒度下良好地工作。
要使用该模型：
import numpy as np
import torch
from transformers import TimesFmModelForPrediction
model = TimesFmModelForPrediction.from_pretrained(
"google/timesfm-2.0-500m-pytorch",
attn_implementation="sdpa",
device_map="auto"
)
# 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).to(model.device)
for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)
# 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 >( 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonepatch_length: int = 32context_length: int = 512horizon_length: int = 128freq_size: int = 3num_hidden_layers: int = 50hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16tolerance: float = 1e-06rms_norm_eps: float = 1e-06quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)pad_val: float = 1123581321.0attention_dropout: float | int = 0.0use_positional_embedding: bool = Falseinitializer_range: float = 0.02min_timescale: int = 1max_timescale: int = 10000 )
参数
- patch_length (
int，可选，默认为 32) — 输入序列中单个 patch 的长度。 - 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) — 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads - 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) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - min_timescale (
int，可选，默认为 1) — 几何位置索引的起始值。决定所添加信号的周期性。 - max_timescale (
int，可选，默认值为 10000) — 几何位置索引的结束值。决定所添加信号的频率。
这是用于存储 TimesFmModel 配置的类。它根据指定的参数实例化 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 Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)
参数
- past_values (
torch.Tensor，形状为(batch_size, sequence_length)) — 作为模型输入的时间序列历史值。 - past_values_padding（形状为
(batch_size, sequence_length)的torch.LongTensor）— 时间序列的填充指示器。 - freq（形状为
(batch_size,)的torch.LongTensor）— 时间序列数据的频率索引。
返回值
TimesFmOutput 或 tuple(torch.Tensor)
TimesFmOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（TimesFmConfig）和输入。
TimesFmModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
loc（形状为
(batch_size, )的torch.Tensor）— 时间序列输入的均值。scale（形状为
(batch_size,)的torch.Tensor）— 时间序列输入的缩放系数。
TimesFmModelForPrediction
用于分位数和均值预测的 TimesFM 模型。
forward
< source >( past_values: collections.abc.Sequence[torch.Tensor]freq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = Nonewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonereturn_forecast_on_context: bool = Falsetruncate_negative: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutputForPrediction or tuple(torch.Tensor)
参数
- past_values (
torch.Tensor，形状为(batch_size, sequence_length)) — 作为模型输入的时间序列历史值。 - freq（形状为
(batch_size,)的torch.LongTensor）— 时间序列数据的频率索引。 - window_size (
int, 可选) — 趋势 + 残差分解的窗口大小。如果为 None，则不进行分解。 - future_values (
torch.Tensor, 可选) — 用于损失计算的可选未来时间序列值。 - forecast_context_len (
int，可选) — 可选的最大上下文长度。 - return_forecast_on_context (
bool，可选) — 如果可用，则返回上下文上的预测，即在第一个输入补丁之后。 - truncate_negative (
bool, 可选) — 如果任一上下文包含非负值，则截断为仅保留非负值；否则不做任何处理。
返回值
TimesFmOutputForPrediction 或 tuple(torch.Tensor)
TimesFmOutputForPrediction 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（TimesFmConfig）和输入。
TimesFmModelForPrediction 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
mean_predictions（形状为
(batch_size, sequence_length)的torch.Tensor）— 时间序列的平均预测值。full_predictions（形状为
(batch_size, sequence_length)的torch.Tensor）— 时间序列的完整预测结果，包括均值和分位数。loss (
torch.Tensor，形状为(1,)，可选，在提供future_values时返回) — TimesFM 模型的损失。
示例：
>>> 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