企业官网建设流程全解析

TimesFM 2.5 动态协变量完整指南：让已知外部变量进入预测

【免费下载链接】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 2.5 通过动态协变量（XReg）机制重新引入了协变量支持：预测时除历史数值外，还能喂入价格、促销、天气等已知外部变量，最终结果是模型预测加线性回归调整。本文覆盖选型、调用与验证全流程。

何时该引入动态协变量

零售门店的周销量受节假日和促销驱动，而这些信息是提前排好的。TimesFM 单看历史曲线，难以预判这类脉冲；把未来节假日排期、计划促销周作为动态协变量喂入，回归部分能接住这些已知波动。判断标准很简单：变量影响目标、且未来值可提前得知，就值得引入。

先分清协变量类型与输入规则

三条输入规则需要记牢：

• 动态协变量必须覆盖历史上下文和未来时域，预测时域长度由「协变量长度 − 上下文长度」推断得出
• 动态协变量必须成对提供（历史段 + 未来段），两者要么都给要么都不给，校验逻辑在 xreg_lib.py
• 只有历史值、未来未知的变量（如实时系统负载）不能直接当动态协变量，先做延迟移位或用模型自举出未来值再使用

协变量模式怎么选

forecast_with_covariates提供两种xreg_mode，默认取值为 "xreg + timesfm"：

参数默认值以 timesfm_2p5_base.py 为准。拿不准就用默认模式，再用同一份数据做 A/B 对比决定。

三步完成协变量预测

1. 安装 xreg 扩展：pip install timesfm[xreg]
2. 编译模型时打开return_backcast=True，XReg 依赖这个开关
3. 把历史序列和四类协变量传入forecast_with_covariates，取回最终点预测与分位数预测

import timesfm # 加载 TimesFM 2.5；XReg 要求编译时 return_backcast=True model = timesfm.TimesFM_2p5_200M_torch.from_pretrained("google/timesfm-2.5-200m-pytorch") model.compile(timesfm.ForecastConfig(max_context=1024, max_horizon=256, return_backcast=True)) point_fc, quantile_fc = model.forecast_with_covariates( inputs=history, # 每条序列的历史上下文 dynamic_numerical_covariates={"gen_forecast": gen_full}, # 长度=上下文+时域 dynamic_categorical_covariates={"week_day": dow_full}, # 建议整型编码 static_categorical_covariates={"country": ["FR"] * len(history)}, xreg_mode="xreg + timesfm", # 默认：先回归、再预测残差 )

常见报错与修复

如何验证协变量是否生效

用无协变量的forecast和有协变量的forecast_with_covariates各跑一次，对比点预测的 MAE 与 MSE。官方 Notebook covariates.ipynb 在电价数据集上给出基准：MAE 从 6.73 降到 5.34，MSE 从 162.31 降到 120.99。你可以用同一份测试数据复现这套对照，确认提升来自你的协变量而非数据波动。

延伸阅读：仓库自带可运行的零售示例 demo_covariates.py，安装方式以 README.md 为准。

写在最后

动态协变量解决的是一个具体问题：把「历史曲线里看不见、但你已经知道」的信息接进预测链路。从默认模式 "xreg + timesfm" 起步，保证协变量长度与成对关系正确，再用 MAE/MSE 对比量化它带来的改善。

【免费下载链接】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