timesfm-forecasting

TimesFM 予測

概要

TimesFM（Time Series Foundation Model）は、Google Research が開発した、時系列予測用の事前学習済みデコーダー専用基盤モデルです。ゼロショットで動作し、任意の単変量時系列を入力すると、学習なしで点予測と、校正済みの分位点予測区間を返します。

このスキルは、TimesFM を安全かつエージェントに適したローカル推論用にラップします。モデルの読み込み前に RAM、GPU メモリ、ディスク容量を確認する必須の事前チェックシステムを備えているため、エージェントによってユーザーのマシンがクラッシュすることはありません。

主な数値：TimesFM 2.5 は 2 億パラメーター（ディスク上で約 800 MB、CPU で約 1.5 GB の RAM、GPU で約 1 GB の VRAM）を使用します。アーカイブ済みの v1／v2 500M パラメーターのモデルには約 32 GB の RAM が必要です。 必ず最初にシステムチェッカーを実行してください。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• あらゆる単変量時系列（売上、需要、センサー、バイタル、価格、天気）を予測する場合
• カスタムモデルを学習させずにゼロショット予測を行いたい場合
• 校正済みの予測区間（分位点）を含む確率的予測が必要な場合
• 任意の長さの時系列を扱う場合（モデルは 1～16,384 個のコンテキストポイントを処理します）
• 数百または数千の時系列を効率よくバッチ予測する必要がある場合
• ARIMA／ETS のパラメーターを手動で調整する代わりに、基盤モデルを利用したい場合

以下の場合は、このスキルを使用しないでください。

• 係数を解釈できる古典的な統計モデルが必要な場合 → statsmodels を使用してください
• 時系列の分類やクラスタリングが必要な場合 → aeon を使用してください
• 多変量ベクトル自己回帰やグレンジャー因果性が必要な場合 → statsmodels を使用してください
• データが表形式の場合（時系列データではない場合）→ scikit-learn を使用してください

異常検知についての注意：TimesFM に異常検知機能は組み込まれていませんが、分位点予測を予測区間として使用できます。90% 信頼区間（q10～q90）の範囲外の値は、統計的に異常です。詳しい例については、examples/anomaly-detection/ ディレクトリを参照してください。

⚠️ 必須の事前チェック：システム要件の確認

重要 — 初めてモデルを読み込む前に、必ずシステムチェッカーを実行してください。

python scripts/check_system.py

このスクリプトでは、次の項目を確認します。

1. 利用可能な RAM — 4 GB 未満の場合は警告し、2 GB 未満の場合は処理を中断します
2. GPU の利用可否 — CUDA／MPS デバイスと VRAM を検出します
3. ディスク容量 — 約 800 MB のモデルをダウンロードできる空き容量があるか確認します
4. Python バージョン — 3.10 以降が必要です
5. 既存のインストール状況 — timesfm と torch がインストールされているか確認します

注意： モデルの重みはこのリポジトリには保存されていません。TimesFM の重み（約 800 MB）は、初回使用時に HuggingFace からオンデマンドでダウンロードされ、~/.cache/huggingface/ にキャッシュされます。 事前チェックにより、ダウンロードを開始する前に十分なリソースがあることを確認できます。

flowchart TD
    accTitle: Preflight System Check
    accDescr: Decision flowchart showing the system requirement checks that must pass before loading TimesFM.

    start["🚀 Run check_system.py"] --> ram{"RAM ≥ 4 GB?"}
    ram -->|"Yes"| gpu{"GPU available?"}
    ram -->|"No (2-4 GB)"| warn_ram["⚠️ Warning: tight RAM<br/>CPU-only, small batches"]
    ram -->|"No (< 2 GB)"| block["🛑 BLOCKED<br/>Insufficient memory"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
    gpu -->|"CPU only"| cpu_ok["✅ CPU mode<br/>Slower but works"]
    vram -->|"Yes"| gpu_ok["✅ GPU mode<br/>Fast inference"]
    vram -->|"No"| cpu_ok
    gpu_ok --> disk{"Disk ≥ 2 GB free?"}
    cpu_ok --> disk
    disk -->|"Yes"| ready["✅ READY<br/>Safe to load model"]
    disk -->|"No"| block_disk["🛑 BLOCKED<br/>Need space for weights"]

    classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warn fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef block fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

    class ready,gpu_ok,cpu_ok ok
    class warn_ram warn
    class block,block_disk block
    class start,ram,gpu,vram,disk neutral

モデルバージョン別のハードウェア要件

モデル	パラメーター	RAM（CPU）	VRAM（GPU）	ディスク	コンテキスト
TimesFM 2.5（推奨）	200M	≥ 4 GB	≥ 2 GB	約 800 MB	最大 16,384
TimesFM 2.0（アーカイブ済み）	500M	≥ 16 GB	≥ 8 GB	約 2 GB	最大 2,048
TimesFM 1.0（アーカイブ済み）	200M	≥ 8 GB	≥ 4 GB	約 800 MB	最大 2,048

推奨： 古いチェックポイントを使用する特別な理由がない限り、常に TimesFM 2.5 を使用してください。より小型で高速なうえ、8 倍長いコンテキストに対応しています。

🔧 インストール

ステップ 1：システムを確認する（必ず最初に実行）

python scripts/check_system.py

ステップ 2：TimesFM をインストールする

# Using uv (recommended by this repo)
uv pip install timesfm[torch]

# For JAX/Flax backend (faster on TPU/GPU)
uv pip install timesfm[flax]

ステップ 3：ハードウェアに対応した PyTorch をインストールする

# CUDA 12.1 (NVIDIA GPU)
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121

# CPU only
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu

# Apple Silicon (MPS)
uv pip install torch>=2.0.0  # MPS support is built-in

ステップ 4：インストールを確認する

import timesfm
import numpy as np
print(f"TimesFM version: {timesfm.__version__}")
print("Installation OK")

🎯 クイックスタート

最小限の例（5 行）

import torch, numpy as np, timesfm

torch.set_float32_matmul_precision("high")

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)
model.compile(timesfm.ForecastConfig(
    max_context=1024, max_horizon=256, normalize_inputs=True,
    use_continuous_quantile_head=True, force_flip_invariance=True,
    infer_is_positive=True, fix_quantile_crossing=True,
))

point, quantiles = model.forecast(horizon=24, inputs=[
    np.sin(np.linspace(0, 20, 200)),  # any 1-D array
])
# point.shape == (1, 24)        — median forecast
# quantiles.shape == (1, 24, 10) — 10th–90th percentile bands

CSV から予測する

import pandas as pd, numpy as np

df = pd.read_csv("monthly_sales.csv", parse_dates=["date"], index_col="date")

# Convert each column to a list of arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

point, quantiles = model.forecast(horizon=12, inputs=inputs)

# Build a results DataFrame
for i, col in enumerate(df.columns):
    last_date = df[col].dropna().index[-1]
    future_dates = pd.date_range(last_date, periods=13, freq="MS")[1:]
    forecast_df = pd.DataFrame({
        "date": future_dates,
        "forecast": point[i],
        "lower_80": quantiles[i, :, 2],  # 20th percentile
        "upper_80": quantiles[i, :, 8],  # 80th percentile
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

共変量を使用した予測（XReg）

TimesFM 2.5+ は、forecast_with_covariates() を使用して外生変数をサポートします。timesfm[xreg] が必要です。

# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"price": price_arrays},
    dynamic_categorical_covariates={"holiday": holiday_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"
)

共変量の種類	説明	例
dynamic_numerical	時間とともに変化する数値	価格、気温、販促費
dynamic_categorical	時間とともに変化するカテゴリ	祝日フラグ、曜日
static_numerical	系列ごとの数値	店舗の広さ、アカウントの利用期間
static_categorical	系列ごとのカテゴリ	店舗の種類、地域、商品カテゴリ

XReg モード：

• "xreg + timesfm"（デフォルト）：まず TimesFM が予測し、その後 XReg が残差を調整します
• "timesfm + xreg"：まず XReg が適合し、その後 TimesFM が残差を予測します

合成小売データを使った完全な例については、examples/covariates-forecasting/ をご覧ください。

異常検知（分位点区間を使用）

TimesFM には異常検知機能が組み込まれていませんが、分位点予測によって自然に予測区間が得られるため、異常を検知できます：

point, q = model.forecast(horizon=H, inputs=[values])

# 90% prediction interval
lower_90 = q[0, :, 1]  # 10th percentile
upper_90 = q[0, :, 9]  # 90th percentile

# Detect anomalies: values outside the 90% CI
actual = test_values  # your holdout data
anomalies = (actual < lower_90) | (actual > upper_90)

# Severity levels
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # outside 80% CI
is_critical = anomalies  # outside 90% CI

深刻度	条件	解釈
正常	80% 信頼区間内	予想される動作
警告	80% 信頼区間外	通常とは異なりますが、起こり得ます
重大	90% 信頼区間外	統計的にまれ（確率 < 10%）

可視化を含む完全な例については、examples/anomaly-detection/ をご覧ください。

# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temperature": temp_arrays},
    dynamic_categorical_covariates={"day_of_week": dow_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"
)

出力、設定、ワークフロー、チューニング

• references/output_and_config.md：点予測と 10 個の分位点バンドの読み取り、予測区間の導出、および ForecastConfig の全フィールド。
• references/workflows.md：標準的な予測手順、ワイド形式の CSV による多数の系列の予測、区間カバレッジを用いたバックテスト。
• references/performance_tuning.md：GPU と TF32 の設定、利用可能なメモリに応じた per_core_batch_size の指定、メモリ管理。
• references/examples_and_validation.md：実行可能な例、品質チェックリスト、よくある間違い、回帰チェック。

🔗 他のスキルとの連携

statsmodels との連携

古典的なモデル（ARIMA、SARIMAX）を比較用のベースラインとして使用するには、statsmodels を使います：

# TimesFM forecast
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[values])

# statsmodels ARIMA forecast
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)

# Compare
print(f"TimesFM MAE: {np.mean(np.abs(actual - tfm_point[0])):.2f}")
print(f"ARIMA MAE:   {np.mean(np.abs(actual - arima_forecast)):.2f}")

matplotlib / scientific-visualization との連携

予測区間付きの予測を、出版品質の図としてプロットします。

exploratory-data-analysis との連携

予測の前に時系列の EDA を実行し、トレンド、季節性、定常性を把握します。

📚 利用可能なスクリプト

scripts/check_system.py

必須の事前チェックツールです。 初回のモデル読み込み前に実行してください。

python scripts/check_system.py

出力例：

=== TimesFM System Requirements Check ===

[RAM]       Total: 32.0 GB | Available: 24.3 GB  ✅ PASS
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ PASS
[Disk]      Free: 142.5 GB                        ✅ PASS
[Python]    3.12.1                                 ✅ PASS
[timesfm]   Installed (2.5.0)                      ✅ PASS
[torch]     Installed (2.4.1+cu121)                ✅ PASS

VERDICT: ✅ System is ready for TimesFM 2.5 (GPU mode)
Recommended: per_core_batch_size=128

scripts/forecast_csv.py

システムの自動チェックを含む、CSV のエンドツーエンド予測です。

python scripts/forecast_csv.py input.csv \
    --horizon 24 \
    --date-col date \
    --value-cols sales,revenue \
    --output forecasts.csv

📖 リファレンスドキュメント

詳細なガイドは references/ にあります：

ファイル	内容
references/system_requirements.md	ハードウェアの区分、GPU/CPU の選択、メモリ推定式
references/api_reference.md	ForecastConfig の全ドキュメント、from_pretrained のオプション、出力形状
references/data_preparation.md	入力形式、NaN の処理、CSV の読み込み、共変量の設定

よくある落とし穴

1. システムチェックを実行しない → RAM が少ないマシンではモデルの読み込み時にクラッシュします。必ず最初に check_system.py を実行してください。
2. model.compile() を忘れる → RuntimeError: Model is not compiled が発生します。forecast() の前に必ず compile() を呼び出してください。
3. normalize_inputs=True を設定しない → 値が大きい系列では予測が不安定になります。
4. RAM が 32 GB 未満のマシンで v1/v2 を使用する → 代わりに TimesFM 2.5（パラメーター数 200M）を使用してください。
5. fix_quantile_crossing=True を設定しない → 分位点が単調にならない場合があります（q10 > q50）。
6. 小型 GPU で per_core_batch_size を大きくしすぎる → CUDA の OOM が発生します。小さい値から始めて、徐々に増やしてください。
7. 2 次元配列を渡す → TimesFM が必要とするのは 2 次元行列ではなく、1 次元配列のリストです。
8. torch.set_float32_matmul_precision("high") を忘れる → Ampere 以降の GPU で推論が遅くなります。
9. 出力の NaN を処理しない → 非常に短い系列でエッジケースが発生します。必ず np.isnan(point).any() を確認してください。
10. 負の値になり得る系列に infer_is_positive=True を使用する → 予測値が 0 に制限されます。温度やリターンなどには False を設定してください。

モデルのバージョン

timeline
    accTitle: TimesFM Version History
    accDescr: Timeline of TimesFM model releases showing parameter counts and key improvements.

    section 2024
        TimesFM 1.0 : 200M params, 2K context, JAX only
        TimesFM 2.0 : 500M params, 2K context, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M params, 16K context, quantile head, no frequency indicator

バージョン	パラメーター数	コンテキスト	分位点ヘッド	頻度フラグ	ステータス
2.5	200M	16,384	✅ 連続値（30M）	❌ 廃止	最新
2.0	500M	2,048	✅ 固定バケット	✅ 必須	アーカイブ済み
1.0	200M	2,048	✅ 固定バケット	✅ 必須	アーカイブ済み

Hugging Face のチェックポイント：

• google/timesfm-2.5-200m-pytorch（推奨）
• google/timesfm-2.5-200m-flax
• google/timesfm-2.0-500m-pytorch（アーカイブ済み）
• google/timesfm-1.0-200m-pytorch（アーカイブ済み）

リソース

• 論文：時系列予測のためのデコーダーのみの基盤モデル（ICML 2024）
• リポジトリ：https://github.com/google-research/timesfm
• Hugging Face：https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
• Google ブログ：https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/
• BigQuery との統合：https://cloud.google.com/bigquery/docs/timesfm-model

関連スキル

• aeon：分類、回帰、クラスタリング、予測、異常検知などの時系列機械学習タスクには、このスキルを使用してください…
• statsmodels：Python 用の統計モデルライブラリです。
• segment-anything-model：ゼロショット転移に対応した画像セグメンテーション用基盤モデルです。