TimesFM

TimesFM (时间序列基础模型) 是由 Google Research 开发的一个预训练时间序列预测模型。

• 论文： A decoder-only foundation model for time-series forecasting, ICML 2024。
• 所有检查点： TimesFM Hugging Face Collection。
• Google Research 博客。
• TimesFM 在 Google 1P 产品中的应用：
  • BigQuery ML：企业级 SQL 查询，用于可扩展性和可靠性。
  • Google Sheets：适用于您的日常电子表格。
  • Vertex Model Garden：用于代理调用的 Docker 化端点。

此开源版本不是 Google 官方支持的产品。

最新模型版本： TimesFM 2.5

已归档的模型版本：

• 1.0 和 2.0：相关代码归档在子目录 v1 中。您可以通过 pip install timesfm==1.3.0 安装此包的旧版本来加载它们。

更新 - 2026年6月5日

将 PyPI 更新为 timesfm=2.0.0。请参阅 安装。

更新 - 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日

通过 XReg 为 TimesFM 2.5 添加了协变量支持。

更新 - 2025年9月15日

TimesFM 2.5 已发布！

与 TimesFM 2.0 相比，这个新的 2.5 模型：

• 参数量从 500M 减少到 200M。
• 支持高达 16k 的上下文长度，从 2048 增加到。
• 通过可选的 30M 分位数头支持高达 1k 的连续分位数预测。
• 移除了 frequency 指示器。
• 添加了一些新的预测标志。

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

1. ✅ Flax 版本的模型，用于更快的推理。
2. ✅ 通过 XReg 的协变量支持（参见 2025 年 10 月更新）。
3. ✅ 文档、示例和代理技能（参见 timesfm-forecasting/）。
4. ✅ 使用 HuggingFace Transformers + PEFT 的 LoRA 微调示例（参见 timesfm-forecasting/examples/finetuning/）。
5. ✅ 核心层、配置和工具的单元测试（参见 tests/）。

安装

从 PyPI

# 使用 torch 安装包
pip install timesfm[torch]
# 或使用 Flax
pip install timesfm[flax]
# 当需要 XReg 时
pip install timesfm[xreg]

本地安装

1. 克隆仓库：

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

2. 创建虚拟环境并使用 uv 安装依赖：

   # 创建虚拟环境
   uv venv
   
   # 激活环境
   source .venv/bin/activate
   
   # 以可编辑模式安装包，使用 torch
   uv pip install -e .[torch]
   # 或使用 flax
   uv pip install -e .[flax]
   # 当需要 XReg 时
   uv pip install -e .[xreg]
   

3. [可选] 根据您的操作系统和加速器（CPU、GPU、TPU 或 Apple Silicon）安装您首选的 torch / jax 后端：

• 安装 PyTorch。
• 安装 Jax 用于 Flax。

代码示例

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)),
    ],  # 两个虚拟输入
)
point_forecast.shape  # (2, 12)
quantile_forecast.shape  # (2, 12, 10)：均值，然后是第 10 到第 90 个分位数。