Google 时间序列基础模型 TimesFM 3.0 发布

TimesFM（Time Series Foundation Model）是 Google Research 开发的预训练时间序列基础模型，用于时间序列预测。

论文：A decoder-only foundation model for time-series forecasting，ICML 2024。

（新增！）TimesFM 3.0 Checkpoint：google/timesfm-3.0-pytorch。

Checkpoints（最高 2.5 版）：TimesFM Hugging Face Collection。

Google Research 博客（TimesFM 3.0 新博客文章即将发布！）。

TimesFM 在 Google 第一方产品中的应用：BigQuery ML：企业级 SQL 查询，兼顾可扩展性与可靠性。Google Sheets：适用于日常电子表格。Vertex Model Garden：支持 Agent 调用的 Docker 化端点。

BigQuery ML：企业级 SQL 查询，兼顾可扩展性与可靠性。

Google Sheets：适用于日常电子表格。

Vertex Model Garden：支持 Agent 调用的 Docker 化端点。

此开源版本并非 Google 官方支持的产品。

最新模型版本：TimesFM 3.0

历史模型版本：

2.5：相关代码位于 src/timesfm。

1.0 和 2.0：相关代码归档于 v1 子目录。可通过 pip install timesfm==1.3.0 安装旧版包来加载它们。

TimesFM 3.0 原生支持多变量时间序列预测、灵活的协变量支持（既支持纯历史协变量，也支持历史+未来协变量）、卓越的零样本泛化能力，并在三大主流时间序列基础模型基准测试中均取得顶级表现。

原生多变量和单变量预测（含协变量）：无缝预测多通道多变量序列以及单个单变量序列，原生支持纯历史和历史+未来动态协变量，无需针对每个任务进行调优。

基准测试顶级表现：🥇 fev-bench：100 个真实世界预测任务综合排名第 1。🥇 TIME Benchmark：50 个领域数据集和 98 个评估任务综合排名第 1。🥇 GIFT-Eval：所有基础模型中排名第 1。

🥇 fev-bench：100 个真实世界预测任务综合排名第 1。

🥇 TIME Benchmark：50 个领域数据集和 98 个评估任务综合排名第 1。

🥇 GIFT-Eval：所有基础模型中排名第 1。

预训练权重许可声明

重要提示：本仓库中的 TimesFM 源代码采用 Apache-2.0 许可，2.5 版及之前的模型权重同样采用 Apache-2.0。然而，TimesFM 3.0 预训练权重目前采用单独的 timesfm-non-commercial-license-v1.0 许可分发，仅允许非商业、非生产环境使用。默认预训练权重的商业或生产用途不被许可。

更新——2026 年 7 月 2 日

PyPI 已更新至 timesfm=2.0.2。参见安装说明。

更新——2026 年 4 月 9 日

新增使用 HuggingFace Transformers + PEFT（LoRA）进行微调的示例——参见 timesfm-forecasting/examples/finetuning/。同时新增了单元测试（tests/）并整合了多项社区修复。

感谢 @kashif 和 @darkpowerxo。

更新——2026 年 3 月 19 日

非常感谢 @borealBytes 增加了对 AGENTS 的支持！TimesFM SKILL.md 已发布。

更新——2025 年 10 月 29 日

为 TimesFM 2.5 重新加入了通过 XReg 实现协变量支持。

更新——2025 年 9 月 15 日

与 TimesFM 2.0 相比，新版 2.5 模型：

参数量从 500M 降至 200M。

上下文长度从 2048 扩展至最多 16k。

通过可选的 30M 分位数预测头支持最远 1k 范围的连续分位数预测。

移除了频率指示器。

新增了若干新的预测标志位。

自 2025 年 9 月发布以来，TimesFM 2.5 已完成以下改进：

✅ 更快推理的 Flax 版模型。

✅ 通过 XReg 实现协变量支持（参见 2025 年 10 月更新）。

✅ 文档、示例和 Agent 技能（参见 timesfm-forecasting/）。

✅ 通过 HuggingFace Transformers + PEFT 实现 LoRA 微调示例（参见 timesfm-forecasting/examples/finetuning/）。

✅ 核心层、配置和工具函数的单元测试（参见 tests/）。

# Install TimesFM with PyTorch
pip install timesfm[torch]

克隆仓库：

git clone https://github.com/google-research/timesfm.git
cd timesfm

创建虚拟环境并安装 PyTorch 版本：

# Using uv
uv venv
source .venv/bin/activate

 # Install the package in editable mode with torch
uv pip install -e .[torch]

代码示例：TimesFM 3.0

传入一批不同上下文长度的 1 维 NumPy 数组以预测单变量时间序列：

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

# Initialize TimesFM 3.0
config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"
)
forecaster = TimesFM3Evaluator(config)

# Two univariate series of different lengths (100 and 72 steps)
ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)

# Generate forecast (point predictions + 9 quantiles: 0.1 to 0.9)
outputs = list(forecaster.predict_batch([ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False))

print("Series 1 forecast shape:", outputs[0].forecast.shape)   # (12,)
print("Series 1 quantiles shape:", outputs[0].quantiles.shape) # (12, 9)

print("Series 2 forecast shape:", outputs[1].forecast.shape)   # (12,)
print("Series 2 quantiles shape:", outputs[1].quantiles.shape) # (12, 9)

传入形状为 (num_variates, context_length) 的 2 维数组，并附带可选的纯历史协变量和历史+未来协变量：

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

# Initialize TimesFM 3.0
config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=16,
    device="cuda"
)
forecaster = TimesFM3Evaluator(config)

context_len = 128
horizon = 24

# 3 target variates across past context: (3, 128)
target = np.random.randn(3, context_len).astype(np.float32)

# 1 past-only covariate channel across past context: (1, 128)
past_only_cov = np.random.randn(1, context_len).astype(np.float32)

# 2 past-and-future covariate channels across context + horizon: (2, 152)
past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32)

# Generate joint forecast across all 3 target variates
outputs = list(
    forecaster.predict_batch(
        contexts=[target],
        horizon=horizon,
        past_only_covariates=[past_only_cov],
        past_future_covariates=[past_future_cov],
        return_quantiles=True,
        use_symmetric_averaging=False,
    )
)

print("Multivariate forecast shape:", outputs[0].forecast.shape)   # (3, 24)
print("Multivariate quantiles shape:", outputs[0].quantiles.shape) # (3, 24, 9)