timesfm-forecasting

TimesFM による予測

概要

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

このスキルには、モデルを読み込む前に RAM、GPU メモリ、ディスク容量を確認する必須の事前システムチェッカーが含まれているため、エージェントがユーザーのマシンをクラッシュさせることはありません。

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

このスキルを使う場面

次の場合にこのスキルを使います。

• 任意の単変量時系列（売上、需要、センサー値、バイタル、価格、天気）を予測する
• カスタムモデルを学習させずにゼロショット予測を行いたい
• 調整済みの予測区間（分位点）を含む確率的予測を行いたい
• 任意の長さの時系列を扱いたい（モデルはコンテキストポイント数 1～16,384 に対応）
• 数百から数千の系列を効率的にバッチ予測したい
• ARIMA／ETS のパラメーターを手動で調整する代わりに、基盤モデルを使いたい
• 外生変数（価格、プロモーション、休日、曜日の影響）を使った共変量予測を行いたい → forecast_with_covariates() を使用します（TimesFM 2.5 ＋ pip install timesfm[xreg]）

次の場合は、このスキルを使わないでください。

• 係数の解釈が必要な古典的統計モデルを使いたい → statsmodels を使用します
• 時系列の分類やクラスタリングが必要 → aeon を使用します
• 多変量ベクトル自己回帰やグレンジャー因果性の分析が必要 → statsmodels を使用します
• データが表形式である（時系列ではない） → scikit-learn を使用します
• オプションの依存関係をインストールできない → XReg には scikit-learn と JAX が必要です

異常検知に関する注意：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
    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"]

データセットの事前確認（新規）

実際のデータを読み込む前に、メモリに収まることを確認してください。

# Quick estimate for your dataset
python scripts/check_system.py \
  --num-series 1000 \
  --context-length 1024 \
  --horizon 24 \
  --batch-size 32 \
  --estimate-only

推定メモリ要件が表示され、データセットが大きすぎる場合は警告されます。

メモリ推定式： RAM ≈ 0.8 GB (model) + 0.5 GB (overhead) + (0.2 MB × num_series × context_length / 1000)

出力例：

✅ データセットは収まります：

Total CPU memory: 2.34 GB
Total GPU memory: 2.15 GB

⚠️ データセットが大きすぎます：

Dataset requires ~12.5 GB RAM but system has 8.0 GB.
Try: context_length=512 or process in chunks of 50 series.

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

モデル	パラメーター数	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 (fast)
uv pip install timesfm[torch]

# Or using pip
pip install timesfm[torch]

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

手順 3：使用するハードウェアに合わせて PyTorch をインストールする

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

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

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

🎯 クイックスタート

最小限の例

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

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

TimesFM 2.5+ は、forecast_with_covariates() を通じて外生変数をサポートしています。 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"
)

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

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

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

actual = test_values
anomalies = (actual < lower_90) | (actual > upper_90)

重大度	条件	解釈
正常	80% CI の範囲内	予想される動作
警告	80% CI の範囲外	異常ですが、起こり得ます
重大	90% CI の範囲外	統計的にまれ（確率 < 10%）

可視化を含む一通りの例については、examples/anomaly-detection/ をご覧ください。

📊 出力の理解

TimesFM は (point_forecast, quantile_forecast) を返します。

• point_forecast：形状 (batch, horizon) — 中央値（0.5 分位点）
• quantile_forecast：形状 (batch, horizon, 10) — 10 個の分位点スライス：

インデックス	分位点	用途
0	平均	平均予測
1	0.1	80% PI の下限
2	0.2	60% PI の下限
5	0.5	中央値（= point_forecast）
8	0.8	60% PI の上限
9	0.9	80% PI の上限

point, q = model.forecast(horizon=H, inputs=data)

lower_80 = q[:, :, 1]  # 10th percentile
upper_80 = q[:, :, 9]  # 90th percentile
median   = q[:, :, 5]

🔧 ForecastConfig リファレンス

予測の動作はすべて timesfm.ForecastConfig で制御されます。

timesfm.ForecastConfig(
    max_context=1024,                    # Max context window
    max_horizon=256,                     # Max forecast horizon
    normalize_inputs=True,               # RECOMMENDED — prevents scale instability
    per_core_batch_size=32,              # Tune for memory
    use_continuous_quantile_head=True,   # Better quantile accuracy for long horizons
    force_flip_invariance=True,          # Ensures f(-x) = -f(x)
    infer_is_positive=True,              # Clamp forecasts ≥ 0 when all inputs > 0
    fix_quantile_crossing=True,          # Ensure q10 ≤ q20 ≤ ... ≤ q90
    return_backcast=False,               # Return backcast (for covariate workflows)
)

パラメーター	デフォルト	変更する場合
max_context	0	最長の履歴ウィンドウに合わせて設定します
normalize_inputs	False	必ず True に設定します
use_continuous_quantile_head	False	較正された PI を使用するには True に設定します
infer_is_positive	True	負の値を取り得る系列では False に設定します
fix_quantile_crossing	False	分位点を単調にするには True に設定します

すべてのパラメーターについては、references/api_reference.md をご覧ください。

📋 よくあるワークフロー

単一系列の予測

import torch, numpy as np, pandas as pd, timesfm, matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

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=512, max_horizon=52, normalize_inputs=True,
    use_continuous_quantile_head=True, fix_quantile_crossing=True,
))

df = pd.read_csv("weekly_demand.csv", parse_dates=["week"])
values = df["demand"].values.astype(np.float32)

point, quantiles = model.forecast(horizon=52, inputs=[values])

fig, ax = plt.subplots(figsize=(12, 5))
ax.plot(values[-104:], label="Historical")
x_fc = range(len(values[-104:]), len(values[-104:]) + 52)
ax.plot(x_fc, point[0], label="Forecast", color="tab:orange")
ax.fill_between(x_fc, quantiles[0, :, 1], quantiles[0, :, 9],
                alpha=0.2, color="tab:orange", label="80% PI")
ax.legend(); ax.set_title("52-Week Demand Forecast")
plt.tight_layout(); plt.savefig("forecast.png", dpi=150)

バッチ予測（複数の系列）

df = pd.read_csv("all_stores.csv", parse_dates=["date"], index_col="date")
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

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

import json
results = {col: {"forecast": point[i].tolist(),
                 "lower_80": quantiles[i, :, 1].tolist(),
                 "upper_80": quantiles[i, :, 9].tolist()}
           for i, col in enumerate(df.columns)}
with open("batch_forecasts.json", "w") as f:
    json.dump(results, f, indent=2)

予測精度の評価

H = 24
train, actual = values[:-H], values[-H:]
point, quantiles = model.forecast(horizon=H, inputs=[train])
pred = point[0]

mae  = np.mean(np.abs(actual - pred))
rmse = np.sqrt(np.mean((actual - pred) ** 2))
mape = np.mean(np.abs((actual - pred) / actual)) * 100
coverage = np.mean((actual >= quantiles[0, :, 1]) & (actual <= quantiles[0, :, 9])) * 100

print(f"MAE: {mae:.2f} | RMSE: {rmse:.2f} | MAPE: {mape:.1f}% | 80% PI Coverage: {coverage:.1f}%")

⚙️ パフォーマンスの調整

# Always set on Ampere+ GPUs (A100, RTX 3090+)
torch.set_float32_matmul_precision("high")

# Batch size guidelines:
# GPU 8 GB VRAM:  per_core_batch_size=64
# GPU 16 GB VRAM: per_core_batch_size=128
# CPU 8 GB RAM:   per_core_batch_size=8
# CPU 16 GB RAM:  per_core_batch_size=32

# Memory-constrained: process in chunks
CHUNK = 50
results = []
for i in range(0, len(inputs), CHUNK):
    p, q = model.forecast(horizon=H, inputs=inputs[i:i+CHUNK])
    results.append((p, q))

📚 利用可能なスクリプト

scripts/check_system.py

必須の事前チェックツールです。初めてモデルを読み込む前に実行してください。 データを読み込む前に OOM エラーを防げるよう、データセットを考慮したメモリ推定機能が追加されました。

# Basic system check
python scripts/check_system.py

# Check if your specific dataset will fit
python scripts/check_system.py \
  --num-series 1000 \
  --context-length 1024 \
  --horizon 24 \
  --batch-size 32

# Quick memory estimate without system checks
python scripts/check_system.py \
  --num-series 5000 \
  --context-length 2048 \
  --estimate-only

チェック項目：

1. 利用可能な RAM — 4 GB 未満の場合は警告し、2 GB 未満の場合は処理を中止します
2. GPU の利用可否 — CUDA/MPS デバイスと VRAM を検出します
3. ディスク容量 — 約 800 MB のモデルダウンロードに必要な空き容量を確認します
4. Python のバージョン — 3.10 以降が必要です
5. インストール状況 — timesfm と torch がインストールされているか確認します
6. データセットの適合性（新機能） — 使用するデータセットのメモリを推定し、収まらない場合は警告します

scripts/forecast_csv.py

エンドツーエンドの CSV 予測 CLI です。

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

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

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

🧪 例

例	ディレクトリ	実演内容
世界の気温予測	examples/global-temperature/	基本的な model.forecast()、CSV → PNG → GIF のパイプライン
異常検知	examples/anomaly-detection/	2 段階のトレンド除去 + Z スコア + 分位 PI、2 パネルの可視化
共変量（XReg）	examples/covariates-forecasting/	forecast_with_covariates()、共有軸を使用した 2×2 の可視化

# Run all three examples:
cd examples/global-temperature && python run_forecast.py && python visualize_forecast.py
cd examples/anomaly-detection  && python detect_anomalies.py
cd examples/covariates-forecasting && python demo_covariates.py

期待される出力

例	主な出力ファイル	受け入れ基準
global-temperature	output/forecast_output.json, output/forecast_visualization.png	point_forecast に12個の値があること。PNGにコンテキスト＋予測＋PIバンドが表示されること
anomaly-detection	output/anomaly_detection.json, output/anomaly_detection.png	2023年9月が CRITICAL（z ≥ 3.0）として検出されること
covariates-forecasting	output/sales_with_covariates.csv, output/covariates_data.png	108行（3店舗 × 36週）があること。店舗ごとに異なる価格配列があること

モデルのバージョン

バージョン	パラメーター数	コンテキスト	ステータス	HuggingFace チェックポイント
2.5	200M	16,384	最新	google/timesfm-2.5-200m-pytorch
2.0	500M	2,048	アーカイブ済み	google/timesfm-2.0-500m-pytorch
1.0	200M	2,048	アーカイブ済み	google/timesfm-1.0-200m-pytorch

• TimesFM 1.0/2.0：月次データには freq=[0] を渡す必要があります
• TimesFM 2.5：頻度フラグはありません。削除されました

リソース

• 論文：A Decoder-Only Foundation Model for Time-Series Forecasting（ICML 2024）
• HuggingFace：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

品質チェックリスト

TimesFM のタスクを完了とする前に、毎回実行してください。

• 出力の形状 — point_fc は (n_series, horizon)、quant_fc は (n_series, horizon, 10) であること
• 分位点インデックス — インデックス0＝平均、1＝q10 … 9＝q90。0＝q0ではありません。
• 頻度フラグ — TimesFM 1.0/2.0：月次データには freq=[0] を渡します。TimesFM 2.5：省略します。
• 系列の長さ — コンテキストには32個以上のデータポイントが必要です。
• NaN がないこと — np.isnan(point_fc).any() が False であること
• 軸 — 複数のパネルでデータを共有する場合は、sharex=True を使用すること
• matplotlib.use('Agg') — ヘッドレス環境で実行する場合は、pyplot をインポートする前に指定すること
• infer_is_positive — 気温、金融リターン、負の値を扱う場合は False に設定すること

よくある間違い

1. 分位点インデックスのずれ — quant_fc[..., 0] は 平均 であり、q0ではありません。q10＝インデックス1、q90＝インデックス9です。次のように定義します：IDX_Q10, IDX_Q90 = 1, 9。

2. 共変量ループでの変数のシャドーイング — 系列ごとの共変量辞書を作成するとき、内包表記の変数に外側のループ変数を使用しないでください。

3. CSV 列名の誤り — global-temperature CSV で使用する列名は anomaly ではなく anomaly_c です。最初に df.columns を出力してください。

4. forecast_with_covariates() には TimesFM 2.5 が必要 — TimesFM 1.0 にはこのメソッドがありません。

5. 将来の共変量は予測期間全体をカバーする必要があります — 動的共変量には、コンテキスト期間と予測期間の両方の値が必要です。

6. コンテキストの異常検知には残差を使用 — まずトレンドを除去し、その後 Z スコアを計算します。生の Z スコアは、トレンドのあるデータでは誤解を招きます。

検証と確認

# Anomaly detection regression:
python -c "
import json
d = json.load(open('examples/anomaly-detection/output/anomaly_detection.json'))
assert d['context_summary']['critical'] >= 1, 'Sep 2023 must be CRITICAL'
print('Anomaly detection: PASS')"

# Covariates regression:
python -c "
import pandas as pd
df = pd.read_csv('examples/covariates-forecasting/output/sales_with_covariates.csv')
assert len(df) == 108, f'Expected 108 rows, got {len(df)}'
print('Covariates: PASS')"