google-research/timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

TimesFM – 時間序列預測的基礎模型

是什麼 – TimesFM（時間序列基礎模型）是一種僅使用解碼器的神經網絡，基於龐大且多樣的時間序列資料進行訓練。Google Research 發布模型權重與 Python 庫，讓您能執行零樣本預測（單變量或多元）並在自己的資料上微調模型。

為何重要 – 就如同文字領域的大規模語言模型，TimesFM 的目標是成為一個通用預測器，無需手動特徵工程，即可開箱即用地適用於多個領域（金融、能源、零售等）。該倉儲提供至版本 3.0 的預訓練檢查點，以及用於推論、評估與 LoRA 風格微調的程式碼。

主要亮點（以 README 為準）

版本 3.0 – 原生支援多變量預測，支援僅過去與過去-未來動態共變量，並在三個主要時間序列基礎模型基準（fev-bench, TIME, GIFT-Eval）上取得最佳成績。
模型大小 – 主要檢查點為 3.3 億參數；另提供更輕量的 2 億參數版本（2.5）。
長上下文 – 支援最多 16,000 個 token（2.5 版）與 15,360 個 token（完整模型），可考慮長期歷史資料進行預測。
分位數預測 – 可選的 3,000 萬參數頭可提供最多 1,000 步的分位數預測（預設 9 個分位）。
後端 – 支援標準 PyTorch 與 Apple Silicon 專用 MLX，數值結果一致。
整合點 – 可在 Google Cloud 產品（BigQuery ML、Vertex Model Garden）與 Google Sheets 中使用，面向終端使用者。
微調 – 範例腳本使用 HuggingFace Transformers + PEFT（LoRA）將模型適配至特定序列。
代理支援 – AGENTS.md 檔案說明如何從自主代理中呼叫 TimesFM。

典型應用場景

領域	TimesFM 如何幫助
業務預測（銷售、需求、庫存）	對新產品線進行零樣本預測；基於歷史銷售資料微調以提升準確性。
能源與公用事業	可同時預測包含天氣共變量的多變量負載與價格序列。
金融	在宏觀經濟共變量條件下預測多個資產價格序列。
物聯網 / 傳感器資料	用於設備健康監測的長窗口預測。
快速原型開發	透過 BigQuery ML 或 Sheets 無需撰寫程式碼即可即插即用。

快速入門（Python）

# 安裝套件（選擇後端）
pip install "timesfm[torch]"      # PyTorch（CPU/GPU）
# 或
pip install "timesfm[mlx]"        # Apple Silicon，無需 PyTorch

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"               # 或 "cpu" / "mlx"
)
forecaster = TimesFM3Evaluator(cfg)

# 單變量範例
ts = np.sin(np.linspace(0, 2*np.pi, 100)).astype(np.float32)
out = forecaster.predict_batch([ts], horizon=12, return_quantiles=True)[0]
print(out.forecast.shape)   # (12,)
print(out.quantiles.shape)  # (12, 9)

對於多變量序列，請依 README 所示傳遞 (num_variates, context_len) 陣列與可選的共變量陣列。

微調（LoRA） – 快速範例

# 克隆倉儲並安裝可編輯版本
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]

# 來自 timesfm-forecasting/examples/finetuning/
from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
from peft import LoraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("google/timesfm-3.0-pytorch")
peft_cfg = LoraConfig(r=8, lora_alpha=32, target_modules=["c_attn"])
model = get_peft_model(model, peft_cfg)
# …準備 (context, target) 對資料集並執行 Trainer…

倉儲包含可直接執行的 finetuning 腳本與單元測試。

授權

原始碼 – Apache-2.0（可自由使用、修改與分發）。
預訓練權重 – 版本 ≤2.5 為 Apache-2.0。版本 3.0 權重採用獨立的 非商業 授權（timesfm-non-commercial-license-v1.0），禁止在無額外協議的情況下用於商業或生產部署。

限制與注意事項

商業使用限制 – 最新檢查點（3.0）在未獲 Google 授權的情況下，不得用於創收產品。
硬體需求 – 完整版 3.3 億參數模型在 GPU 上運行最佳；MLX 後端僅限 Apple Silicon。
零樣本效能 – 雖在基準測試中表現領先，但特定領域資料仍可能從微調中受益。
上下文截斷 – 超過模型 global_context（15,360 個 token）的上下文將自動截斷，可能遺失極長的歷史資料。
無官方產品支援 – 倉儲聲明其為「非 Google 官方支援產品」，因此錯誤修復與更新依賴開源社群。