SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场timesfm-forecasting

timesfm-forecasting

数据与分析

查看项目

更新于 10-21 16:20

技能介绍

用途

TimesFM Forecasting 用于对任意单变量时间序列进行零样本预测，无需训练自定义模型。适用场景包括销售、需求、传感器、生命体征、价格、天气等序列的预测，也支持对数百或数千条序列进行批量预测。它提供带校准预测区间（分位数）的概率预测，可处理长度在 1 到 16,384 个上下文点之间的序列。

不适用场景：需要可解释系数的经典统计模型（应使用 statsmodels）；时间序列分类或聚类（应使用 aeon）；多变量向量自回归或格兰杰因果（应使用 statsmodels）；非时间性的表格数据（应使用 scikit-learn）。TimesFM 本身不含内置异常检测，但可用分位数预测作为预测区间，落在 90% 置信区间（q10–q90）之外的值可视为统计上异常。

主要能力

  • 零样本预测：直接输入单变量序列，返回点预测与分位数预测区间，无需训练。
  • 概率预测：输出 10 个分位数带（第 10 至第 90 百分位），可推导预测区间。
  • 批量预测：支持一次对多条序列进行预测。
  • 协变量支持（TimesFM 2.5+）：通过 forecast_with_covariates() 支持外生变量，包括动态数值协变量（如价格、温度、促销支出）、动态分类协变量（如节假日标志、星期几）、静态数值协变量（如门店面积、账户年龄）和静态分类协变量（如门店类型、地区、产品类别）。XReg 模式有 "xreg + timesfm"（默认，先由 TimesFM 预测再由 XReg 调整残差）和 "timesfm + xreg"（先由 XReg 拟合再由 TimesFM 预测残差）。
  • 异常检测：利用分位数区间，落在 80% 置信区间外为警告，落在 90% 置信区间外为严重异常。

使用方式

强制预检：首次加载模型前必须运行 python scripts/check_system.py，检查可用内存（低于 4 GB 警告，低于 2 GB 阻止）、GPU 可用性与显存、磁盘空间（约 800 MB 模型下载）、Python 版本（需 3.10+）以及 timesfm 和 torch 是否已安装。模型权重不存储在本仓库中，首次使用时从 HuggingFace 按需下载（约 800 MB），缓存于 ~/.cache/huggingface/。

安装步骤：

  1. 运行 python scripts/check_system.py。
  2. 安装 TimesFM：uv pip install timesfm[torch]，或 JAX/Flax 后端 uv pip install timesfm[flax]。
  3. 安装 PyTorch：CUDA 12.1 使用 uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121；仅 CPU 使用 uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu；Apple Silicon（MPS）使用 uv pip install torch>=2.0.0。
  4. 验证安装：import timesfm; import numpy as np; print(f"TimesFM version: {timesfm.__version__}"); print("Installation OK")。

最小示例：

import torch, numpy as np, 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, quantiles = model.forecast(horizon=24, inputs=[
    np.sin(np.linspace(0, 20, 200)),
])

从 CSV 预测：读取 CSV 后将每列转为 1-D 数组列表，调用 model.forecast(horizon=12, inputs=inputs)，再构建结果 DataFrame。

协变量预测（需 uv pip install timesfm[xreg]）：

point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"price": price_arrays},
    dynamic_categorical_covariates={"holiday": holiday_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",
)

可用脚本：scripts/check_system.py（强制预检）和 scripts/forecast_csv.py（端到端 CSV 预测，自动系统检查，支持 --horizon、--date-col、--value-cols、--output 参数）。

参考文档：references/output_and_config.md（输出与 ForecastConfig 字段）、references/workflows.md（标准预测流程、宽表多序列预测、回测与区间覆盖）、references/performance_tuning.md（GPU 与 TF32 设置、per_core_batch_size、内存管理）、references/examples_and_validation.md（可运行示例、质量清单、常见错误、回归检查）、references/system_requirements.md、references/api_reference.md、references/data_preparation.md。

适用场景

  • 对销售、需求、传感器、生命体征、价格、天气等单变量序列做零样本预测。
  • 需要概率预测与校准预测区间。
  • 批量预测数百或数千条序列。
  • 希望使用基础模型方法而非手工调参 ARIMA/ETS。
  • 与 statsmodels 的 ARIMA/SARIMAX 做基线对比。
  • 与 matplotlib / scientific-visualization 配合绘制带预测区间的出版级图表。
  • 与 exploratory-data-analysis 配合，在预测前理解趋势、季节性和平稳性。

限制

  • 仅支持单变量时间序列，不支持多变量向量自回归或格兰杰因果。
  • 无内置异常检测，需借助分位数区间实现。
  • 无内置时间序列分类或聚类能力。
  • 不适用于非时间性的表格数据。
  • 硬件要求：TimesFM 2.5（200M 参数）需 CPU 内存 ≥ 4 GB、GPU 显存 ≥ 2 GB、磁盘约 800 MB，上下文最长 16,384；TimesFM 2.0（500M 参数，已归档）需内存 ≥ 16 GB、显存 ≥ 8 GB、磁盘约 2 GB，上下文最长 2,048；TimesFM 1.0（200M 参数，已归档）需内存 ≥ 8 GB、显存 ≥ 4 GB、磁盘约 800 MB，上下文最长 2,048。
  • 常见陷阱：未运行系统检查、忘记 model.compile()、未设置 normalize_inputs=True、在小内存机器上使用 v1/v2、未设置 fix_quantile_crossing=True、per_core_batch_size 过大导致 CUDA OOM、传入 2-D 数组（应传 1-D 数组列表）、未设置 torch.set_float32_matmul_precision("high")、未处理输出中的 NaN、对可能为负的序列使用 infer_is_positive=True。

模型版本

  • TimesFM 2.5：200M 参数，16,384 上下文，连续分位数头（30M），已移除频率标志，最新版本。
  • TimesFM 2.0：500M 参数，2,048 上下文，固定分位数桶，需要频率标志，已归档。
  • TimesFM 1.0：200M 参数，2,048 上下文，固定分位数桶，需要频率标志，已归档。

Hugging Face 检查点：google/timesfm-2.5-200m-pytorch（推荐）、google/timesfm-2.5-200m-flax、google/timesfm-2.0-500m-pytorch（已归档）、google/timesfm-1.0-200m-pytorch（已归档）。

资源

  • 论文：A Decoder-Only Foundation Model for Time-Series Forecasting (ICML 2024)
  • 仓库：https://github.com/google-research/timesfm
  • Hugging Face：https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
  • Google Blog：https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/
  • BigQuery 集成：https://cloud.google.com/bigquery/docs/timesfm-model