Timestral – 時系列基盤モデル

概要 – Timestral は、多変量確率的時系列予測のための事前学習済みトランスフォーマーモデル群です。リポジトリには推論コードのみが含まれており、モデルの重みは Hugging Face にあります。

主な機能

• 最大 32,000 ステップの履歴コンテキストを使用して、複数の変数を同時に予測します。
• 過去のみ、既知の将来、カテゴリカル共変量（数値またはワンホット類似）を処理します。
• 水平線ステップごとに 21 個の分位数（非交差）を返し、完全な予測分布を提供します。
• 4 つのモデルサイズ（5M、28M、123M、209M）があり、精度とフットプリントのトレードオフがあります。209M バージョンは、3 つの公開ベンチマーク（GIFT-Eval、TIME、fev-bench）でゼロショットモードで上位を獲得しました。
• CPU フレンドリーな推論。利用可能であれば GPU でも動作します。

インストール

pip install git+https://github.com/mistralai/timestral.git   # Python ≥3.10, torch ≥2.4

または、uv で正確に固定された依存関係を同期するためにクローンします。

典型的な使用法

import numpy as np
from timestral import TimestralForecaster

forecaster = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-209M", device="cpu"
)

# context: (batch, variates, time) – NaN marks missing values
context = np.random.randn(2, 1, 2000).cumsum(-1)
forecast = forecaster.forecast(context, prediction_length=96)

print(forecast.quantiles.shape)   # (2, 1, 96, 21)
print(forecast.median.shape)      # (2, 1, 96)

オプション引数で以下を渡せます：

• past_covariates（履歴ウィンドウでのみ既知）
• known_covariates（予測水平線に拡張）
• categorical_*_covariates（数値カテゴリコード、内部的にターゲットエンコード）

モデル zoo – 重みは Mistral AI 組織の下で Hugging Face にホストされています：

モデル	リポジトリ	サイズ
Timestral‑5M	mistralai/Timestral-5M	21 MB
Timestral‑28M	mistralai/Timestral-28M	111 MB
Timestral‑123M	mistralai/Timestral-123M	490 MB
Timestral‑209M	mistralai/Timestral-209M	837 MB

TimestralForecaster.from_pretrained は config.json と model.safetensors を自動的にダウンロードします。

アーキテクチャの概要 – Decoupled Horizon Forecasting でトレーニングされた因果パッチベースのトランスフォーマー。個別の予測トークンがエンコードされたコンテキストを読み取り、分位数ヘッドがステップごとに 21 個の非交差分位数を出力します。共変量行は読み取り専用です。既知の将来共変量は水平線を参照しますが、ターゲットトークンを読み取ることはありません。

ライセンス – コードは Apache 2.0 です。モデルの重みは修正 MIT ライセンス（各 Hugging Face リポジトリを参照）の下でリリースされています。重みの使用はそのライセンスを尊重する必要があります。

サポート – プルリクエストは受け付けていません。バグや質問は GitHub で issue を開いてください。