# TimesFM 2.5

## 概述

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

该论文的摘要如下：

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

该模型由 [kashif](https://huggingface.co/kashif) 贡献。原始代码可在[此处](https://github.com/google-research/timesfm)找到。

您可以在 [`google/timesfm-2.5-200m-transformers`](https://huggingface.co/google/timesfm-2.5-200m-transformers) 找到该检查点。

## 使用示例

```python
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[[transformers.TimesFm2_5Config]]

#### transformers.TimesFm2_5Config[[transformers.TimesFm2_5Config]]

```python
transformers.TimesFm2_5Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, patch_length: int = 32, context_length: int = 16384, horizon_length: int = 128, num_hidden_layers: int = 20, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, rms_norm_eps: float = 1e-06, quantiles: 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.0, initializer_range: float = 0.02, num_key_value_heads: int = 16, attention_bias: bool = False, output_quantile_len: int = 1024, decode_index: int = 5, use_bias: bool = False, activation: str = 'swish', use_continuous_quantile_head: bool = True, force_flip_invariance: bool = True, infer_is_positive: bool = True, max_position_embeddings: int = 16384, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm2_5/configuration_timesfm2_5.py#L30)

**参数：**

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`，模型将使用多头注意力（MHA）；如果 `num_key_value_heads=1`，模型将使用多查询注意力（MQA）；否则将使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](https://huggingface.co/papers/2305.13245)。如果未指定，则默认为 `num_attention_heads`。

attention_bias (`bool`，*可选*，默认为 `False`)：在自注意力机制中，是否在查询、键、值和输出投影层中使用偏置。

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` 的值，并且如果希望使用更长的 `max_position_embeddings` 配合 RoPE，则可选地包含用于缩放的参数。

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

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

## TimesFm2_5Model[[transformers.TimesFm2_5Model]]

#### transformers.TimesFm2_5Model[[transformers.TimesFm2_5Model]]

```python
transformers.TimesFm2_5Model(config: TimesFm2_5Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L454)

#### forward[[transformers.TimesFm2_5Model.forward]]

```python
forward(past_values: Tensor, past_values_padding: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L550)

**参数：**

past_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`)：用作模型输入的时间序列历史值。

past_values_padding (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入的填充掩码。`1` 表示填充（被掩码）的时间步，`0` 表示有效值。

**返回：** `TimesFm2_5Output` 或 `tuple(torch.Tensor)`

`TimesFm2_5Output` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[TimesFm2_5Config](/docs/transformers/v5.23.0/zh/model_doc/timesfm2_5#transformers.TimesFm2_5Config)）和输入。

[TimesFm2_5Model](/docs/transformers/v5.23.0/zh/model_doc/timesfm2_5#transformers.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`）-- 在归一化期间按输入补丁计算的运行均值。
- **context_sigma**（形状为 `(batch_size, num_patches)` 的 `torch.Tensor`）-- 在归一化过程中按输入补丁计算的运行标准差。

## TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

#### transformers.TimesFm2_5ModelForPrediction[[transformers.TimesFm2_5ModelForPrediction]]

```python
transformers.TimesFm2_5ModelForPrediction(config: TimesFm2_5Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L636)

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

#### forward[[transformers.TimesFm2_5ModelForPrediction.forward]]

```python
forward(past_values: collections.abc.Sequence[torch.Tensor], window_size: int | None = None, future_values: typing.Optional[torch.Tensor] = None, forecast_context_len: int | None = None, truncate_negative: bool | None = None, force_flip_invariance: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/timesfm2_5/modeling_timesfm2_5.py#L724)

**参数：**

past_values (`collections.abc.Sequence[torch.Tensor]`) : 作为模型输入的时间序列的历史值。每个张量都是一个一维时间序列。

window_size (`int`, *optional*) : 趋势 + 残差分解的窗口大小。如果为 `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](/docs/transformers/v5.23.0/zh/model_doc/timesfm2_5#transformers.TimesFm2_5Config)）和输入。

[TimesFm2_5ModelForPrediction](/docs/transformers/v5.23.0/zh/model_doc/timesfm2_5#transformers.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 和分位数损失计算的训练损失。

