google-research--timesfm/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

TimesFM

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

• 论文： A decoder-only foundation model for time-series forecasting, ICML 2024。
• 全部检查点： TimesFM Hugging Face Collection.
• Google Research blog.
• TimesFM 在 Google 第一方产品中的应用：
  • BigQuery ML: 企业级 SQL 查询，兼具可扩展性与可靠性。
  • Google Sheets: 适用于日常电子表格场景。
  • Vertex Model Garden: 容器化端点，支持 agent 式调用。

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

最新模型版本： TimesFM 2.5

已归档模型版本：

• 1.0 和 2.0：相关代码已归档至子目录 v1。你可以 pip install timesfm==1.3.0 安装该软件包的旧版本以加载 它们。

更新 - 2026 年 7 月 2 日

已将 PyPI 更新至 timesfm=2.0.2。参见 Install.

更新 - 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 重新加入协变量（covariate）支持。

更新 - 2025 年 9 月 15 日

TimesFM 2.5 正式发布！

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

• 参数量为 200M，较此前的 500M 有所减少。
• 支持最长 16k 上下文长度，较此前的 2048 大幅提升。
• 通过可选的 30M quantile head，支持最长 1k 预测步长的连续分位数（quantile）预测。
• 移除了 frequency 指示器。
• 新增若干预测相关标志位。

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

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

安装

通过 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]

本地安装

1. 克隆仓库：

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

2. 使用 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]
   

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

• Install PyTorch.
• Install 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)),
    ],  # Two dummy inputs
)
point_forecast.shape  # (2, 12)
quantile_forecast.shape  # (2, 12, 10): mean, then 10th to 90th quantiles.