google-research/timesfm

项目介绍

TimesFM 是 Google Research 发布的 decoder-only 时间序列基础模型。它不要求为每条序列单独训练，而是对新的数值序列直接做零样本预测；3.0 版本增加了原生多变量预测，以及仅历史、历史加未来两类协变量支持。相关论文发表于 ICML 2024，项目背景见研究博客。

它适合需要基于原始数组快速得到预测结果的数据科学家、分析师和构建预测服务的工程师。代码以 Python 包形式提供，检查点放在 Hugging Face，1.0/2.0 的旧代码归档在 v1 子目录。

快速使用

通过 PyPI 安装最省事。torch 额外依赖会安装 PyTorch，mlx 额外依赖面向 Apple 芯片、不依赖 PyTorch：

pip install timesfm[torch]

然后加载 3.0 检查点，对一批序列生成预测和分位数：

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

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

ts1 = np.linspace(0, 1, 100).astype(np.float32)
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)
outputs = list(forecaster.predict_batch(
    [ts1, ts2], horizon=12, return_quantiles=True, use_symmetric_averaging=False
))
print(outputs[0].forecast.shape)   # (12,)
print(outputs[0].quantiles.shape)  # (12, 9)

如需基于仓库源码开发，README 给出了用 uv venv 创建环境并执行 uv pip install -e .[torch] 的可编辑安装方式。多变量预测需要向 predict_batch 传入形状为 (变量数, 上下文长度) 的二维数组及协变量数组，具体参数名和输出形状见示例。

Apple 芯片可使用 MLX 后端，接口与 PyTorch 版一致，通过 TimesFM3Forecaster.from_pretrained("google/timesfm-3.0-pytorch") 加载；它支持单变量、多变量和协变量，README 报告了与 PyTorch 路径在指定误差范围内的数值一致性。

使用约束

TimesFM 3.0 的预训练权重不是 Apache-2.0 授权。仓库源码采用 Apache-2.0，2.5 及以前的权重也仍为 Apache-2.0，但 3.0 权重使用单独的非商业许可，禁止将下载或自托管的权重用于商业和生产用途。3.0 的商业使用需通过 Google Cloud 服务，例如受 Google Cloud 条款约束的 BigQuery ML。

CUDA 路径依赖 PyTorch；MLX 路径仅限 Apple 芯片。3.0 默认模型为 2 亿参数、支持 16k 上下文；2.5 文档说明支持最高 16k 上下文，并可通过可选的 3000 万分位数头支持最高 1k 预测步长。README 还说明这个开源版本不是 Google 官方支持的产品。

HotRepo 点评

项目累计约 3.5 万 Star、3.4k Fork。2026-09-03 的日榜快照记录到单日新增 1,626 Star；2026-11-05 它位列 Python 日榜第 12 名，该快照新增 55 Star。这些数据分属不同日期和不同榜单口径，不能据此判断趋势；Python 日榜第 12 名是这里唯一记录到的名次。

Hacker News 上的讨论持续存在，2026 年 3 月的帖子获得 327 分、109 条评论。讨论中有不少人质疑单一通用模型能否可靠处理鸡蛋价格、通胀这类差异极大的序列，有回复指出这类模型主要刻画趋势、季节性和残差，而不是外部事件(讨论)。评估零样本预测时值得留意这一点：基准排名领先，并不意味着模型的模式与当前领域天然匹配。另外，采用 3.0 前应先看清许可差异——代码开源，但当前权重为非商业许可。