---
url: /timesfm/introduction.md
description: >-
  TimesFM 3.0 是 Google Research 于 2026 年 8 月 31 日发布的零样本时间序列预测基础模型，3.3 亿参数、在超 1
  万亿时间点上预训练，首次原生支持多变量预测与未来已知协变量，单次前向传播出完整预测区间，在 fev-bench、TIME、GIFT-Eval
  三大榜单拿下第一。本文带你从零认识 TimesFM：什么是时序基础模型、它凭什么能零样本预测、怎么装、怎么用、以及那个必须知道的许可坑。
---

# 认识 TimesFM 3.0：Google 那个 3.3 亿参数的"预言家"，终于学会了看促销日历

先讲一个每个做过业务预测的人都撞过的墙。

运营跑过来说：下周我们要搞三天大促，你帮我估一下能卖多少。你把历史销量扔进模型，ARIMA 也好 Prophet 也好，它老老实实把上周、上上周的曲线往未来平移——然后给你一条平平稳稳的线。

问题是，**下周有促销这件事，你明明知道，模型不知道**。

这条"已知的未知"，才是时序预测最尴尬的地方。你的日历上写着促销排期，你的手机里存着天气预报，你的采购系统里记着节假日——这些信息全都是**未来已知的**，但在传统模型眼里，未来就是一片空白，只能靠历史外推。

结果就是促销当天实际爆了 20%，你的预测线还在那儿岁月静好。

2026 年 8 月 31 日，Google Research 把 **TimesFM 3.0** 放了出来，当天冲上 GitHub Trending。它做的第一件事，就是把这个墙推倒了：**让模型直接"看见"未来已知的日历**。

## 什么是 TimesFM

一句话：**TimesFM 是一个预训练好的时间序列基础模型——你给它一段历史数字，它直接吐出未来数字，不需要你有任何训练过程。**

全称 **Time Series Foundation Model**，Google Research 出品。它的思路说穿了特别简单粗暴：NLP 领域有 BERT、GPT 这样"海量预训练 + 零样本泛化"的通用底座，那时间序列领域为什么不能有？于是 Google 把 GPT 那套 decoder-only Transformer 架构原样搬到了数字序列上，论文《A decoder-only foundation model for time-series forecasting》发在了 **ICML 2024**。

从 2024 年首次开源到现在，它迭代了三代：

| 版本 | 时间 | 参数量 | 关键变化 |
| --- | --- | --- | --- |
| **1.0 / 2.0** | 2024 | 500M | 纯单变量，上下文 2048，已归档在 `v1` 目录（`pip install timesfm==1.3.0` 可复现） |
| **2.5** | 2025 年 9 月 | 200M | 上下文拉到 **16k**，可选 30M 分位数头支持最长 1000 步概率预测，**去掉了 frequency 指示器**，2025 年 10 月通过 XReg 把协变量支持补了回来 |
| **3.0** | 2026 年 8 月 31 日 | **330M** | **原生多变量预训练**、原生支持历史协变量与历史-未来协变量、**单次前向传播出整个预测区间** |

注意 2.5 到 3.0 这个转变的分量：**2.5 以前，TimesFM 严格局限于单变量预测**——只拿一条序列自己的历史预测它自己的未来。而现实世界里绝大多数预测问题天生是多变量的：多条相关序列 + 一堆外部特征，共同决定某个数字的未来。

Google 官方举的例子特别好懂：预测一家零售连锁店的冰淇淋销量，光看过去的销量远远不够。一个像样的预测至少还得参考**相关产品的销量**（甜筒、糖浆）、**历史客流量**，以及**天气预报、促销活动、节假日**这些已知的未来事件。

> 时序预测最反直觉的一点是：影响未来的很多信息，你现在就已经知道了。之前的模型全都浪费了它。

## 它有什么特点

* **原生多变量，一条前向传播全搞定**：同时预测多条共同演化的序列（比如联合预测不同品牌冰淇淋的销量），并捕捉它们之间的依赖关系。官方配置支持最多 **32 个变量**。
* **三类输入，分工明确**：
  * **目标序列**（targets）：你要预测的那些序列；
  * **历史协变量**（past-only covariates）：只在过去已知、未来未知的特征，比如历史客流量；
  * **历史-未来协变量**（past-future / dynamic covariates）：过去和未来都已知的信号，比如促销排期、天气预报、节假日日历。
* **"前瞻" token 构造**：对历史-未来协变量，每个 token 会把**当前 patch 和未来 patch 拼在一起**，让模型提前看到即将到来的已知信号。这就是它能"看日历"的技术来源。
* **32 步一个 patch**：延续前代做法，把连续时间点切成每 32 步一个 patch 做 token 化，再对每条序列分别归一化以适应量级差异巨大的不同序列。
* **交替注意力架构**：这是 3.0 最核心的架构创新。Transformer 堆栈以二维网格运行，两种注意力**交替执行**：
  * **因果时间注意力**：沿时间维度横向计算，严格因果，一个 token 只能看自己序列里的过去 token（防数据泄漏）；
  * **全变量注意力**：沿序列之间的维度纵向计算，同一时间步上一个 token 可以看到数据集里所有其他序列——模型就是这么学会"某个序列的促销会影响另一个序列的销量"的。
* **连续 Patch 掩码（Contiguous Patch Masking）+ 非自回归解码**：以前的版本一个 patch 一个 patch 地生成预测，延迟高、误差还会逐步累积。3.0 在已观测上下文之后追加一整段被掩码的占位 token，**一次前向传播把整个预测区间填满**，不用任何迭代循环。
* **9 个分位数，不给你一个孤零零的数字**：对每个目标序列的每个预测步，输出从 **第 10 到第 90 百分位共 9 个分位数**。做计划的人最怕的不是预测不准，是不知道自己有多不准——这个不确定性视图比点预测值钱得多。
* **三大榜单全项第一**（Google 官方口径，对比 Chronos-2、Toto 2.0 系列、TimesFM-2.5 等）：
  * 🥇 **fev-bench**：100 个真实预测任务，**总榜第一**；
  * 🥇 **TIME Benchmark**：50 个领域数据集、98 个评测任务，**总榜第一**；
  * 🥇 **GIFT-Eval**：**所有基础模型中排名第一**。
  * 而且 Google 特意做了"单变量模式"对照——**即使完全不用协变量和跨序列信息，TimesFM-3 也已经能达到或超越对手**；切到完整多变量模式后，性能再跳一档。
* **模型规格**：3.3 亿参数、20 层 Transformer、checkpoint 约 **1.32 GB**（`google/timesfm-3.0-pytorch`），训练语料是真实 + 合成混合的**超 1 万亿个时间点**。
* **工程化做得像产品不像论文**：仓库里有单元测试、有基于 HuggingFace Transformers + PEFT 的 **LoRA 微调示例**（2026 年 4 月加的）、有 Flax 版本做加速推理，甚至还按 agentskills.io 规范提供了 `timesfm-forecasting/SKILL.md`，让 AI 编码智能体直接调用不出错。Google Research 的仓库很少这么"贴心"。

## 它能用在哪

**1. 零售与供应链需求预测——Google 官方的冰淇淋例子**

Google 在发布博客里给了一个特别直观的对比：你要预测下个月的冰淇淋销量，同时已经定好了促销排期。

* **标准单变量模型**：看历史销量，把每周模式向未来延伸。它压根不知道哪天有促销，画出来一条平滑的红线。
* **TimesFM-3 多变量模式**：把促销日程作为历史-未来协变量喂进去，模型从历史上下文里学到"促销 ↔ 销量提升"的关系，再应用到未来已排期的促销日上——**预测每个促销日销量大约提升 20%**，蓝色的预测线会明显对每次促销作出响应。

把一整个月累计起来，这就是更准确的营收预期。对零售来说，哪怕预测准确率只提升一点点，都直接对应库存成本的下降和营收的提升。

**2. 最大的"客户"其实是 Google 自己**

TimesFM 不是躺在 notebook 里的研究玩具，它已经被接进了 Google 的多个产品线：

| 产品 | 能干什么 |
| --- | --- |
| **BigQuery ML** | 用 `AI.FORECAST` 函数在 SQL 里做企业级规模的预测，**不需要任何机器学习背景** |
| **Google Sheets** | 电子表格里的预测按钮，业务同学自己就能点 |
| **Vertex Model Garden** | Docker 化端点，供 Agent 流水线调用 |
| **AlloyDB** | 数据库内嵌预测，直接服务事务型负载 |

这意味着同一套模型，既服务了住在 Sheets 里的运营，也服务了住在 BigQuery 里的数据团队，中间没有任何人需要重新训练模型。Google 已表示 **TimesFM-3 的 BigQuery 集成将在发布后数周内上线**，会走和 2.5 相同的 `AI.FORECAST` 命令。

顺带说一句：你现在想在 BigQuery 里上手，用的是 **TimesFM-2.5**（2.5 权重仍是 Apache-2.0，可商用），先熟悉 `AI.FORECAST` 的语法就行。

**3. 更多领域**

Google Research 明确列出 TimesFM 已落地的应用方向：**零售、金融、可观测性、制造、医疗健康、自然科学**。典型场景包括销量与库存预测、网站/APP 流量与服务器扩容预测、交易量与风险评估、能耗与电力负荷预测、空气质量与 PM2.5 预测。

> 说句实在话：Google 目前没有公布具名的外部企业落地案例和误差指标，上述三大榜单成绩也都是 Google 自己报的。所以别拿榜单当结论——用它自己的数据跑一遍，和你现在的基线比，那才是数。

## 初体验

先装包。PyPI 上的包名就是 `timesfm`：

```bash
# PyTorch 版本
pip install timesfm[torch]

# 想从源码跑，官方推荐用 uv
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]
```

**场景一：单变量预测，不同长度的序列混着来**

```python
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)      # 长度 100
ts2 = np.sin(np.linspace(0, 24, 72)).astype(np.float32)  # 长度 72

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)   9 个分位数
```

**场景二：多变量 + 协变量（这才是 3.0 的主场）**

```python
context_len, horizon = 128, 24

target          = np.random.randn(3, context_len).astype(np.float32)            # 3 条目标序列
past_only_cov   = np.random.randn(1, context_len).astype(np.float32)            # 历史协变量，如客流
past_future_cov = np.random.randn(2, context_len + horizon).astype(np.float32)  # 历史-未来协变量，如促销日历

outputs = list(forecaster.predict_batch(
    contexts=[target],
    horizon=horizon,
    past_only_covariates=[past_only_cov],
    past_future_covariates=[past_future_cov],
    return_quantiles=True,
    use_symmetric_averaging=False,
))

print(outputs[0].forecast.shape)   # (3, 24)      3 条序列各预测 24 步
print(outputs[0].quantiles.shape)  # (3, 24, 9)
```

**四条踩坑提醒，都是真金白银换来的：**

1. **许可协议这个坑必须先说**：仓库**代码是 Apache-2.0**，**2.5 及更早版本的权重也是 Apache-2.0**；但 **TimesFM 3.0 的预训练权重单独走 `timesfm-non-commercial-license-v1.0`，仅限非商业、非生产用途**。想商用生产，要么继续用 2.5，要么等 BigQuery / Vertex 的托管路径。别兴冲冲把 3.0 权重塞进公司系统然后被法务找上门。
2. **这个开源仓库不是 Google 官方支持的产品**。README 里写得明明白白："This open version is not an officially supported Google product." 生产级 SLA 在 Vertex 和 BigQuery 里，不在 GitHub issue 区。
3. **零样本不等于万能**。预训练语料偏向日/周/月粒度（零售、流量、搜索热度这类），**亚小时级的高频 IoT 噪声流不是它的主场**；如果你要塞五十个外部回归变量并建模复杂交互，针对你领域专门训的模型还是会赢。
4. **本地大批量推理还是要张卡**。330M 参数在 LLM 标准下是小不点，但一次批处理几千条长上下文序列，没有加速器会比较难受——这也是 BigQuery ML 存在的理由之一。

## 进阶

到这里，你已经知道 TimesFM 是什么、能干什么、怎么把第一次预测跑起来了——对新手来说，"知道"比"精通"重要得多，剩下的交给好奇心就行。

真想往下挖，建议按这个顺序：先把单变量这条最短链路跑通、看懂 9 个分位数怎么读，再上多变量 + 协变量（这才是 3.0 的真正价值点），然后在自己的业务数据上跟 ARIMA / Prophet / LightGBM 基线做同窗口对比，最后再试 LoRA 微调和 BigQuery 的 `AI.FORECAST`。别一上来就想着替换公司的整套预测系统，那不是入门，那是渡劫。

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。