企业官网建设流程全解析

TimesFM 2.5 实战指南：Google 时序基础模型的零样本预测从安装到调优

【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfm

TimesFM（Time Series Foundation Model）是 Google Research 推出的预训练时序基础模型，采用 decoder-only 架构，无需针对任务训练即可对任意一元时间序列做零样本预测，并同时输出点预测与校准过的分位数预测区间。本文以当前仓库根目录 README.md 为主体骨架，结合 src/timesfm 源码、tests 测试与 timesfm-forecasting 示例工程，完整讲解 TimesFM 2.5 的版本特性、安装方式、ForecastConfig全部配置项、forecast()与forecast_with_covariates()两大核心 API 的底层实现，以及常见误区与质量自检清单。读完本文，你将能够独立完成从环境检查、模型加载到批量预测、协变量预测与异常检测的完整实战链路。

模型概览：decoder-only 的时序基础模型

TimesFM 是 Google Research 开发、面向时间序列预测任务的预训练基础模型。其核心技术方案发表于论文《A decoder-only foundation model for time-series forecasting》（ICML 2024），所有公开 checkpoint 统一发布在 Google 的 TimesFM Hugging Face 集合中，并已集成进 Google 1P 产品：

• BigQuery ML：以企业级 SQL 查询获得可扩展、可靠的预测能力；
• Google Sheets：面向日常电子表格的预测；
• Vertex Model Garden：以 Docker 化端点形式提供，便于 Agent 化调用。

需要特别说明的是：当前开源版本并非 Google 官方支持产品（README 原文为 "This open version is not an officially supported Google product"），使用时请自行评估生产环境适配。仓库当前的 PyPI 包版本为timesfm 2.0.2（见 pyproject.toml），requires-python = ">=3.10"，基础依赖仅numpy>=1.26.4、huggingface_hub[cli]>=0.23.0、safetensors>=0.5.3，框架（torch / flax）通过可选依赖引入。

TimesFM 2.5：相对 2.0 的关键升级

仓库根 README 明确标注最新模型版本为 TimesFM 2.5（1.0 与 2.0 的代码归档在v1子目录，可通过pip install timesfm==1.3.0安装旧版包来加载）。与 2.0 相比，2.5 的升级点如下：

自 2025 年 9 月发布以来，官方陆续补齐了以下能力（README 中均有对应完成标记）：

1. ✅Flax 版本模型，用于更快推理（见 timesfm_2p5_flax.py）；
2. ✅ 通过XReg 恢复协变量（covariate）支持；
3. ✅ 文档、示例与 Agent 技能包（timesfm-forecasting 目录）；
4. ✅ 基于 HuggingFace Transformers + PEFT（LoRA）的微调示例（finetune_lora.py）；
5. ✅ 面向核心层、配置与工具函数的单元测试（tests 目录）。

从源码结构看，模型定义的骨架集中在 timesfm_2p5_base.py：TimesFM_2p5_200M_Definition声明了context_limit = 16384、输入 patch 长度 32、输出 patch 长度 128、输出分位长度 1024，分位点集合为[0.1, 0.2, ..., 0.9]，并配置了 20 层、1280 维、16 头的堆叠 Transformer（RMS 归一化 + rotary 位置编码 + swish 激活 + QKV 融合）。torch 与 flax 两个实现类则分别位于 timesfm_2p5_torch.py 与 timesfm_2p5_flax.py，统一由 src/timesfm/init.py 导出TimesFM_2p5_200M_torch与TimesFM_2p5_200M_flax。

安装与环境准备

从 PyPI 安装

README 给出了三组可选依赖安装方式，分别对应不同能力组合：

# 安装 torch 后端 pip install timesfm[torch] # 安装 Flax 后端 pip install timesfm[flax] # 需要协变量（XReg）功能时追加 pip install timesfm[xreg]

其中[xreg]额外引入jax[cuda]与scikit-learn（见 pyproject.toml），这是forecast_with_covariates()的运行前提。[flax]则引入flax、optax、einshape、orbax-checkpoint、jaxtyping、jax[cuda]等依赖。

本地源码安装（uv）

README 推荐的本地安装流程使用uv管理虚拟环境：

# 1. 克隆仓库并进入目录 git clone <仓库地址> cd timesfm # 2. 创建并激活虚拟环境 uv venv source .venv/bin/activate # 3. 以可编辑模式安装（按需选择后端） uv pip install -e .[torch] # 或 uv pip install -e .[flax] # 需要 XReg 时追加 uv pip install -e .[xreg]

第 3 步之后，[可选] 根据操作系统与加速器（CPU / GPU / TPU / Apple Silicon）安装适配的torch或jax后端。

加载模型前的强制预检

首次加载模型前，务必先运行仓库提供的系统预检脚本（模型权重约 800MB，需在首次使用时从 HuggingFace 按需下载并缓存在~/.cache/huggingface/）：

python timesfm-forecasting/scripts/check_system.py

该脚本检查可用内存（低于 4GB 警告、低于 2GB 阻止）、GPU/VRAM、磁盘空间、Python 版本（要求 3.10+）以及timesfm/torch是否已安装。还支持数据集级内存估算：

python timesfm-forecasting/scripts/check_system.py \ --num-series 1000 --context-length 1024 --horizon 24 --batch-size 32

脚本内置了三代模型的硬件要求画像（见 check_system.py）：TimesFM 2.5 推荐 RAM ≥ 4GB、VRAM ≥ 2GB、磁盘约 2GB；2.0（500M）推荐 RAM ≥ 16GB、VRAM ≥ 8GB；1.0（200M）推荐 RAM ≥ 8GB、VRAM ≥ 4GB。

30 秒上手：最小零样本预测代码

README 给出了一个可直接运行的完整示例，我们先逐行解读其含义：

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)), ], # 两个示例输入 ) point_forecast.shape # (2, 12) quantile_forecast.shape # (2, 12, 10)：mean，然后是 10th~90th 分位数

几个关键点：

• from_pretrained默认模型仓库为google/timesfm-2.5-200m-pytorch（源码常量DEFAULT_REPO_ID，见 timesfm_2p5_torch.py），权重文件为model.safetensors；也支持传入本地目录路径加载 checkpoint，加载成功后会自动执行torch.compile加速前向（torch_compile=True默认开启）。
• model.compile(ForecastConfig(...))是调用forecast()之前的强制步骤——基类 timesfm_2p5_base.py 中forecast()首先检查self.compiled_decode is None，未编译会直接抛出RuntimeError("Model is not compiled. Please call compile() first.")。
• inputs接收一个 numpy 数组列表，每个数组是一条一元时间序列，长度不同也没关系；返回的point_forecast形状为(序列数, horizon)，quantile_forecast形状为(序列数, horizon, 10)，第 0 个切片是均值，第 1~9 个切片对应 q10~q90。
• 编译期会对配置做合法性校验与自动修正：max_context会被向上取整为 patch 大小 32 的倍数，max_horizon会被向上取整为输出 patch 大小 128 的倍数，且要求max_context + max_horizon <= 16384；use_continuous_quantile_head=True时max_horizon不能超过 1024（详见 timesfm_2p5_torch.py）。

ForecastConfig 全参数源码级解析

所有预测行为都由 configs.py 中定义的冻结（frozen）dataclassForecastConfig控制。全部字段、默认值与作用如下：

各 flag 的底层实现都可以在 timesfm_2p5_torch.py 的_compiled_decode闭包中找到：

• normalize_inputs=True：在输入上计算逐序列的均值/标准差并做标准化（revin反向实例归一化），预测结束后再反归一化还原量纲；
• force_flip_invariance=True：同时用-inputs再做一次解码，通过(f(x) - f(-x)) / 2取对称平均，实现对负数输入的翻转不变性；
• infer_is_positive=True：对整条输入全为非负的序列，用torch.maximum(forecast, 0)对输出做非负钳制；
• fix_quantile_crossing=True：分别向左（q10→q40）与向右（q60→q90）做单调化扫描，用相邻分位数替换交叉点；
• use_continuous_quantile_head=True：用连续分位数头输出的 spread 相对中位数（索引 5）的偏移重写各分位切片，从而获得连续、不发散的分位数估计。

测试 test_configs.py 同时印证了两个工程细节：配置是冻结 dataclass，任何字段赋值都会触发FrozenInstanceError（这保证compile()捕获的配置对象在闭包生命周期内不可变）；编译路径用dataclasses.replace修正上下文/horizon 倍数时不会污染原始配置对象。

理解输出：点预测与分位数预测区间

model.forecast()始终返回二元组(point_forecast, quantile_forecast)：

• point_forecast：形状(batch, horizon)，即中位数（0.5 分位）预测；
• quantile_forecast：形状(batch, horizon, 10)，10 个分位切片。

分位数索引约定如下（来自 README 与 SKILL 文档的明确说明）：

一个常见误区是分位数索引 off-by-one：索引 0 是均值而不是 q0，q10 是索引 1、q90 是索引 9。取 80% 预测区间应写：

lower_80 = quantile_forecast[:, :, 1] # 10th percentile upper_80 = quantile_forecast[:, :, 9] # 90th percentile

利用分位数区间可以做轻量异常检测：超出 q10~q90（90% 置信区间）的点在统计上属于异常（发生概率 < 10%），这是 TimesFM 虽然没有内置异常检测模块、却能通过预测区间间接实现异常判定的标准做法，完整的端到端示例见 detect_anomalies.py。

下面是官方 global-temperature 示例的运行结果，图中展示了历史上下文、点预测与 80% 预测区间带（forecast_visualization.png），对应的数据管道见 run_forecast.py 与 visualize_forecast.py：

协变量预测：forecast_with_covariates()与 XReg

TimesFM 2.5 通过 XReg 恢复了协变量（外生变量）支持，这是 README 明确列出的 2025 年 10 月更新内容。API 签名定义在基类 timesfm_2p5_base.py：

model.forecast_with_covariates( inputs=inputs, dynamic_numerical_covariates={"price": price_arrays}, # 动态数值协变量 dynamic_categorical_covariates={"holiday": holiday_arrays}, # 动态类别协变量 static_categorical_covariates={"region": region_labels}, # 静态类别协变量 static_numerical_covariates=None, # 静态数值协变量 xreg_mode="xreg + timesfm", # 或 "timesfm + xreg" normalize_xreg_target_per_input=True, ridge=0.0, max_rows_per_col=0, force_on_cpu=False, )

使用前提与行为要点：

• 必须先以return_backcast=True重新编译模型，否则直接抛出ValueError（源码在 timesfm_2p5_base.py）；
• 四类协变量至少提供一种，否则报错；
• xreg_mode决定拟合顺序：
  • "xreg + timesfm"：先在目标序列上拟合 XReg 线性模型，再用 TimesFM 预测残差；
  • "timesfm + xreg"：先跑 TimesFM 得到预测，再在预测残差上拟合 XReg 模型；
• 动态协变量必须同时覆盖上下文窗口与完整预测 horizon（这是 SKILL 文档明确列出的常见错误之一）；
• 为了推理速度，应避免使用字符串取值的类别协变量；
• 由动态协变量长度推断出的 horizon 不能超过ForecastConfig.max_horizon。

运行效果可参考 demo_covariates.py 与它的可视化输出（3 家门店 × 36 周的销售数据 + 各店独立价格数组，covariates_data.png）：

输入预处理：NaN 处理与上下文填充

在进入模型之前，每条输入序列都会经过两道预处理（见 timesfm_2p5_base.py）：

1. strip_leading_nans：删除序列开头连续的 NaN；
2. linear_interpolation：对序列内部的 NaN 做线性插值填充（np.interp；尾部 NaN 按最近有效值钳制外推，全部无效时回退到均值/0）。

随后若序列长度超过max_context则取末尾max_context个点，否则在序列前部以 0 填充并对填充部分打 mask。这两道 NaN 处理位于推理关键路径上，test_base_utils.py 用十余个用例覆盖了各种边界情况（单个/多个内部 NaN、前导/尾部 NaN、全 NaN、dtype 保持等），确保 NaN 不会穿透整个模型产生垃圾预测。

模型架构与加载机制速览

从 timesfm_2p5_base.py 可以提炼出 TimesFM 2.5-200M 的完整架构配置：

• Tokenizer（输入残差块）：input_dims=64，hidden_dims=1280，output_dims=1280，使用 swish 激活与偏置；
• 主干 Transformer：20 层堆叠，model_dims=1280、hidden_dims=1280、16 头（head_dim=80），RMS 注意力/前馈归一化、RMS QK 归一化、rotary 位置编码、swish 激活、QKV 融合、无偏置；
• 输出投影：点预测头与分位数头均为 swish 残差块，分位数头输出维度 10240（= 1024 输出分位长 × 10 个分位切片）；
• 分位点集合：[0.1, 0.2, ..., 0.9]，配合均值切片构成 10 维分位输出。

PyTorch 实现类 TimesFM_2p5_200M_torch 基于PyTorchModelHubMixin实现from_pretrained，权重以 safetensors 格式存储；也实现了_save_pretrained与本地目录load_checkpoint。解码过程采用「prefill + 自回归迭代」：先对上下文做 patch 化（patch 长度 32）、维护逐 patch 的运行统计（ReVIN 反向实例归一化），再按输出 patch（长度 128）逐块自回归解码，直至达到目标 horizon。

实战工作流与质量自检清单

常用脚本

• check_system.py：系统预检 + 数据集内存估算（前文已述）；
• forecast_csv.py：端到端 CSV 预测 CLI：

python timesfm-forecasting/scripts/forecast_csv.py input.csv \ --horizon 24 --date-col date --value-cols sales,revenue \ --output forecasts.csv

示例工程一览

完成任务前的质量自检

综合 README、SKILL 文档与源码约束，每次运行后建议核对：

• 输出形状正确：point为(n_series, horizon)，quantile为(n_series, horizon, 10)；
• 分位数索引正确：索引 0 是均值，q10=1、q90=9，不是 0=q0；
• 频率标志：TimesFM 1.0/2.0 需为月度数据传freq=[0]；TimesFM 2.5 已移除该参数，不要传；
• 序列长度 ≥ 32（一个输入 patch）；
• 输出无 NaN：np.isnan(point_forecast).any()为 False；
• 负值序列（温度、收益率等）记得把infer_is_positive设为 False；
• 协变量预测必须return_backcast=True且动态协变量覆盖完整 horizon；
• 无头环境绘图前先matplotlib.use("Agg")。

结语

TimesFM 2.5 以 200M 参数、16k 上下文、连续分位数头与 XReg 协变量支持，构成了一个「开箱即用」的零样本时序预测方案：from_pretrained加载 →compile(ForecastConfig)配置 →forecast()/forecast_with_covariates()出结果，全流程无需训练。理解ForecastConfig每个开关的底层实现、分位数输出的索引约定以及 NaN/上下文填充的预处理细节，是把它稳定接入生产数据管线的关键。仓库内的 tests、timesfm-forecasting 示例与 src/timesfm 源码，可以作为进一步研究实现细节与复现完整工作流的直接参考。

【免费下载链接】timesfmTimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.项目地址: https://gitcode.com/GitHub_Trending/ti/timesfm