TimesFMの使い方完全ガイド【インストールから応用まで】
時系列予測は、ビジネスの意思決定において不可欠な要素です。例えば、小売業の在庫管理や金融市場のトレンド分析、製造業の故障予知など、様々な分野でその重要性が高まっています。
しかし、従来の時系列予測モデルの構築は、専門知識と多くの時間が必要です。データの特性に応じたモデル選択や、複雑な特徴量エンジニアリングが求められてきました。予測精度を高めるためには、何度も試行錯誤を繰り返す必要がありました。
そんな中、Google Researchが開発した「TimesFM」は、この課題を根本から解決します。大規模な時系列データで事前学習された基盤モデルにより、少ない労力で高精度な予測を実現できます。これにより、開発者はモデル構築の手間から解放され、より本質的なビジネス価値創出に集中できるようになるでしょう。
本記事では、TimesFMのインストールから基本的な使い方、さらには実践的な応用例までを詳しく解説します。
TimesFMとは
TimesFM (Time Series Foundation Model) は、Google Researchが開発した時系列予測のための基盤モデルです。まるで大規模言語モデル (LLM) が自然言語を理解するように、TimesFMは時系列データのパターンを学習しています。
このモデルは、数百万の時系列データセットで事前学習されています。そのため、特定のドメインに特化した追加学習(ファインチューニング)なしでも、高い予測性能を発揮します。従来のモデルでは難しかった、多様な時系列データに対する汎用的な予測を可能にするのがTimesFMの最大の特長です。
誕生した背景
従来の時系列予測モデルは、データの周期性やトレンドを仮定するものが多く、柔軟性に欠ける側面がありました。また、モデルごとに異なる前処理やパラメータ調整が必要でした。
近年、Transformerアーキテクチャに代表されるディープラーニング技術が進化しました。これにより、LLMのような大規模な基盤モデルが誕生しています。Google Researchは、この基盤モデルの概念を時系列予測に応用しました。その結果、大規模なデータから汎用的な時系列のパターンを学習できるTimesFMが生まれました。
TimesFMは、予測モデル構築の障壁を下げ、誰もが手軽に高精度な時系列予測を利用できる未来を目指しています。
インストール方法
TimesFMはPythonのパッケージとして提供されています。pip コマンドを使って簡単にインストールできます。PyTorchとFlaxの2つのバックエンドが選択可能です。また、共変量(外部要因)を取り扱うためのXRegオプションもあります。
PyPIからのインストール
最も一般的なインストール方法です。お使いの環境に合わせて、バックエンドを選択してください。
PyTorchバックエンドでインストールする場合
pip install timesfm[torch]
Flaxバックエンドでインストールする場合
FlaxはJAXをベースとした高性能なライブラリです。高速な推論が必要な場合に適しています。
pip install timesfm[flax]
共変量サポート (XReg) も含める場合
共変量(外部要因)を用いて予測精度を高めたい場合は、XRegオプションを追加します。上記のバックエンドと組み合わせてインストールできます。
# PyTorchバックエンドとXReg
pip install timesfm[torch,xreg]
# FlaxバックエンドとXReg
pip install timesfm[flax,xreg]
ローカルからのインストール(開発者向け)
TimesFMのリポジトリをクローンし、開発環境をセットアップする方法です。主に開発や貢献を行う場合に利用します。uv コマンドは高速なPythonパッケージインストーラです。
リポジトリのクローン
git clone https://github.com/google-research/timesfm.git cd timesfm仮想環境の作成とアクティベート
uv venv source .venv/bin/activate開発モードでパッケージをインストール
バックエンドとXRegオプションは上記と同様に選択します。
# PyTorchバックエンドでインストール uv pip install -e .[torch] # Flaxバックエンドでインストール uv pip install -e .[flax] # PyTorchバックエンドとXRegを含める場合 uv pip install -e .[torch,xreg]
これでTimesFMの利用準備が整いました。
基本的な使い方
TimesFMを使った時系列予測は、以下のシンプルなステップで実行できます。ここでは、最低限のコードで予測を行う方法を解説します。
- TimesFMモデルの初期化
- 時系列データの準備
- 予測の実行
1. TimesFMモデルの初期化
TimesFMは、TimesFMクラスをインスタンス化して使用します。最新のTimesFM 2.5モデルは、いくつかのパラメータを持っています。load_pretrained()メソッドを呼び出すことで、Hugging Faceから事前学習済みモデルの重みが自動的にダウンロードされ、ロードされます。
例えば、以下のようにモデルを初期化します。
import numpy as np
from timesfm import TimesFM
# TimesFMモデルの初期化
# context_len: 過去のデータをどれだけ参照するか (入力時系列の長さ)
# horizon_len: どれだけ先の期間を予測するか (出力時系列の長さ)
# backend: "torch" または "flax" を指定
tfm = TimesFM(
context_len=1024, # 予測に利用する過去データの長さ
horizon_len=256, # 予測する未来データの長さ
input_patch_len=32, # 内部処理における入力パッチの長さ
output_patch_len=128, # 内部処理における出力パッチの長さ
num_layers=20, # モデルの層数
model_dims=128, # モデルの次元数
backend="torch" # PyTorchバックエンドを使用
)
# 事前学習済み重みのロード
# これにより、Hugging Faceからモデルの重みがダウンロードされます
tfm.load_pretrained()
print("TimesFMモデルが正常にロードされました。")
context_lenとhorizon_lenは、利用するデータの特性と予測したい期間に合わせて調整します。
2. 時系列データの準備
TimesFMに入力するデータは、NumPy配列として準備します。データは浮動小数点数型 (np.float32) である必要があります。複数の時系列データを一度に予測する場合、各系列は行として格納されます。
例えば、過去100日間の日次売上データが1つの系列としてある場合を考えます。
import pandas as pd
# サンプル時系列データの生成
# 例えば、過去100日間の日次売上データ
num_series = 1 # 予測したい時系列の数
context_length = 100 # 入力として使う過去データの長さ
# ランダムなデータにトレンドと季節性を少し加える例
dates = pd.date_range(start='2023-01-01', periods=context_length, freq='D')
data_series = (np.sin(np.arange(context_length) / 10) * 10
+ np.arange(context_length) * 0.5
+ np.random.rand(context_length) * 50 + 100)
# TimesFMはNumPy配列を期待します
# データは (系列数, 系列長) の形状である必要があります
# また、データ型は np.float32 にする必要があります
input_data = data_series.reshape(num_series, context_length).astype(np.float32)
print("入力データの形状:", input_data.shape)
print("入力データの最初の5要素:", input_data[0, :5])
3. 予測の実行
準備した入力データと、予測したい未来の期間 (horizon_len) を指定して、forecastメソッドを呼び出します。
# 予測したい期間 (例えば、次の7日間)
forecast_horizon = 7
# 予測の実行
# forecast_outputの形状は (系列数, 予測期間) となります
forecast_output = tfm.forecast(input_data, horizon_len=forecast_horizon)
print("\n予測結果の形状:", forecast_output.shape)
print("最初の系列の予測値 (次の{}日間):".format(forecast_horizon))
print(forecast_output[0])
# 予測結果をPandas DataFrameに変換して見やすくする例
forecast_dates = pd.date_range(start=dates.max() + pd.Timedelta(days=1),
periods=forecast_horizon, freq='D')
forecast_df = pd.DataFrame({
'Date': forecast_dates,
'Predicted_Value': forecast_output[0]
})
print("\n予測結果(DataFrame形式):")
print(forecast_df)
これで、TimesFMを使った基本的な時系列予測が完了しました。非常に少ないコードで、高精度な予測が手に入ります。
便利な使い方・応用例 3選
TimesFMは、基本的な予測だけでなく、実際の開発シーンで役立つ様々な応用が可能です。ここでは、特に有用な3つの使い方を紹介します。
1. 共変量を取り入れた高精度予測 (XReg)
時系列データには、曜日、祝日、プロモーション活動、気温など、外部の要因が影響を与えることがよくあります。TimesFM 2.5では、これらの外部要因(共変量)を予測に含めることができます。これにより、予測精度を大幅に向上させることが可能です。
XReg (eXogenous REGressors) は、TimesFMが共変量を扱うための機能です。共変量データもNumPy配列として準備し、forecastメソッドのcovariates引数に渡します。
例えば、日次売上予測に曜日情報とプロモーションの有無を加える場合を考えます。
import numpy as np
import pandas as pd
from timesfm import TimesFM
# モデルの初期化 (XRegを使うので、インストール時にtimesfm[torch,xreg]が必要です)
tfm = TimesFM(
context_len=1024,
horizon_len=256,
input_patch_len=32,
output_patch_len=128,
num_layers=20,
model_dims=128,
backend="torch"
)
tfm.load_pretrained()
# 1. 時系列データの準備 (過去100日間の売上)
num_series = 1
context_length = 100
dates_context = pd.date_range(start='2023-01-01', periods=context_length, freq='D')
data_series = (np.sin(np.arange(context_length) / 10) * 10
+ np.arange(context_length) * 0.5
+ np.random.rand(context_length) * 50 + 100)
input_data = data_series.reshape(num_series, context_length).astype(np.float32)
# 2. 共変量データの準備
# 過去データ (context) と未来データ (horizon) 両方の共変量が必要です
forecast_horizon = 7
total_length = context_length + forecast_horizon
dates_total = pd.date_range(start=dates_context.min(), periods=total_length, freq='D')
# 例えば、曜日を数値で表現 (月曜=0, 火曜=1, ...)
day_of_week = dates_total.dayofweek.values.reshape(1, total_length, 1).astype(np.float32)
# 例えば、プロモーション実施フラグ (ランダムに設定)
# 0: なし, 1: あり
promotion_flag = np.random.randint(0, 2, size=(1, total_length, 1)).astype(np.float32)
# 共変量を結合 (形状: (系列数, 全長, 共変量の特徴量数))
# 例えば、曜日とプロモーションフラグの2つの共変量
covariates_data = np.concatenate([day_of_week, promotion_flag], axis=2)
print("\n共変量データの形状:", covariates_data.shape) # (1, 107, 2)
# 3. 予測の実行 (共変量を渡す)
# covariates引数に共変量データを指定します
forecast_output_with_cov = tfm.forecast(
input_data,
horizon_len=forecast_horizon,
covariates=covariates_data
)
print("\n共変量を用いた予測結果の形状:", forecast_output_with_cov.shape)
print("共変量を用いた予測値:", forecast_output_with_cov[0])
# 共変量なしの場合と比較
forecast_output_no_cov = tfm.forecast(input_data, horizon_len=forecast_horizon)
print("\n共変量なしの予測値:", forecast_output_no_cov[0])
共変量を適切に設計することで、季節性やイベントによる予測のブレを吸収し、よりロバストな予測が可能になります。
2. ファインチューニングによるドメイン特化
TimesFMは事前学習済みモデルですが、特定のドメインのデータでさらに学習させる(ファインチューニング)ことで、そのドメインに特化した予測性能を向上させることができます。Hugging Face TransformersとPEFT (Parameter-Efficient Fine-Tuning) ライブラリのLoRA (Low-Rank Adaptation) を組み合わせることで、効率的にファインチューニングが可能です。
ファインチューニングのプロセスは、TimesFMが提供するtrainメソッドや、Hugging Faceのトレーニングパイプラインを利用します。これはより高度な利用法ですが、特定の業界のデータや、非常に特殊なパターンを持つ時系列データに対して絶大な効果を発揮します。
具体的なファインチューニングのコードは複雑になるため、ここでは概念と公式の例への誘導に留めます。詳細な実装はTimesFM GitHubリポジトリのファインチューニング例を参照してください。
概念的なステップは以下のようになります。
- TimesFMモデルをHugging Face形式でロード
- PEFT (LoRA) の設定:モデルの一部のみを学習対象とし、効率的にファインチューニングを行います。
- ドメイン特化データセットの準備:Transformerモデルが扱える形式に変換します。
- トレーニングの実行:Hugging Faceの
Trainerクラスなどを用いて、ファインチューニングを行います。
これにより、例えば特定の製品群の需要予測や、特定の機械の故障予測など、限られたデータセットでもTimesFMの強力な学習能力を最大限に引き出すことが可能になります。
3. 大規模データに対する効率的なバッチ予測
多くの時系列データを一括で予測する場合、効率的な処理が求められます。TimesFMは、複数の時系列データを同時に処理するバッチ予測に対応しています。また、Flaxバックエンドを選択することで、さらに高速な推論が期待できます。
例えば、1000店舗のそれぞれ異なる商品の売上を同時に予測する場合を考えます。
import numpy as np
from timesfm import TimesFM
# モデルの初期化 (Flaxバックエンドで高速化)
# インストール時にtimesfm[flax]が必要です
tfm = TimesFM(
context_len=1024,
horizon_len=256,
input_patch_len=32,
output_patch_len=128,
num_layers=20,
model_dims=128,
backend="flax" # Flaxバックエンドを指定
)
tfm.load_pretrained()
# 複数の時系列データを準備
num_series_to_forecast = 1000 # 1000個の異なる時系列を予測
context_length = 100
# 各系列は異なるパターンを持つと仮定
multi_series_data = np.random.rand(num_series_to_forecast, context_length) * 100 + 50
multi_series_data = multi_series_data.astype(np.float32)
print("複数系列入力データの形状:", multi_series_data.shape) # (1000, 100)
# 予測したい期間
forecast_horizon = 7
# バッチ予測の実行
# 入力データは (系列数, 入力長) の形状です
batch_forecast_output = tfm.forecast(multi_series_data, horizon_len=forecast_horizon)
print("\nバッチ予測結果の形状:", batch_forecast_output.shape) # (1000, 7)
print("最初の3系列の予測値:")
print(batch_forecast_output[:3])
このように、複数の時系列データをまとめてforecastメソッドに渡すことで、効率的に大量の予測を生成できます。Flaxバックエンドと組み合わせることで、特にGPUやTPU環境での推論速度が向上し、大規模な予測タスクに対応できます。
他ツールとの組み合わせ
TimesFMは単体でも強力ですが、他のツールと組み合わせることで、より高度な時系列予測パイプラインを構築できます。
1. Pandas / NumPy
- 役割: データ前処理、特徴量エンジニアリング、予測結果の後処理。
- 組み合わせ方:
- データ準備: 生データをPandas DataFrameで読み込み、欠損値処理、日付インデックスの操作、共変量の生成を行います。その後、TimesFMが期待するNumPy配列 (
np.float32) に変換します。 - 結果分析: TimesFMから得られた予測結果をPandas DataFrameに戻し、元のデータと結合して可視化や評価を行います。
- データ準備: 生データをPandas DataFrameで読み込み、欠損値処理、日付インデックスの操作、共変量の生成を行います。その後、TimesFMが期待するNumPy配列 (
2. Matplotlib / Seaborn
- 役割: 予測結果の可視化、モデル性能の評価。
- 組み合わせ方:
- TimesFMで得られた予測値と実際の値を、グラフとして比較します。これにより、予測の精度や傾向を視覚的に把握できます。
- 例えば、過去の時系列データと未来の予測データを一本の折れ線グラフで表示し、予測区間を塗りつぶしで示すことも可能です。
3. Hugging Face Transformers / PEFT (LoRA)
- 役割: TimesFMのファインチューニング、モデルのカスタマイズ。
- 組み合わせ方:
- TimesFMはTransformerベースのモデルであり、Hugging Faceのエコシステムと親和性が高いです。
- 特定のドメインデータでTimesFMをファインチューニングする際に、Hugging Face Transformersの
TrainerやPEFTライブラリのLoRAを組み合わせます。これにより、効率的かつ効果的にモデルをドメイン特化させられます。
4. Databricks / Apache Spark
- 役割: 大規模データ処理、MLパイプラインの構築。
- 組み合わせ方:
- Databricks環境では、Apache Sparkを用いて大量の時系列データを前処理し、TimesFMが利用できる形式に変換します。
- 予測結果もSpark DataFrameに格納し、後続の分析やBIツールとの連携に活用できます。
- 提供された参考記事「GenAI for Time Series Analysis with TimesFM」もDatabricks環境での利用例を詳述しています。
5. BigQuery ML / Google Sheets
- 役割: Google Cloudエコシステムでの大規模な時系列予測、ビジネスユーザー向けの簡単な予測。
- 組み合わせ方:
- TimesFMは、Googleのプロダクト(BigQuery ML、Google Sheets)にも組み込まれています。
- オープンソース版のTimesFMで開発した知見を、BigQuery MLの
CREATE MODEL文やGoogle Sheetsの予測機能に活用できます。特に、BigQuery MLはSQLインターフェースで大規模なデータに対する予測を簡単に実行できます。
これらのツールとTimesFMを組み合わせることで、データ収集から前処理、モデル学習、予測、評価、デプロイまで、一貫した時系列予測ソリューションを構築することが可能です。
よくある設定・カスタマイズ
TimesFMの予測性能や動作は、初期化時に指定するいくつかのパラメータによって調整できます。ここでは、特に重要な設定とそのカスタマイズについて解説します。
1. コンテキスト長と予測期間 (context_len, horizon_len)
context_len: 予測に利用する過去の時系列データの長さです。- 設定のヒント: データの周期性(例えば、週次、月次、年次)を考慮し、その周期が複数回含まれる長さを設定すると良いでしょう。例えば、週次パターンがあるなら
7の倍数、月次パターンがあるなら30や365などです。長すぎると計算コストが増え、短すぎると必要な情報が不足します。 - 例: 過去1年間の日次データ(365日)をコンテキストとして利用する場合、
context_len=365とします。
- 設定のヒント: データの周期性(例えば、週次、月次、年次)を考慮し、その周期が複数回含まれる長さを設定すると良いでしょう。例えば、週次パターンがあるなら
horizon_len: 予測したい未来の期間の長さです。- 設定のヒント: ビジネス要件に合わせて設定します。例えば、来週の需要予測なら
7、来月の売上予測なら30などです。 - 例: 次の30日間の予測を行いたい場合、
horizon_len=30とします。
- 設定のヒント: ビジネス要件に合わせて設定します。例えば、来週の需要予測なら
これらのパラメータは、モデルの初期化時に指定します。
tfm = TimesFM(
context_len=512, # 過去512日間のデータを参照
horizon_len=60, # 次の60日間を予測
# その他のパラメータ...
backend="torch"
)
tfm.load_pretrained()
2. バックエンドの選択 (backend)
backend: モデルの計算に利用するフレームワークです。"torch"(PyTorch) または"flax"(JAX/Flax) を選択できます。- 設定のヒント:
- PyTorch (
"torch"): 柔軟性が高く、幅広い環境で利用しやすいです。デバッグやカスタマイズの際に情報を見つけやすい場合があります。 - Flax (
"flax"): JAXを基盤としており、特にTPUやGPU環境での高速な推論に適しています。大規模なバッチ予測や低レイテンシーが求められる場合に有効です。
- PyTorch (
- 設定のヒント:
backend="flax"を選択します。インストール時に対応するバックエンドの依存関係 (timesfm[flax]) を含める必要があります。3. モデルの内部パラメータ (input_patch_len, output_patch_len, num_layers, model_dims)
これらのパラメータは、TimesFMモデルの内部アーキテクチャに関連します。通常、デフォルト値で十分な性能を発揮しますが、特定のユースケースで最適化したい場合に調整を検討します。
input_patch_len/output_patch_len: 時系列データを分割するパッチの長さ。num_layers: Transformerモデルの層の数。model_dims: モデルの次元数(埋め込みサイズ)。
これらの値を大きくするとモデルの表現力が増しますが、計算コストも増加します。小規模なデータやリソースが限られている場合は、これらの値を小さくすることも検討できます。
設定ファイルの例(概念)
TimesFM自体には直接的な設定ファイル形式はありません。しかし、Pythonスクリプトでこれらのパラメータを管理する際には、設定オブジェクトや辞書を使うと良いでしょう。
# config.py (設定ファイルを模したPythonモジュール)
MODEL_CONFIG = {
"context_len": 720, # 約2年分のデータ
"horizon_len": 90, # 3ヶ月先を予測
"input_patch_len": 32,
"output_patch_len": 128,
"num_layers": 20,
"model_dims": 128,
"backend": "torch",
"use_xreg": True # 共変量を使うかどうかをカスタム設定として持つ
}
# main_forecast.py (メインの予測スクリプト)
from timesfm import TimesFM
from config import MODEL_CONFIG
# 設定を読み込んでモデルを初期化
tfm = TimesFM(
context_len=MODEL_CONFIG["context_len"],
horizon_len=MODEL_CONFIG["horizon_len"],
input_patch_len=MODEL_CONFIG["input_patch_len"],
output_patch_len=MODEL_CONFIG["output_patch_len"],
num_layers=MODEL_CONFIG["num_layers"],
model_dims=MODEL_CONFIG["model_dims"],
backend=MODEL_CONFIG["backend"]
)
tfm.load_pretrained()
# ... データ準備と予測実行 ...
このように設定を分離することで、異なる環境やユースケースに応じてパラメータを簡単に切り替え、管理しやすくなります。
今日からできる実行プラン
TimesFMの導入は、以下の3つのステップでスムーズに開始できます。
ステップ1: 環境準備と基本インストール (所要時間: 30分)
まずは、TimesFMを動かすための環境を整えましょう。
- Python環境の確認: Python 3.8以降がインストールされていることを確認します。推奨は仮想環境の利用です。
python --version - TimesFMのインストール: 記事で紹介した
pip install timesfm[torch]コマンドでインストールします。共変量を使用する予定があればtimesfm[torch,xreg]を選択してください。pip install timesfm[torch] - Hugging Faceの認証設定(オプション): 事前学習済みモデルのダウンロードで問題が発生する場合、Hugging Face Hubの認証が必要になることがあります。Hugging Faceアカウントを作成し、トークンを設定します。
これは必須ではありませんが、安定した利用のために推奨されます。pip install huggingface_hub huggingface-cli login
ステップ2: サンプルデータでの動作確認 (所要時間: 1時間)
インストールが完了したら、簡単なサンプルデータでTimesFMの動作を確認します。これにより、モデルが正しくロードされ、予測が実行できることを確認します。
- 基本コードの実行: 記事の「基本的な使い方」セクションにあるコードをコピーし、Pythonスクリプトとして保存(例:
timesfm_quickstart.py)。 - スクリプトの実行: ターミナルでスクリプトを実行します。
python timesfm_quickstart.py - 出力の確認: 予測結果が正常に出力されることを確認します。予測値の形状や内容が期待通りかを確認しましょう。
このステップでTimesFMの基本的な予測フローを体験できます。
ステップ3: 応用的な利用の検討と実装 (所要時間: 3時間〜)
基本動作が確認できたら、次は自身のデータや具体的なユースケースに合わせてTimesFMを応用しましょう。
- 自身のデータ準備: 予測したい実際の時系列データを用意します。Pandasを使って整形し、TimesFMが期待するNumPy配列 (
(系列数, 系列長)の形状、np.float32型) に変換します。 - 共変量の検討: 予測精度向上のため、曜日、祝日、イベントフラグ、気温などの共変量を検討します。過去と未来の両方の共変量データを作成し、記事の「共変量を取り入れた高精度予測」を参考に実装します。
- 予測結果の可視化と評価: MatplotlibやSeabornを用いて、実際のデータとTimesFMの予測結果を比較します。予測の傾向や誤差を確認し、モデルの性能を評価します。
- ファインチューニングの検討(上級者向け): もし予測対象のデータが非常に特殊な場合や、さらに高い精度が求められる場合は、ファインチューニングを検討します。TimesFMのGitHubリポジトリにあるファインチューニング例を参考に、PEFT (LoRA) を用いた追加学習を試してみましょう。
これらのステップを通じて、TimesFMを自身のプロジェクトに統合し、時系列予測の課題を解決する強力なツールとして活用できます。
参考文献
- GenAI for Time Series Analysis with TimesFM
- Building an Open Ecosystem for Time Series Forecasting: Introducing TimesFM in Hugging Face
- Google Research TimesFM GitHub Repository
- A decoder-only foundation model for time-series forecasting (arXiv Paper)
- TimesFM Hugging Face Collection