Transformers documentation
TimesFM 2.5
このモデルは2023年10月14日にHF papersで公開され、2026年2月27日にHugging Face Transformersに貢献されました。
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 で提案された事前学習済み時系列ファウンデーションモデルです。元の TimesFM アーキテクチャを基盤とし、rotary attention、QK normalization、次元ごとの attention scaling、および連続量子予測を備えています。
論文の抄録は以下の通りです。
自然言語処理(NLP)における大規模言語モデルの最近の進歩を背景に、私たちは予測のための時系列ファウンデーションモデルを設計しました。このモデルは、多様な公開データセットにおいて、個別のデータセットごとに訓練された最先端の教師あり予測モデルに匹敵する精度を、そのままの状態で(ゼロショットで)実現します。本モデルは、実世界のデータセットと合成データセットからなる大規模な時系列コーパスを用いて、入力パッチングを備えたデコーダ型のアテンションモデルを事前学習することで構築されています。これまで見たことのない多様な予測データセットに対する実験から、このモデルは、異なるドメイン、予測期間、時間粒度にわたって、高精度なゼロショット予測を生成できることが示唆されています。
このモデルは 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_predictionsTimesFm2_5Config
クラス 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)— 入力シーケンスにおける 1 つのパッチの長さです。 - 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) — アテンション確率のドロップアウト率です。 - 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) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。 - output_quantile_len (
int、任意、デフォルトは 1024) — Quantile 出力の射影次元の長さ。 - 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 と同様の設定が得られます。
設定オブジェクトは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 (
torch.Tensor、形状(batch_size, sequence_length)) — モデルの入力として使用される時系列の過去の値です。 - past_values_padding (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — 入力用のパディングマスクです。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 (
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、shape(batch_size,)または(batch_size, input_size)、optional) — 各時系列のコンテキストウィンドウのスケーリング値。モデルへの入力値を同じ桁揃えにするために使用し、その後、元の桁揃えに戻すために逆スケーリングに用いられます。context_mu(
torch.Tensor、形状(batch_size, num_patches))— 正規化処理中に各入力パッチごとに計算される平均値。context_sigma (
torch.Tensor、形状(batch_size, num_patches)) — 正規化処理中に各入力パッチに対して計算された標準偏差。
TimesFm2_5ModelForPrediction
TimesFm2_5 モデルによる分位数予測および平均予測。
forward
< source >( 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]) — モデルへの入力として使用される時系列の過去の値です。各テンソルは1次元の時系列です。 - 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 (
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、shape(batch_size, horizon_length, quantiles)) — 正規化解除後の中央値を含む分位数予測。loss (
torch.Tensor、shape(1,)、optional、future_valuesが指定された場合に返されます) — ターゲットが提供された場合、MSE と quantile の損失を組み合わせるトレーニング損失。