今日开源[第20期]google-research/timesfm - zhang

google-research/timesfm 项目分析

分析日期：2026-06-21
项目地址：https://github.com/google-research/timesfm

一、项目介绍

1.1 项目概述

TimesFM（Time Series Foundation Model）是 Google Research 开发的预训练时间序列基础模型，专为零样本（zero-shot）时间序列预测而设计。模型采用 Decoder-Only 架构，借鉴了 LLM 的设计思想，将时间序列分割为连续 patch 作为 token 输入 Transformer 进行预测。

项目基于 Apache-2.0 协议开源，论文发表于 ICML 2024（arXiv: 2310.10688），作者为 Abhimanyu Das、Weihao Kong、Rajat Sen、Yichen Zhou。

1.2 项目地址与官网

项目	链接
GitHub 仓库	https://github.com/google-research/timesfm
论文	https://arxiv.org/abs/2310.10688
HuggingFace 模型集	https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
Google Research 博客	https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/
许可证	Apache-2.0

1.3 项目状态

Stars：约 22,000+
提交数：326 次
当前最新版本：TimesFM 2.5（2025 年 9 月发布），PyPI 包 timesfm==2.0.1（2026-06-09）
编程语言：Python（PyTorch + Flax/JAX 双后端）

1.4 模型版本演进

版本	参数规模	上下文长度	预测长度	关键特性
TimesFM 1.0	200M	2048	由 output_patch_len 控制	首个版本，基于 1000 亿真实时间点训练，ICML 2024 论文
TimesFM 2.0	500M	2048	较长	参数量增大，精度提升
TimesFM 2.5	200M	16384（16K）	最高 1000 步（分位数）	参数减半，上下文大幅扩展，取消频率指示器，新增连续分位数头

TimesFM 2.5 核心改进：

参数从 500M 降至 200M，推理更快、部署成本更低
上下文长度从 2048 扩展到 16,384（16K），可捕获更长周期和低频分量
通过可选的 30M 连续分位数头（quantile head），支持高达 1000 步的连续分位数预测（10%-90% 分位数），给出置信区间而非单一点估计
去掉了 frequency 指示器，降低预处理复杂度
在 GIFT-Eval 基准上点预测和概率预测均排名第一（MASE、CRPS 指标）

1.5 项目示意图

README 中提供了以下可视化资源：

模型架构图：展示 Decoder-Only 架构中 patch 分割、Transformer 堆叠和输出解码的流程
GIFT-Eval 基准对比图：TimesFM 2.5 在点预测（MASE）和概率预测（CRPS）上的排名
预测结果示例图：展示不同数据集上的实际预测曲线

二、项目亮点

2.1 核心亮点

亮点	说明
零样本预测	无需任何额外训练，即可对未见过的时序数据进行预测，性能接近甚至超过监督模型（DeepAR、PatchTST）
大规模预训练	基于 1000 亿真实世界时间点（Google Trends、Wikipedia Pageviews 等）和合成数据联合训练
Decoder-Only 架构	借鉴 LLM 设计思想，将时间序列 patch 作为 token，使用因果自注意力 Transformer
长上下文建模	TimesFM 2.5 支持最高 16K 上下文长度，可捕获多季节结构
概率预测	2.5 版本通过连续分位数头输出 10%-90% 分位数，提供预测置信区间
翻转不变性	保证 `TimesFM(aX+b) = a*TimesFM(X) + b`，对正负缩放均有效
双后端支持	同时提供 PyTorch（GPU）和 Flax/JAX（TPU）实现
Google 产品落地	已集成到 BigQuery ML、Google Sheets、Vertex AI Model Garden

2.2 主要功能

功能	描述
点预测	单步或多步确定性预测
概率预测	连续分位数头输出 10%-90% 分位数（TimesFM 2.5）
协变量支持	通过 XReg 支持外部回归变量
LoRA 微调	2026 年 4 月新增 HuggingFace Transformers + PEFT（LoRA）微调示例
Agent 集成	提供 SKILL.md，支持 AI Agent 直接调用
回测	支持 `return_backcast` 输出回测结果

三、项目运行环境与运行条件

3.1 技术栈

类别	技术
编程语言	Python >= 3.10
深度学习框架	PyTorch >= 2.0.0, Flax/JAX
模型格式	safetensors >= 0.5.3
模型分发	HuggingFace Hub >= 0.23.0
包管理	pip / uv

3.2 核心依赖

依赖	说明
`numpy>=1.26.4`	数值计算
`huggingface_hub>=0.23.0`	模型下载
`safetensors>=0.5.3`	模型权重格式
`torch>=2.0.0`	PyTorch 后端
`flax, optax, einshape, orbax-checkpoint`	Flax 后端
`scikit-learn`	XReg 协变量支持

3.3 安装方式

# PyTorch 版本
pip install timesfm[torch]# Flax 版本（TPU 友好，推理更快）
pip install timesfm[flax]# 需要协变量支持时
pip install timesfm[xreg]

3.4 运行环境要求

Python: >= 3.10
GPU: NVIDIA GPU（PyTorch 后端）或 Google TPU（Flax 后端）
内存: 200M 参数模型，推理内存需求较低
操作系统: Linux / macOS / Windows（跨平台）

四、项目代码介绍

4.1 代码架构图

google-research/timesfm/
├── .github/workflows/          # CI/CD 工作流
├── src/timesfm/                # 核心源码（v2.5 为主）
│   ├── __init__.py             # API 入口，导出 TimesFM_2p5_200M_torch/flax
│   ├── configs.py              # 通用配置：ForecastConfig, TransformerConfig 等
│   ├── timesfm_2p5/            # TimesFM 2.5 模型实现
│   │   ├── timesfm_2p5_base.py # 基础类（15KB）
│   │   ├── timesfm_2p5_torch.py# PyTorch 实现（18KB）
│   │   └── timesfm_2p5_flax.py # Flax/JAX 实现（20KB）
│   ├── torch/                  # PyTorch 底层组件
│   │   ├── dense.py            # 残差块、MLP
│   │   ├── normalization.py    # RMS 归一化
│   │   ├── transformer.py      # Transformer 层、堆叠 Transformer
│   │   └── util.py             # 工具函数
│   ├── flax/                   # Flax 底层组件
│   │   ├── dense.py            # 残差块、MLP
│   │   ├── normalization.py    # RMS 归一化
│   │   ├── transformer.py      # Transformer 层
│   │   └── util.py             # 工具函数
│   └── utils/                  # 通用工具
├── timesfm-forecasting/        # 文档、示例、Agent Skill
│   ├── SKILL.md                # Agent Skill 定义（19KB）
│   ├── examples/               # 示例代码
│   │   └── finetuning/         # LoRA 微调示例（2026.04 新增）
│   ├── references/             # 参考文档
│   └── scripts/                # 脚本
├── tests/                      # 单元测试（2026.04 新增）
├── v1/                         # 旧版 TimesFM 1.0/2.0 代码归档
│   ├── src/                    # 旧版源码
│   ├── notebooks/              # Jupyter 示例
│   ├── experiments/            # 实验脚本
│   ├── peft/                   # 旧版 PEFT 微调
│   ├── docs/                   # 文档
│   └── tests/                  # 旧版测试
├── pyproject.toml              # 项目配置（v2.0.1）
├── requirements.txt            # 锁定依赖
├── README.md                   # 项目说明
├── LICENSE                     # Apache-2.0
└── AGENTS.md                   # AI Agent 集成入口

4.2 核心模块介绍

4.2.1 `src/timesfm/init.py` — 统一 API 入口

自动检测 torch/flax 可用性
导出 TimesFM_2p5_200M_torch 和 TimesFM_2p5_200M_flax 两个类
提供简洁的 from_pretrained() 和 forecast() 高层 API

4.2.2 `src/timesfm/configs.py` — 配置系统

包含所有框架无关的配置 dataclass：

ForecastConfig：最大上下文长度、最大预测长度、是否归一化、是否使用分位数头、翻转不变性等
ResidualBlockConfig：残差块配置
TransformerConfig：Transformer 层配置（层数、维度、注意力头数、激活函数）
StackedTransformersConfig：堆叠 Transformer 配置
RandomFourierFeaturesConfig：随机傅里叶特征配置

4.2.3 `src/timesfm/timesfm_2p5/timesfm_2p5_base.py` — 基础类

模型加载、预测逻辑的基类实现
跨框架共享的预处理和后处理逻辑

4.2.4 `src/timesfm/timesfm_2p5/timesfm_2p5_torch.py` — PyTorch 实现

完整 PyTorch 版模型实现（18KB）
from_pretrained()：从 HuggingFace Hub 下载预训练权重
forecast()：执行预测的主方法
支持连续分位数头

4.2.5 `src/timesfm/timesfm_2p5/timesfm_2p5_flax.py` — Flax/JAX 实现

完整 Flax 版模型实现（20KB）
TPU 推理优化
与 PyTorch 版 API 保持一致

4.2.6 `src/timesfm/torch/transformer.py` — Transformer 层

RMS 归一化（attention_norm、feedforward_norm、qk_norm）
RoPE 旋转位置编码
因果自注意力机制
支持 Swish/ReLU 激活函数

4.2.7 `timesfm-forecasting/SKILL.md` — Agent Skill 定义

19KB 的 Agent Skill 文件
定义 AI Agent 如何调用 TimesFM 进行预测
包含参数说明、使用示例和最佳实践

4.3 核心代码解析

4.3.1 模型架构

输入时间序列↓
Patch 分割（连续时间点 → token）↓
残差 MLP 块 + 位置编码（RoPE）↓
堆叠 Transformer 层（因果自注意力）├── RMS 归一化├── 多头注意力 + RoPE├── 前馈网络└── 残差连接↓
输出解码（预测后续时间点）├── 点预测（确定性）└── 分位数预测（可选，10%-90%）

4.3.2 使用示例

import timesfm# 加载预训练模型
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained()# 准备输入数据
import numpy as np
historical_data = np.array([...])  # shape: (batch, time)# 执行预测
forecast = model.forecast(historical_data,horizon=96,  # 预测 96 步
)# 概率预测（含分位数）
forecast = model.forecast(historical_data,horizon=96,use_continuous_quantile_head=True,
)
# 输出: mean, 10th, 20th, ..., 90th 分位数

4.3.3 ForecastConfig 关键参数

@dataclass
class ForecastConfig:max_context: int = 0          # 最大上下文长度（0=不限）max_horizon: int = 128        # 最大预测长度normalize_inputs: bool = True  # 是否归一化输入use_continuous_quantile_head: bool = False  # 是否使用分位数头force_flip_invariance: bool = False  # 强制翻转不变性infer_is_positive: bool = False  # 非负输入保证非负输出fix_quantile_crossing: bool = False  # 修复分位数交叉return_backcast: bool = False  # 是否返回回测

4.3.4 核心代码文件清单

文件	大小	功能
`src/timesfm/__init__.py`	-	API 入口，自动检测后端
`src/timesfm/configs.py`	-	配置 dataclass 定义
`src/timesfm/timesfm_2p5/timesfm_2p5_base.py`	15KB	基础类，跨框架共享逻辑
`src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`	18KB	PyTorch 完整实现
`src/timesfm/timesfm_2p5/timesfm_2p5_flax.py`	20KB	Flax 完整实现
`src/timesfm/torch/transformer.py`	-	Transformer 层实现
`src/timesfm/flax/transformer.py`	-	Flax Transformer 层
`timesfm-forecasting/SKILL.md`	19KB	Agent Skill 定义
`pyproject.toml`	-	项目配置 v2.0.1

五、项目的应用、优点和不足

5.1 应用场景

领域	具体场景
零售/电商	产品需求预测、库存优化
金融	股票价格、交易量预测
能源	电力负荷预测、电网优化
气象	天气、降水趋势预测
供应链	物流需求、仓储规划
交通	流量预测
制造业	设备维护、产能规划
医疗健康	患者流量、药物需求预测
Google 产品	BigQuery ML、Google Sheets、Vertex AI 企业级预测

5.2 项目优点

优点	说明
开箱即用	`pip install timesfm[torch]` 后几行代码即可预测
零样本能力强	无需训练，直接在 Monash 基准上超越多数统计方法（ARIMA、ETS）和部分监督 DL 模型
跨领域泛化	在交通、天气、需求预测等多种领域和粒度（分钟级到年级）上表现良好
轻量高效	200M 参数，远小于 LLM（如 GPT-3.5），推理成本低
双框架支持	PyTorch（GPU）和 Flax（TPU）均可使用
Apache-2.0 开源	商用友好
活跃维护	326 次 commit，持续更新至 2026 年 6 月
企业级落地	已集成 Google 核心产品（BigQuery ML、Google Sheets、Vertex AI）
长上下文	16K 上下文长度，可捕获多季节结构
概率预测	连续分位数头提供置信区间

5.3 项目不足与待改进

不足	说明
单变量为主	核心设计针对单变量时间序列，多变量支持有限（通过 XReg 协变量间接支持）
无训练代码	开源仓库仅提供推理代码和预训练权重，不包含预训练脚本，无法自行从头训练
对异常值敏感	零样本预测对输入数据的分布和异常值较敏感，可能需要预处理
预测长度限制	虽然 2.5 支持最高 1000 步预测，但超长 horizon 场景下精度仍需验证
非官方 Google 产品	README 明确声明 "not an officially supported Google product"，企业使用时需自行评估风险
中文/特定领域数据	预训练数据以英文互联网数据为主（Google Trends、Wikipedia），对特定领域的中文数据泛化能力未知
缺乏训练文档	对于希望 fine-tune 的用户，文档和工具支持仍在完善中
旧版代码归档	v1/ 目录包含大量旧版代码，可能造成混淆

5.4 社区与生态

HuggingFace 集成：模型权重托管在 HuggingFace Hub，支持一键下载
Agent Skill：提供 SKILL.md，支持 AI Agent 直接调用
LoRA 微调：2026 年 4 月新增 HuggingFace Transformers + PEFT 微调示例
Google 产品落地：BigQuery ML、Google Sheets、Vertex AI 已集成
论文发表：ICML 2024 论文

六、总结

TimesFM 是 Google Research 在时序预测基础模型方向的重要探索，从 ICML 2024 论文发表到 TimesFM 2.5 的持续迭代，项目展现了从学术研究到产品落地的完整路径。其核心优势在于：

零样本预测能力：无需训练即可在未见过的数据上达到竞争性性能
轻量级架构：200M 参数，推理高效，部署成本低
长上下文支持：16K 上下文长度，可捕获复杂的多季节模式
概率预测：连续分位数头提供置信区间，增强决策可信度
企业级落地：已集成 Google 核心产品（BigQuery ML、Google Sheets、Vertex AI）

项目代码结构清晰，双后端（PyTorch/Flax）支持，并通过 BigQuery ML、Google Sheets 等产品实现了商业化落地。对于需要快速构建时序预测能力的团队，TimesFM 是一个值得关注的开源选择。但需要注意的是，项目不提供预训练代码，且对特定领域数据（如中文）的泛化能力有待验证。