# TimesFM 2.5

## 概要

TimesFM 2.5 (Time Series Foundation Model) は、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 normalization、次元ごとの attention scaling、および連続量子予測を備えています。

論文の抄録は以下の通りです。

*自然言語処理（NLP）における大規模言語モデルの最近の進歩を背景に、私たちは予測のための時系列ファウンデーションモデルを設計しました。このモデルは、多様な公開データセットにおいて、個別のデータセットごとに訓練された最先端の教師あり予測モデルに匹敵する精度を、そのままの状態で（ゼロショットで）実現します。本モデルは、実世界のデータセットと合成データセットからなる大規模な時系列コーパスを用いて、入力パッチングを備えたデコーダ型のアテンションモデルを事前学習することで構築されています。これまで見たことのない多様な予測データセットに対する実験から、このモデルは、異なるドメイン、予測期間、時間粒度にわたって、高精度なゼロショット予測を生成できることが示唆されています。*

このモデルは [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`、*optional*、デフォルトは 32) : 入力シーケンスにおける 1 つのパッチの長さ。

context_length (`int`、*optional*、デフォルトは 16384) : 入力コンテキストの長さ。

horizon_length (`int`、*optional*、デフォルトは 128) : 予測ホライズンの長さ。

num_hidden_layers (`int`、*任意*、デフォルトは`20`) : Transformer デコーダーの隠れ層の数。

hidden_size (`int`、*任意*、デフォルトは`1280`) : 隠れ表現の次元数。

intermediate_size (`int`, *optional*, デフォルトは `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]`、*optional*、デフォルトは`[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`) : 注意確率のドロップアウト率。

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 ヘッドは、そのグループ内の元のすべてのヘッドを平均プーリングして構築する必要があります。詳細については、[この論文](https://huggingface.co/papers/2305.13245)を参照してください。指定されない場合、デフォルトで `num_attention_heads` が使用されます。

attention_bias (`bool`、*任意*、デフォルトは`False`) : セルフアテンションにおけるクエリ、キー、バリュー、出力の投影層でバイアスを使用するかどうか。

output_quantile_len (`int`、*optional*、デフォルトは 1024) : 量子化出力射影次元の長さ。

decode_index (`int`、*optional*、デフォルトは 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`、*optional*、デフォルトは`16384`) : このモデルが使用される可能性のある最大シーケンス長です。

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *optional*) : RoPE 埋め込みの設定パラメータを含む辞書です。この辞書には `rope_theta` の値が含まれていなければならず、より長い `max_position_embeddings` で RoPE を使用する場合、スケーリングに使用されるパラメータが任意で含まれます。

これは、[google/timesfm-2.5-200m-transformers](https://huggingface.co/google/timesfm-2.5-200m-transformers) と同様の設定をデフォルト値で生成する、TimesFm2_5Model の設定を保存するための設定クラスです。指定された引数に基づいて Timesfm2 5 モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/v5.23.0/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/v5.23.0/ja/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/ja/model_doc/timesfm2_5#transformers.TimesFm2_5Config)）と入力に応じて、さまざまな要素で構成されます。

[TimesFm2_5Model](/docs/transformers/v5.23.0/ja/model_doc/timesfm2_5#transformers.TimesFm2_5Model)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(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)`、*任意*) -- 各時系列のコンテキストウィンドウのスケーリング値。モデルへの入力値を同じ大きさ（magnitude）に揃えるために使用し、その後、元の大きさに戻すために使用されます。
- **context_mu** (`torch.Tensor`、形状 `(batch_size, num_patches)`) -- 正規化処理中に各入力パッチごとに計算された実行平均値。
- **context_sigma** (`torch.Tensor`、形状 `(batch_size, num_patches)`) -- 正規化処理中に各入力パッチごとに計算された標準偏差。

## 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]`) : モデルの入力として機能する時系列の過去の値。各テンソルは1次元の時系列です。

window_size (`int`, *optional*) : トレンドと残差の分解のウィンドウサイズ。`None`の場合、分解は適用されません。

future_values (`torch.Tensor`, *任意*) : 損失を計算するために使用される、任意の将来の値。

forecast_context_len (`int`, *optional*) : 予測時に使用するコンテキスト長のオプションの上書きです。

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/ja/model_doc/timesfm2_5#transformers.TimesFm2_5Config)）と入力に応じて、さまざまな要素で構成されます。

[TimesFm2_5ModelForPrediction](/docs/transformers/v5.23.0/ja/model_doc/timesfm2_5#transformers.TimesFm2_5ModelForPrediction) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
- **mean_predictions** (`torch.Tensor`、形状 `(batch_size, horizon_length)`) -- 正規化解除後の決定論的な予測値。
- **full_predictions** (`torch.Tensor`、形状 `(batch_size, horizon_length, quantiles)`) -- 正規化解除後の中央値を含む分位数予測。
- **loss** (`torch.Tensor`、shape `(1,)`、*optional*、`future_values` が指定された場合に返されます) -- ターゲットが提供された場合、MSE と quantile の損失を組み合わせるトレーニング損失。

