Transformers documentation

TimesFM 2.5

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2023-10-14 在 HF papers 上发布,并于 2026-02-27 贡献至 Hugging Face Transformers。

FlashAttention SDPA

TimesFM 2.5

概述

TimesFM 2.5(时间序列基础模型)是由 Abhimanyu Das、Weihao Kong、Rajat Sen 和 Yichen Zhou 在 A decoder-only foundation model for time-series forecasting 中提出的一种预训练时间序列基础模型。它在原始 TimesFM 架构的基础上,引入了旋转注意力(rotary attention)、QK 归一化、逐维度注意力缩放以及连续分位数预测。

该论文的摘要如下:

受自然语言处理(NLP)领域大语言模型近期进展的启发,我们设计了一个用于预测的时间序列基础模型。该模型在多种公开数据集上的开箱即用零样本性能,已接近针对每个单独数据集训练的最先进监督式预测模型的精度。我们的模型基于对采用输入分块(input patching)的解码器式注意力模型进行预训练,所使用的语料库包含大量真实世界和合成时间序列数据集。在一系列此前未见过的预测数据集上的实验表明,该模型能够在不同领域、不同预测时间跨度和不同时间粒度下提供准确的零样本预测。

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

您可以在 google/timesfm-2.5-200m-transformers 找到该检查点。

使用示例

import numpy as np
import torch

from transformers import TimesFm2_5ModelForPrediction


model = TimesFm2_5ModelForPrediction.from_pretrained(
    "google/timesfm-2.5-200m-transformers",
    device_map="auto",
)

forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
forecast_input_tensor = [torch.tensor(ts, dtype=torch.float32, device=model.device) for ts in forecast_input]

with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, return_dict=True)
    point_forecast = outputs.mean_predictions
    quantile_forecast = outputs.full_predictions

TimesFm2_5Config

class transformers.TimesFm2_5Config

< >

( 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 = 16384horizon_length: int = 128num_hidden_layers: int = 20hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16rms_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)attention_dropout: float | int = 0.0initializer_range: float = 0.02num_key_value_heads: int = 16attention_bias: bool = Falseoutput_quantile_len: int = 1024decode_index: int = 5use_bias: bool = Falseactivation: str = 'swish'use_continuous_quantile_head: bool = Trueforce_flip_invariance: bool = Trueinfer_is_positive: bool = Truemax_position_embeddings: int = 16384rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

参数

  • patch_length (int,可选,默认为 32) — 输入序列中单个 patch 的长度。
  • context_length (int,可选,默认值为 16384) — 输入上下文的长度。
  • horizon_length(int,可选,默认值为 128)— 预测时域的长度。
  • num_hidden_layers (int, 可选, 默认为 20) — 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 解码器中每个注意力层的注意力头数量。
  • 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]) — 要预测的分位数。
  • attention_dropout (Union[float, int],可选,默认为 0.0) — 注意力概率的 dropout 比率。
  • initializer_range (float,可选,默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
  • num_key_value_heads (int, 可选,默认为 16) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果 num_key_value_heads=num_attention_heads,模型将使用 Multi Head Attention (MHA);如果 num_key_value_heads=1,模型将使用 Multi Query Attention (MQA);否则将使用 GQA。在将多头检查点转换为 GQA 检查点时,每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 这篇论文。如果未指定,则默认为 num_attention_heads。
  • attention_bias (bool,可选,默认为 False) — 在自注意力机制中,是否在 query、key、value 和 output 投影层中使用偏置。
  • output_quantile_len (int,可选,默认为 1024) — 分位数输出投影维度的长度。
  • decode_index (int,可选,默认为 5) — 用于从分位数维度中提取点(中位数)预测值的索引。
  • use_bias (bool,可选,默认为 False) — 是否在 MLP 和 transformer 线性层中使用偏置。
  • activation (str,可选,默认为 swish) — 解码器中的非线性激活函数(函数或字符串)。例如,"gelu"、 "relu"、"silu" 等。
  • use_continuous_quantile_head (bool,可选,默认为 True) — 是否使用连续分位数头进行非中位数分位数预测。
  • force_flip_invariance (bool,可选,默认为 True) — 是否在预测过程中应用翻转不变性平均。
  • infer_is_positive (bool,可选,默认为 True) — 当输入的最小值非负时,是否将预测值截断为非负值。
  • max_position_embeddings (int,可选,默认为 16384) — 该模型可能使用的最大序列长度。
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 可选) — 包含 RoPE 嵌入配置参数的字典。该字典应包含 rope_theta 的值,并且如果希望使用 RoPE 处理更长的 max_position_embeddings,则可选地包含用于缩放的参数。

这是用于存储 TimesFm2_5Model 配置的类。它根据指定的参数实例化 Timesfm2 5 模型,并定义模型架构。使用默认值实例化配置,将得到与 google/timesfm-2.5-200m-transformers 类似的配置。

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

示例:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

>>> configuration = TimesFm2_5Config()
>>> model = TimesFm2_5ModelForPrediction(configuration)
>>> configuration = model.config

TimesFm2_5Model

class transformers.TimesFm2_5Model

< >

( config: TimesFm2_5Config )

forward

< >

( past_values: Tensorpast_values_padding: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5Output or tuple(torch.Tensor)

参数

  • past_values(形状为 (batch_size, sequence_length) 的 torch.Tensor)— 用作模型输入的时间序列历史值。
  • past_values_padding(形状为 (batch_size, sequence_length) 的 torch.LongTensor,可选) — 输入的填充掩码。1 表示填充(被掩码)的时间步,0 表示有效值。

返回值

TimesFm2_5Output 或 tuple(torch.Tensor)

TimesFm2_5Output 或 torch.Tensor 元组(当传入 return_dict=False 或 config.return_dict=False 时),其包含的元素取决于配置(TimesFm2_5Config)和输入。

TimesFm2_5Model 的 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(形状为 torch.Tensor 的 (batch_size,) 或 (batch_size, input_size),可选)—— 用于平移每个时间序列上下文窗口的值,使模型输入具有相同的量级,随后再平移回原始量级。

  • scale(形状为 torch.Tensor 的 (batch_size,) 或 (batch_size, input_size),可选)— 用于缩放每个时间序列上下文窗口的值,以便为模型提供具有相同量级的输入,随后再将其缩放回原始量级。

  • context_mu(形状为 (batch_size, num_patches) 的 torch.Tensor)— 在归一化过程中,针对每个输入 patch 计算得到的运行均值。

  • context_sigma(形状为 (batch_size, num_patches) 的 torch.Tensor)— 在归一化过程中按输入块计算的运行标准差。

TimesFm2_5ModelForPrediction

class transformers.TimesFm2_5ModelForPrediction

< >

( config: TimesFm2_5Config )

用于分位数和均值预测的 TimesFm2_5 模型。

forward

< >

( past_values: collections.abc.Sequence[torch.Tensor]window_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonetruncate_negative: bool | None = Noneforce_flip_invariance: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5OutputForPrediction or tuple(torch.Tensor)

参数

  • past_values (collections.abc.Sequence[torch.Tensor]) — 作为模型输入的时间序列的历史值。每个张量都是一维时间序列。
  • window_size (int, 可选) — 趋势 + 残差分解的窗口大小。如果为 None,则不应用分解。
  • future_values (torch.Tensor, 可选) — 用于计算损失的可选未来值。
  • forecast_context_len (int, 可选) — 用于预测期间的可选上下文长度覆盖值。
  • truncate_negative (bool, 可选) — 是否将输出截断为非负值。如果为 None,则默认为 config.infer_is_positive。
  • force_flip_invariance (bool, 可选) — 是否应用翻转不变性组合。如果为 None,则默认为 config.force_flip_invariance。

返回值

TimesFm2_5OutputForPrediction 或 tuple(torch.Tensor)

TimesFm2_5OutputForPrediction 或 torch.Tensor 元组(如果传入 return_dict=False 或 config.return_dict=False),包含根据配置(TimesFm2_5Config)和输入而定的各种元素。

TimesFm2_5ModelForPrediction 的 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, horizon_length) 的 torch.Tensor)— 反归一化后的确定性预测值。

  • full_predictions(形状为 (batch_size, horizon_length, quantiles) 的 torch.Tensor)— 反归一化后包含中位数的分位数预测。

  • loss (torch.Tensor,形状为 (1,),可选,在提供 future_values 时返回) — 当提供目标值时,结合 MSE 损失和分位数损失计算得出的训练损失。

Update on GitHub