alterlab-timesfm

TimesFM Forecasting

概要

TimesFM（Time Series Foundation Model）は、Google Research が開発した、時系列予測用の事前学習済みデコーダー専用基盤モデルです。ゼロショットで動作します。時系列を入力すると、学習を必要とせず、分位点予測区間を伴う点予測を返します。timesfm パッケージ（現行バージョン 3.0.2）には、2 つのモデル API が含まれています。

• TimesFM 2.5（2 億、Apache-2.0 の重み） — ForecastConfig を使用する timesfm.TimesFM_2p5_200M_torch。単変量で、XReg を介したオプションの共変量に対応します。このスキルのデフォルトであり、商用または本番環境で使用できる唯一の選択肢です。
• TimesFM 3.0（約 3 億 3,000 万、2026 年 8 月リリース） — timesfm3.TimesFM3Forecaster。単変量および多変量の予測に対応し、過去のみ、および過去と未来の共変量をネイティブに扱います。重みには timesfm-non-commercial-license-v1.0 が適用されるため、非商用の研究にのみ使用し、制限についてユーザーに伝えてください。

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

主な数値：TimesFM 2.5 は 2 億パラメーター（0.93 GB の safetensors）を使用し、TimesFM 3.0 は約 3 億 3,000 万パラメーター（1.3 GB）を使用します。初回の読み込み前にシステムチェッカーを実行してください。リソース不足のマシンでスワップやクラッシュが発生する前に、速やかに失敗させることができます。

このスキルを使う場面

次のような場合にこのスキルを使ってください。

• あらゆる単変量時系列（売上、需要、センサー、バイタル、価格、天候）を予測する
• カスタムモデルを学習させずにゼロショット予測を行う
• 校正済みの予測区間（分位点）を伴う確率的予測を行う
• 長さを問わない時系列を扱う（モデルは 1～16,384 個のコンテキストポイントを処理できます）
• 数百から数千の系列を効率よくバッチ予測する
• ARIMA／ETS のパラメーターを手動で調整する代わりに、基盤モデルの手法を使う
• 関連するチャネルや既知の将来要因を扱う（多変量と共変量には TimesFM 3.0、または TimesFM 2.5 の XReg）

対象外

シナリオ	代わりに使うもの
解釈可能な係数を持つ古典的モデル（ARIMA／SARIMAX の表）、VAR、またはグレンジャー因果性検定	alterlab-statsmodels
時系列の分類、クラスタリング、セグメンテーション、または類似性検索	alterlab-aeon
予測を行う前に時系列ファイルの構造と品質を調べる	alterlab-eda
表形式データ（時系列ではないデータ）の予測	alterlab-scikit-learn

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

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

マシンで初めてモデルを読み込む前に、システムチェッカーを実行してください。読み込み時に約 1 GB の重みがダウンロードされ、数 GB の RAM が割り当てられます。チェッカーを実行すると、読み込みによるクラッシュやスワップを防ぎ、明確なメッセージを表示して早期に停止します。

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 3.0（非商用ウェイト）	約330M	≥ 6 GB	≥ 4 GB	約1.3 GB	最大15,360
TimesFM 2.5（デフォルト）	200M	≥ 4 GB	≥ 2 GB	約0.9 GB	最大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を使用してください（最小サイズ、Apache-2.0、ForecastConfig による完全な制御が可能）。多変量ターゲットやネイティブ共変量を扱う場合は、非商用ライセンスが プロジェクトに適合するならTimesFM 3.0を使用してください。1.0／2.0のチェックポイントには timesfm==1.3.0 が必要で、過去の結果を再現する場合にのみ使用する価値があります。32系列 × コンテキスト長1,024で計測したCPUメモリのピーク値（timesfm 3.0.2）は、2.5で約2.0 GB、3.0で約2.7 GBです。上記のしきい値には余裕を持たせています。python scripts/check_system.py --model v3.0 で3.0を確認してください。

🔧 インストール

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

python scripts/check_system.py

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

uv pip install "timesfm[torch]"          # TimesFM 2.5 + 3.0, PyTorch backend
uv pip install "timesfm[torch,xreg]"     # + XReg covariates for TimesFM 2.5 (adds JAX, scikit-learn)
uv pip install "timesfm[mlx]"            # TimesFM 3.0 on Apple silicon without PyTorch
uv pip install "timesfm[flax]"           # TimesFM 2.5 JAX/Flax backend

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

# CPU-only wheels (small download, no CUDA libraries)
uv pip install torch --index-url https://download.pytorch.org/whl/cpu

# NVIDIA GPU: take the CUDA-specific index URL from https://pytorch.org/get-started/locally/
# Apple Silicon: the default PyPI wheel already includes MPS support
uv pip install torch

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

from importlib.metadata import version
import timesfm  # noqa: F401  (import check)
print(f"TimesFM version: {version('timesfm')}")  # the package defines no __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

TimesFM 3.0（多変量、ネイティブ共変量）

import numpy as np
from timesfm3 import TimesFM3Forecaster  # non-commercial weights — see license note above

forecaster = TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch", device="cpu")  # or "cuda"

out = forecaster.predict(np.sin(np.linspace(0, 40, 512)).astype(np.float32),
                         horizon=24, return_quantiles=True)
# out.forecast.shape == (24,)      — median forecast
# out.quantiles.shape == (24, 9)   — q10..q90; index 4 is the median (no mean column)

# Two target channels plus one known-future covariate (context 256, horizon 32)
target = np.stack([np.sin(np.linspace(0, 24, 256)), np.cos(np.linspace(0, 24, 256))]).astype(np.float32)
future_cov = np.sin(np.linspace(0, 30, 256 + 32))[None, :].astype(np.float32)
out = forecaster.predict(target, horizon=32, past_future_covariates=future_cov, return_quantiles=True)
# out.forecast.shape == (2, 32); out.quantiles.shape == (2, 32, 9)

パラメーターの全一覧（predict_batch、past_only_covariates、make_positive、…）： references/api_reference.md。

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, :, 1],  # q10 — lower bound of 80% PI
        "upper_80": quantiles[i, :, 9],  # q90 — upper bound of 80% PI
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

共変量を使った予測（XReg）

TimesFM 2.5は、forecast_with_covariates() を通じて外生変数をサポートします。timesfm[xreg] と return_backcast=True でコンパイルしたモデルが必要です（そうでない場合は ValueError が発生します）。TimesFM 3.0では、共変量を predict() に直接渡します（上記を参照）。

# Requires: uv pip install "timesfm[torch,xreg]"
model.compile(timesfm.ForecastConfig(
    max_context=1024, max_horizon=256, normalize_inputs=True,
    use_continuous_quantile_head=True, fix_quantile_crossing=True,
    return_backcast=True,
))
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 / quantiles: one array per series — (horizon,) and (horizon, 10)

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

XRegモード：

• "xreg + timesfm"（デフォルト）：最初に共変量に対するインコンテキスト線形回帰を当てはめ、その後TimesFMが回帰残差を予測します
• "timesfm + xreg"：最初にTimesFMが予測し、その後共変量に対する線形回帰でTimesFMの残差を当てはめます

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

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

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

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

# 80% prediction interval
lower_80 = q[0, :, 1]  # 10th percentile
upper_80 = q[0, :, 9]  # 90th percentile

# Detect anomalies: values outside the 80% CI
actual = test_values  # your holdout data
anomalies = (actual < lower_80) | (actual > upper_80)

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

重大度	条件	解釈
正常	60% CIの範囲内	予想される挙動
警告	60% CIの範囲外	通常とは異なりますが、起こり得ます
重大	80% CIの範囲外	統計的にまれ（確率 < 20%）

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

📊 出力、設定、ワークフロー

出力構造とForecastConfigの全リファレンスについては、 **references/output_and_config.md**を参照してください。

分位点の配置（TimesFM 2.5）： quantile_forecast の形状は (batch, horizon, 10) です。 インデックス0は平均値です。q10 = インデックス1、q50（中央値）= インデックス5、q90 = インデックス9なので、80% PIは q[:,:,1]～q[:,:,9]です。TimesFM 3.0は9列（q10～q90）を返し、中央値は インデックス4です。モデルを切り替える場合は、インデックスを再確認してください。

コピーして使えるワークフロー（単一系列、バッチ、精度評価）、GPU／メモリのパフォーマンス調整、 およびstatsmodels／matplotlib／EDAとの統合については、 **references/workflows.md**を参照してください。

📚 スクリプト

• scripts/check_system.py — 必須の事前チェックツールです。初回のモデル読み込み前に実行してください。RAM／GPU／ディスク／Python／インストール状況と、推奨される per_core_batch_size を報告します。
• 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/output_and_config.md	出力形状、分位点インデックスマップ、ForecastConfig パラメーターの完全なリファレンス
references/workflows.md	単一／バッチ／評価のワークフロー、GPU とメモリの調整、statsmodels／matplotlib／EDA との統合
references/pitfalls_and_validation.md	よくある落とし穴、品質チェックリスト、既知の間違い、回帰ベースラインの検証
references/system_requirements.md	ハードウェアの各ティア、GPU／CPU の選択、メモリ見積もり式
references/api_reference.md	from_pretrained オプションの全一覧、API の概要、出力形状
references/data_preparation.md	入力形式、NaN の処理、CSV の読み込み、共変量の設定

タスクを完了とする前に、品質チェックリストを実行し、references/pitfalls_and_validation.md のよくある落とし穴／間違いを確認してください。 特に、分位点インデックスのオフバイワンと、負の系列に対する infer_is_positive に注意してください。

モデルのバージョン

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
    section 2026
        TimesFM 3.0 : ~330M params, 15K context, multivariate + covariates, non-commercial weights

バージョン	パラメーター数	コンテキスト	分位点ヘッド	頻度フラグ	ステータス
3.0	~330M	15,360	✅ 9 分位	❌	最新（非商用の重み）
2.5	200M	16,384	✅ 連続（30M）	❌ 削除済み	デフォルト（Apache-2.0）
2.0	500M	2,048	✅ 固定バケット	✅ 必須	アーカイブ済み
1.0	200M	2,048	✅ 固定バケット	✅ 必須	アーカイブ済み

Hugging Face チェックポイント：

• google/timesfm-3.0-pytorch（TimesFM 3.0、非商用ライセンス）
• google/timesfm-2.5-200m-pytorch（デフォルト）
• google/timesfm-2.5-200m-flax
• google/timesfm-2.5-200m-transformers（🤗 Transformers 移植版、TimesFm2_5ModelForPrediction）
• 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

例

examples/ には、リファレンスとなる例が 3 つあります。すべて TimesFM 2.5 API を使用しています（出力は 2026-09 に timesfm 3.0.2 で再生成）。正しい API の使い方と期待される出力形状の基準として利用してください。

例	ディレクトリ	内容	使用する場面
全球気温の予測	examples/global-temperature/	基本的な model.forecast() 呼び出し、CSV -> PNG -> GIF のパイプライン、NOAA の 36 か月分のコンテキスト、60%／80% の予測区間	単変量系列の出発点として、コピーして使える基本例
異常検知	examples/anomaly-detection/	2 段階の検知：線形トレンド除去 + コンテキストに対する Z スコア、予測に対する分位点 PI、2 パネルの可視化	過去のデータと予測データの両方で外れ値検出が必要なタスク
共変量（XReg）	examples/covariates-forecasting/	forecast_with_covariates() API（TimesFM 2.5）、共変量の分解、共有軸を使った 2x2 の可視化	小売、エネルギー、または既知の外生要因がある系列

例の実行

# Global temperature (TimesFM 2.5)
cd examples/global-temperature && python run_forecast.py && python visualize_forecast.py

# Anomaly detection (TimesFM 2.5)
cd examples/anomaly-detection && python detect_anomalies.py

# Covariates (data + API walkthrough; real inference needs timesfm[torch,xreg])
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）こと。注入された異常により、予測結果で2件以上が CRITICAL となること
covariates-forecasting	output/sales_with_covariates.csv、output/covariates_data.png	CSV に108行（3店舗 x 36週間）があり、各店舗の価格配列が異なること

品質、誤り、検証

タスクの完了を宣言する前に、タスク後の品質チェックリストを実行し、既知の誤り（分位点の1つずれ、共変量の予測期間カバレッジ、残差ベースの異常検出など）を確認し、回帰ベースラインの検証スニペットを実行してください。すべて references/pitfalls_and_validation.md にあります。

AlterLab Academic Skills スイートの一部です。