google-research/timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

TimesFM – 时间序列预测的基础模型

是什么 – TimesFM（时间序列基础模型）是一种仅使用解码器的神经网络，基于海量且多样化的时序数据进行训练。Google Research 发布了模型权重和 Python 库，使您能够执行零样本预测（单变量或多元）并基于自己的数据对模型进行微调。

为何重要 – 与文本领域的大型语言模型类似，TimesFM 旨在成为一个通用预测器，无需手工特征工程，即可开箱即用地适用于多个领域（金融、能源、零售等）。该仓库提供了至版本 3.0 的预训练检查点以及用于推理、评估和 LoRA 风格微调的代码。

主要亮点（以 README 为准）

版本 3.0 – 原生支持多变量预测，支持仅过去和过去-未来动态协变量，并在三个主要时间序列基础模型基准（fev-bench, TIME, GIFT-Eval）上取得最佳成绩。
模型大小 – 主要检查点为 3.3 亿参数；还提供更轻量的 2 亿参数版本（2.5）。
长上下文 – 支持最多 16,000 个 token（2.5 版）和 15,360 个 token（完整模型），可考虑长期历史数据进行预测。
分位数预测 – 可选的 3,000 万参数头可提供最多 1,000 步的分位数预测（默认 9 个分位）。
后端 – 支持标准 PyTorch 和 Apple Silicon 专用 MLX，数值结果一致。
集成点 – 可在 Google Cloud 产品（BigQuery ML、Vertex Model Garden）和 Google Sheets 中使用，面向终端用户。
微调 – 示例脚本使用 HuggingFace Transformers + PEFT（LoRA）将模型适配到特定序列。
代理支持 – AGENTS.md 文件说明了如何从自主代理中调用 TimesFM。

典型应用场景

领域	TimesFM 如何帮助
业务预测（销售、需求、库存）	对新产品线进行零样本预测；基于历史销售数据微调以提高准确性。
能源与公用事业	可同时预测包含天气协变量的多变量负荷和价格序列。
金融	在宏观经济协变量条件下预测多个资产价格序列。
物联网 / 传感器数据	用于设备健康监测的长窗口预测。
快速原型开发	通过 BigQuery ML 或 Sheets 无需编写代码即可即插即用。

快速入门（Python）

# 安装库（选择后端）
pip install "timesfm[torch]"      # PyTorch（CPU/GPU）
# 或
pip install "timesfm[mlx]"        # Apple silicon，无需 PyTorch

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"               # 或 "cpu" / "mlx"
)
forecaster = TimesFM3Evaluator(cfg)

# 单变量示例
ts = np.sin(np.linspace(0, 2*np.pi, 100)).astype(np.float32)
out = forecaster.predict_batch([ts], horizon=12, return_quantiles=True)[0]
print(out.forecast.shape)   # (12,)
print(out.quantiles.shape)  # (12, 9)

对于多变量序列，请按 README 所示传递 (num_variates, context_len) 数组和可选的协变量数组。

微调（LoRA） – 快速示例

# 克隆仓库并安装可编辑版本
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]

# 来自 timesfm-forecasting/examples/finetuning/
from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
from peft import LoraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("google/timesfm-3.0-pytorch")
peft_cfg = LoraConfig(r=8, lora_alpha=32, target_modules=["c_attn"])
model = get_peft_model(model, peft_cfg)
# …准备 (context, target) 对数据集并运行 Trainer…

仓库包含可直接运行的 finetuning 脚本和单元测试。

许可证

源代码 – Apache-2.0（可自由使用、修改和分发）。
预训练权重 – 版本 ≤2.5 为 Apache-2.0。版本 3.0 权重采用独立的 非商业 许可证（timesfm-non-commercial-license-v1.0），禁止在无单独协议的情况下用于商业或生产部署。

限制与注意事项

商业使用限制 – 最新检查点（3.0）在未获得 Google 许可的情况下，不得用于创收产品。
硬件要求 – 完整版 3.3 亿参数模型在 GPU 上运行最佳；MLX 后端仅限 Apple Silicon。
零样本性能 – 尽管在基准测试中表现领先，但特定领域数据仍可能从微调中受益。
上下文截断 – 超过模型 global_context（15,360 个 token）的上下文将自动截断，可能丢失极长的历史数据。
无官方产品支持 – 仓库声明其为“非 Google 官方支持产品”，因此 bug 修复和更新依赖开源社区。