Transformers documentation
TimesFM 2.5
该模型于 2023-10-14 在 HF papers 上发布，并于 2026-02-27 贡献至 Hugging Face Transformers。
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）的解码器式注意力模型进行预训练，所使用的语料库包含大量真实世界和合成时间序列数据集。在一系列此前未见过的预测数据集上的实验表明，该模型能够在不同领域、不同预测时间跨度和不同时间粒度下提供准确的零样本预测。
您可以在 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_predictionsTimesFm2_5Config
class transformers.TimesFm2_5Config
< 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 = 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 的文档。
TimesFm2_5Model
forward
< source >( 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
用于分位数和均值预测的 TimesFm2_5 模型。
forward
< source >( past_values: Sequencewindow_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 损失和分位数损失计算得出的训练损失。