timesfm-forecasting

TimesFM 预测

首先选择模型/API

Python 包版本为 3.0.2；检查点版本另行区分。

检查点	接口	分位数输出	使用条款
2.5, 200M	timesfm.TimesFM_2p5_200M_torch、compile、forecast	均值 + 9 个十分位数，中位数索引 5	Apache-2.0 权重；捆绑 CLI 默认
3.0, 约 330M	timesfm3.TimesFM3Forecaster、predict / predict_batch	9 个十分位数，中位数索引 4	下载的权重仅限非商业、非生产用途

上游将 3.0 标识为最新模型。本技能保留 2.5 作为其默认本地工作流，因为其 Apache 许可的权重具有不同的使用条款。 对于 3.0 多变量目标、仅过去的协变量或 Apple MLX，在改编代码前请阅读 references/timesfm3.md。授权的 Google Cloud 服务有单独的条款；Cloud 授权不会改变 下载权重的许可证。参见上游许可证声明。

在无需任务特定模型训练的情况下，使用 TimesFM 预测有序时间目标。 它不是因果效应估计器、临床检测器或基于物理的气候模型。零样本描述的是拟合；它并不确立 预训练中不存在基准重叠，也不确立在新领域中具有良好的准确率。

工作流

1. 确定周期、单位、预测起点、预测范围、起点已知协变量、 评估截止点以及朴素/季节性朴素基线。
2. 验证排序、唯一、规则的时间网格。不要对内部缺口使用 dropna()： 那会改变时间间隔。拒绝非有限输入，或在每个训练历史内 显式插补。切勿使用留出的未来目标进行填充。
3. 在下载/加载权重之前运行 python scripts/check_system.py。 其可用 RAM 和缓存卷阈值是启发式的，并非防止 OOM 的保证。 从批大小 1 开始；测量实际峰值使用量。
4. 使用记录的不可变修订版本加载所选检查点。对于 2.5， 编译显式的正上下文/预测范围设置；零不意味着 “使用最大值”。在使用连续分位数头时，保持块取整的上下文 + 预测范围 <=16,384 且预测范围 <=1,024。
5. 预测、验证形状/有限值/分位数排序并导出 预测起点、频率、配置和检查点修订版本。
6. 使用按各起点独立拟合的预处理，跨滚动起点进行评估。 按预测范围报告准确率、区间覆盖率和区间宽度； 在相关数据上校准之前，将分位数区间标记为名义区间。

安装

在单独的环境中运行。以下命令针对已审核的版本。 Shell 附加项和版本约束必须加引号，尤其是在 zsh 中。

uv venv .venv-timesfm
uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
.venv-timesfm/bin/python scripts/check_system.py

使用当前的 PyTorch 安装选择器 获取与主机匹配的 CUDA wheel。此版本中的 2.5 加载器会选择 cuda:0（如果 CUDA 存在），否则选择 CPU；检测到 MPS 不会在 MPS 上启用 推理。不要像对 nn.Module 那样对包装器使用 model.to(...)。 对于仅 CPU 的 XReg，请与 PyTorch 配置一起安装 jax 和 scikit-learn； 上游的 [xreg] 附加项请求 jax[cuda]，这不适用于 macOS。 Flax 是单独的、可选的后端；捆绑脚本并不需要它。

from importlib.metadata import version
import timesfm
print(version("timesfm"))  # package has no guaranteed timesfm.__version__
assert hasattr(timesfm, "TimesFM_2p5_200M_torch")

TimesFM 2.5 快速开始

检查点加载示例仅用于说明：本次刷新的验证使用了原生包代码、微型随机模型和受控解码夹具，未下载预训练权重。这验证的是机制，而非准确率。

import numpy as np
import timesfm

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch",
    revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
    torch_compile=False,  # avoid compilation startup during an initial smoke run
)
model.compile(timesfm.ForecastConfig(
    max_context=512, max_horizon=128, per_core_batch_size=1,
    normalize_inputs=True, use_continuous_quantile_head=True,
    force_flip_invariance=True, infer_is_positive=False,
    fix_quantile_crossing=True,
))
histories = [np.sin(np.linspace(0, 20, 200)).astype(np.float32)]
# 2.5 may append dummy series to its input list during batching; pass a fresh list.
point, q = model.forecast(horizon=24, inputs=list(histories))
assert point.shape == (1, 24) and q.shape == (1, 24, 10)
assert np.isfinite(q).all() and np.all(np.diff(q[..., 1:], axis=-1) >= 0)
assert np.allclose(point, q[..., 5])
lower_80, upper_80 = q[..., 1], q[..., 9]  # q10-q90: nominal 80% PI
lower_60, upper_60 = q[..., 2], q[..., 8]  # q20-q80: nominal 60% PI

仅当目标域确实非负时，才设置 infer_is_positive=True。观测窗口为正并不能说明温度异常、收益率或残差不会变为负值。单调分位数和连续分位数头并不能说明区间校准。

CSV 辅助工具

python scripts/forecast_csv.py monthly_sales.csv \
  --date-col date --freq MS --value-cols sales,revenue \
  --horizon 12 --batch-size 1 --nonnegative --output forecasts.csv

forecast_csv.py 在加载前进行验证，对日期排序，拒绝重复表头/日期，检查完整的规则网格并保留缺失位置。缺失值默认报错；--missing interpolate 仅填充内部缺口，绝不填充首尾值。未指定 --date-col 时，假定行顺序为规则网格，输出使用步数。数值 ID 必须通过 --value-cols 排除。--max-context 控制历史截断；在此分位数头工作流中，--horizon 限制为 1..1,024。

输出保留 forecast、median、lower_80、upper_80、lower_60、upper_60。.metadata.json 附属文件记录来源、频率、模型修订版本和配置。旧版技能发布将 q10-q90/q20-q80 错误标记为 90%/80%；请同时将旧的外层 *_90 迁移为 *_80，将旧的内层 *_80 迁移为 *_60。旧的生成示例预测已被移除，因为其映射/来源无效。

协变量与异常筛查

对于 2.5 XReg，请以 return_backcast=True 编译，将目标与协变量保留在相同的网格上，并在上下文 和 预测期上提供动态协变量。"xreg + timesfm" 先对目标拟合回归，再预测回归残差。"timesfm + xreg" 先预测，再对回测残差拟合回归。后者需要多于一个输入补丁（32 个观测值）。在包 3.0.2 中，实现返回 合并的点预测和分位数预测列表；继承的文档字符串错误地将第二个返回值描述为仅 XReg。完整调用请参见 references/api_reference.md。

分位数超出情况可用于筛查异常观测，但即使经过校准的 80% 区间，在边际上也会排除约 20% 的普通观测。它们不提供异常概率、族系错误率控制或经过验证的告警严重程度。回顾性去趋势 Z 分数也不同于前瞻性异常检测。

参考与示例

• API 参考：2.5 加载器、编译、预测和 XReg 契约。
• 输出/配置：所有真实的 ForecastConfig 字段和区间索引。
• 数据准备：网格、缺失性、协变量时序和格式配方。
• 工作流：留出集和滚动原点验证、基线比较。
• 系统要求：资源检查和后端要求。
• 性能调优：经测量的批处理/上下文调优。
• 示例与验证：示例命令和测试范围。
• TimesFM 3.0：多变量 API、9 分位布局和使用边界。

主要评审来源：官方源、 3.0.2 发行版、 2.5 模型卡、 3.0 模型卡。