このモデルは2023年10月14日にHF papersで公開され、2025年4月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 で提案された、事前学習済みの時系列ファウンデーションモデルです。これはデコーダーオンリーモデルであり、時系列データの重複しないパッチを入力として受け取り、自己回帰的な方法で出力パッチ長の予測を生成します。

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

自然言語処理（NLP）における大規模言語モデルの最近の進歩を背景に、私たちは予測のための時系列ファウンデーションモデルを設計しました。このモデルは、さまざまな公開データセットにおいて、ゼロショットでそのまま使用した場合でも、各データセット個別の最先端の教師あり予測モデルの精度に迫るパフォーマンスを発揮します。当社のモデルは、大規模な時系列コーパス上でパッチ付きデコーダー型のアテンションモデルを事前学習させることで構築されており、異なる予測履歴の長さ、予測の長さ、時間的粒度にわたって良好に機能します。

このモデルは kashif によって提供されました。元のコードはこちらで確認できます。

モデルを使用するには:

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

クラス 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)— 入力シーケンスにおける 1 つのパッチの長さです。
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) — quantile loss の許容誤差です。
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) — アテンションスコアに適用されるドロップアウト確率です。
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

クラス transformers.TimesFmModel

< source >

( config: TimesFmConfig )

パラメータ

config (TimesFmConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

特定のヘッドを付加せずに、生の隠れ状態を出力する素の Timesfm Model。

このモデルは 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 (torch.LongTensor、形状 (batch_size, sequence_length)) — 時系列データのpaddingインジケーターです。
freq (torch.LongTensor、形状 (batch_size,)) — 時系列データの周波数インデックスです。

戻り値

TimesFmOutput または tuple(torch.Tensor)

TimesFmOutput、またはtorch.Tensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（TimesFmConfig）や入力に応じて、さまざまな要素で構成されます。

TimesFmModelの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, )) — 時系列入力の平均値。
scale (torch.Tensor、shape (batch_size,)) — 時系列入力のスケール。

TimesFmModelForPrediction

class transformers.TimesFmModelForPrediction

< source >

( config: TimesFmConfig )

Quantileとmeanの予測を行うTimesFMモデル。

forward

< source >

( past_values: Sequencefreq: 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 (torch.LongTensor、形状 (batch_size,)) — 時系列データの周波数インデックスです。
window_size (int, 任意) — トレンドと残差の分解におけるウィンドウサイズ。None の場合は分解を行いません。
future_values (torch.Tensor, 任意) — 損失計算に使用する将来の時間系列値（任意）。
forecast_context_len (int、省略可) — 任意の最大コンテキスト長です。
return_forecast_on_context (bool、省略可) — 利用可能な場合、つまり最初の入力パッチ以降に、コンテキストに対する予測を返す場合は True にします。
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 (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, sequence_length)）— 時系列の平均予測値。
full_predictions (torch.Tensor、形状 (batch_size, sequence_length)) — 平均と分位数を含む、時系列の予測全体。
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

Update on GitHub