timesfm-forecasting

TimesFM による予測

まずモデル/API を選択する

Python パッケージのバージョンは 3.0.2 です。チェックポイントのバージョンは別個です。

チェックポイント	インターフェース	分位点出力	利用条件
2.5、200M	timesfm.TimesFM_2p5_200M_torch、compile、forecast	平均 + 9 分位数、中央値インデックス 5	Apache-2.0 の重み。同梱 CLI のデフォルト
3.0、約 330M	timesfm3.TimesFM3Forecaster、predict / predict_batch	9 分位数、中央値インデックス 4	ダウンロードした重みは非商用・非本番利用に限定

上流は 3.0 を最新モデルと位置づけています。このスキルは 2.5 をデフォルトの ローカルワークフローとして維持しています。その Apache ライセンスの重みは 利用条件が異なるためです。3.0 の多変量ターゲット、過去のみの共変量、または Apple MLX については、 コードを適応させる前に references/timesfm3.md をお読みください。認可された Google Cloud サービスには別個の条件が適用されます。Cloud の資格があっても ダウンロードした重みのライセンスは変わりません。上流のライセンス通知を参照してください。

TimesFM は、タスク固有のモデル訓練なしに、順序付けられた時系列ターゲットを予測するために使用します。 これは因果効果の推定器でも、臨床検出器でも、物理ベースの気候モデルでもありません。 ゼロショットとは適合を指すのであって、事前学習におけるベンチマークの重複がないことや、 新しいドメインでの高い精度を確立するものではありません。

ワークフロー

1. 周期、単位、予測の起点、ホライズン、起点時点で既知の共変量、 評価カットオフ、および naive/季節 naive ベースラインを確定します。
2. ソート済みで一意かつ規則的な時間グリッドを検証します。内部の欠損に対して dropna() を 行わないでください。時間間隔が変わってしまいます。非有限の入力は拒否するか、各訓練履歴の 内部で明示的に補完してください。ホールドアウトされた将来のターゲットを使って 埋めてはいけません。
3. 重みをダウンロード/ロードする前に python scripts/check_system.py を実行します。 その利用可能 RAM とキャッシュ容量のしきい値はヒューリスティックであり、OOM に対する 保証ではありません。バッチサイズ 1 から始め、実際のピーク使用量を測定してください。
4. 記録された不変のリビジョンで選択したチェックポイントをロードします。2.5 では、 明示的な正のコンテキスト/ホライズン設定を compile します。ゼロは 「最大値を使う」という意味ではありません。連続分位点ヘッドを使用する場合は、 パッチで丸めたコンテキスト + ホライズン <=16,384 およびホライズン <=1,024 を維持してください。
5. 予測し、形状/有限値/分位点の順序を検証し、予測の起点、頻度、 構成、チェックポイントのリビジョンをエクスポートします。
6. ローリング起点にわたって評価し、前処理は起点ごとに独立して適合させます。精度、 区間被覆率、ホライズン別の区間幅を報告します。分位点区間は、関連データで キャリブレーションされるまで名目上のものとラベル付けします。

インストール

別の環境で実行してください。以下のコマンドはレビュー済みリリースを対象としています。 シェルの追加指定やバージョン制約は、特に zsh では引用符で囲む必要があります。

uv venv .venv-timesfm
uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
.venv-timesfm/bin/python scripts/check_system.py

ホストに合った CUDA ホイールについては、最新の PyTorch インストールセレクター を使用してください。このリリースの 2.5 ローダーは、CUDA が存在すれば cuda:0 を選択し、そうでなければ CPU を選択します。MPS の検出は、MPS 推論を有効化することはありません。ラッパーに対して、それが nn.Module であるかのように model.to(...) を使わないでください。 CPU のみの XReg では、PyTorch プロファイルと併せて jax と scikit-learn をインストールしてください。 上流の [xreg] 追加指定は jax[cuda] を要求しますが、これは macOS には適していません。 Flax は別個のオプションのバックエンドであり、同梱スクリプトでは必須ではありません。

from importlib.metadata import version
import timesfm
print(version("timesfm"))  # package has no guaranteed timesfm.__version__
assert hasattr(timesfm, "TimesFM_2p5_200M_torch")

TimesFM 2.5 クイックスタート

チェックポイント読み込みの例は説明用です。この更新の検証では、事前学習済みの重みをダウンロードせずに、ネイティブパッケージのコードと小規模なランダムモデルおよび制御されたデコードフィクスチャを使用しました。これは仕組みを検証するものであり、精度を検証するものではありません。

import numpy as np
import timesfm

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch",
    revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
    torch_compile=False,  # avoid compilation startup during an initial smoke run
)
model.compile(timesfm.ForecastConfig(
    max_context=512, max_horizon=128, per_core_batch_size=1,
    normalize_inputs=True, use_continuous_quantile_head=True,
    force_flip_invariance=True, infer_is_positive=False,
    fix_quantile_crossing=True,
))
histories = [np.sin(np.linspace(0, 20, 200)).astype(np.float32)]
# 2.5 may append dummy series to its input list during batching; pass a fresh list.
point, q = model.forecast(horizon=24, inputs=list(histories))
assert point.shape == (1, 24) and q.shape == (1, 24, 10)
assert np.isfinite(q).all() and np.all(np.diff(q[..., 1:], axis=-1) >= 0)
assert np.allclose(point, q[..., 5])
lower_80, upper_80 = q[..., 1], q[..., 9]  # q10-q90: nominal 80% PI
lower_60, upper_60 = q[..., 2], q[..., 8]  # q20-q80: nominal 60% PI

infer_is_positive=True は、真に非負であるターゲット領域に対してのみ設定してください。観測ウィンドウが正の値であっても、気温の異常値、リターン、残差が負になり得ないことを示すものではありません。単調な分位点と連続的な分位点ヘッドは、区間のキャリブレーションを保証するものではありません。

CSV ヘルパー

python scripts/forecast_csv.py monthly_sales.csv \
  --date-col date --freq MS --value-cols sales,revenue \
  --horizon 12 --batch-size 1 --nonnegative --output forecasts.csv

forecast_csv.py は、読み込み前に検証し、日付を並べ替え、重複するヘッダー/日付を拒否し、完全な規則的グリッドをチェックし、欠損位置を保持します。欠損値はデフォルトで失敗します。--missing interpolate は内部のギャップのみを埋め、先頭/末尾の値は決して埋めません。--date-col を指定しない場合、行の順序が規則的グリッドであると見なされ、出力はステップを使用します。数値 ID は --value-cols を使用して除外する必要があります。--max-context は履歴の切り詰めを制御します。--horizon は、この分位点ヘッドのワークフローでは 1..1,024 に制限されています。

出力は forecast、median、lower_80、upper_80、lower_60、upper_60 を保持します。.metadata.json サイドカーは、origin、cadence、モデルのリビジョン、config を記録します。古いスキルリリースでは、q10-q90/q20-q80 を 90%/80% と誤ってラベル付けしていました。古い外側の *_90 を *_80 に、古い内側の *_80 を *_60 に同時に移行してください。古い生成例の予測は、そのマッピング/来歴が無効であったため削除されました。

共変量と異常スクリーニング

2.5 XReg では、return_backcast=True をコンパイルし、ターゲットと共変量を同一のグリッド上に保持し、コンテキストおよびホライズンにわたる動的共変量を提供してください。"xreg + timesfm" はターゲットに対して回帰をフィットし、その後、回帰残差を予測します。"timesfm + xreg" は最初に予測し、その後、バックキャスト残差に対して回帰をフィットします。後者には複数の入力パッチ（32 観測）が必要です。パッケージ 3.0.2 では、実装は結合された点予測と分位点予測のリストを返します。継承された docstring は、2 番目の戻り値を XReg のみであると誤って記述しています。完全な呼び出しについては、references/api_reference.md を参照してください。

分位点の超過は、異常な観測をスクリーニングするために使用できるかもしれませんが、キャリブレーションされた 80% 区間であっても、通常の観測の約 20% を限界的に除外します。これらは、異常確率、familywise 制御、検証済みのアラーム重大度を提供するものではありません。回顧的なトレンド除去済み Z スコアも、前向きな異常検出とは異なります。

リファレンスと例

• API リファレンス: 2.5 のローダー、コンパイル、予測、XReg の契約。
• 出力/config: 実際のすべての ForecastConfig フィールドと区間インデックス。
• データ準備: グリッド、欠損、共変量のタイミング、形式のレシピ。
• ワークフロー: ホールドアウトおよびローリングオリジンの検証、ベースライン比較。
• システム要件: リソースチェックとバックエンド要件。
• パフォーマンスチューニング: 測定されたバッチ/コンテキストチューニング。
• 例と検証: コマンド例とテスト範囲。
• TimesFM 3.0: 多変量 API、9 分位レイアウト、使用境界。

主なレビューソース: 公式ソース、 3.0.2 ディストリビューション、 2.5 モデルカード、 3.0 モデルカード。