Google Research / TimesFM

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting. Paper: A decoder-only foundation model for time-series forecasting, ICML 2024. All checkpoints: TimesFM Hugging Face Collection. Google Research blog. TimesFM (时间序列基础模型) 是由 Google Research 开发的用于时间序列预测的预训练基础模型。论文：《A decoder-only foundation model for time-series forecasting》，发表于 ICML 2024。所有检查点：TimesFM Hugging Face 合集。Google Research 博客。

TimesFM in Google 1P Products: BigQuery ML: Enterprise level SQL queries for scalability and reliability. Google Sheets: For your daily spreadsheet. Vertex Model Garden: Dockerized endpoint for agentic calling. This open version is not an officially supported Google product. TimesFM 在 Google 自家产品中的应用：BigQuery ML：提供企业级 SQL 查询，具备可扩展性和可靠性。Google Sheets：用于日常电子表格处理。Vertex Model Garden：提供用于智能体调用的 Docker 化端点。此开源版本并非 Google 官方支持的产品。

Latest Model Version: TimesFM 2.5. Archived Model Versions: 1.0 and 2.0: relevant code archived in the sub directory v1. You can pip install timesfm==1.3.0 to install an older version of this package to load them. 最新模型版本：TimesFM 2.5。已归档模型版本：1.0 和 2.0：相关代码已归档在子目录 v1 中。你可以通过 pip install timesfm==1.3.0 安装旧版本软件包以加载它们。

Update - June 5, 2026: Updated PyPI to timesfm=2.0.0. See Install. 更新 - 2026 年 6 月 5 日：将 PyPI 更新至 timesfm=2.0.0。详见“安装”部分。

Update - Apr. 9, 2026: Added fine-tuning example using HuggingFace Transformers + PEFT (LoRA) — see timesfm-forecasting/examples/finetuning/. Also added unit tests (tests/) and incorporated several community fixes. Shoutout to @kashif and @darkpowerxo. 更新 - 2026 年 4 月 9 日：添加了使用 HuggingFace Transformers + PEFT (LoRA) 进行微调的示例——详见 timesfm-forecasting/examples/finetuning/。此外还添加了单元测试 (tests/) 并合并了多项社区修复。特别感谢 @kashif 和 @darkpowerxo。

Update - Mar. 19, 2026: Huge shoutout to @borealBytes for adding the support for AGENTS! TimesFM SKILL.md is out. 更新 - 2026 年 3 月 19 日：特别感谢 @borealBytes 添加了对智能体 (AGENTS) 的支持！TimesFM SKILL.md 已发布。

Update - Oct. 29, 2025: Added back the covariate support through XReg for TimesFM 2.5. 更新 - 2025 年 10 月 29 日：为 TimesFM 2.5 重新添加了通过 XReg 实现的协变量支持。

Update - Sept. 15, 2025: TimesFM 2.5 is out! Comparing to TimesFM 2.0, this new 2.5 model: uses 200M parameters, down from 500M; supports up to 16k context length, up from 2048; supports continuous quantile forecast up to 1k horizon via an optional 30M quantile head; gets rid of the frequency indicator; has a couple of new forecasting flags. 更新 - 2025 年 9 月 15 日：TimesFM 2.5 发布！与 TimesFM 2.0 相比，新版 2.5 模型：参数量从 500M 降至 200M；上下文长度从 2048 提升至 16k；通过可选的 30M 分位数头支持长达 1k 预测范围的连续分位数预测；移除了频率指示器；增加了若干新的预测标志。

Since the Sept. 2025 launch, the following improvements have been completed: ✅ Flax version of the model for faster inference. ✅ Covariate support via XReg (see Oct. 2025 update). ✅ Documentation, examples, and agent skill (see timesfm-forecasting/). ✅ Fine-tuning example with LoRA via HuggingFace Transformers + PEFT (see timesfm-forecasting/examples/finetuning/). ✅ Unit tests for core layers, configs, and utilities (see tests/). 自 2025 年 9 月发布以来，已完成以下改进：✅ 用于更快推理的 Flax 版本模型。✅ 通过 XReg 实现的协变量支持（见 2025 年 10 月更新）。✅ 文档、示例和智能体技能（见 timesfm-forecasting/）。✅ 通过 HuggingFace Transformers + PEFT 使用 LoRA 进行微调的示例（见 timesfm-forecasting/examples/finetuning/）。✅ 核心层、配置和工具的单元测试（见 tests/）。

Install From PyPI

从 PyPI 安装

# Install the package with torch
pip install timesfm[torch]
# Or with Flax
pip install timesfm[flax]
# And when XReg is needed
pip install timesfm[xreg]

Local Install

本地安装

# Clone the repository:
git clone https://github.com/google-research/timesfm.git
cd timesfm

# Create a virtual environment and install dependencies using uv:
# Create a virtual environment
uv venv
# Activate the environment
source .venv/bin/activate
# Install the package in editable mode with torch
uv pip install -e .[torch]
# Or with flax
uv pip install -e .[flax]
# And when XReg is needed
uv pip install -e .[xreg]

[Optional] Install your preferred torch / jax backend based on your OS and accelerators (CPU, GPU, TPU or Apple Silicon).: Install PyTorch. Install Jax for Flax. [可选] 根据你的操作系统和加速器（CPU、GPU、TPU 或 Apple Silicon）安装你偏好的 torch / jax 后端：安装 PyTorch。安装 Jax for Flax。

Code Example

代码示例

import torch
import numpy as np
import 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_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[
        np.linspace(0, 1, 100),
        np.sin(np.linspace(0, 20, 67)),
    ], # Two dummy inputs
)

point_forecast.shape # (2, 12)
quantile_forecast.shape # (2, 12, 10): mean, then 10th to 90th quantiles.