timesfm-forecasting

TimesFM 预测

概述

TimesFM（时间序列基础模型）是由 Google Research 开发的预训练纯解码器基础模型， 用于时间序列预测。它可以零样本运行——输入任意单变量时间序列，即可返回点预测和经过校准的分位数 预测区间，无需训练。

此技能封装了 TimesFM，支持安全、便于 Agent 使用的本地推理。它包含一个 强制预检系统检查器，会在加载模型之前验证 RAM、GPU 内存和磁盘空间， 从而避免 Agent 导致用户的机器崩溃。

关键数据：TimesFM 2.5 使用 200M 个参数（磁盘占用约 800 MB，CPU 上约需 1.5 GB RAM， GPU 上约需 1 GB VRAM）。已归档的 v1/v2 500M 参数模型需要约 32 GB RAM。 请始终先运行系统检查器。

何时使用此技能

在以下情况下使用此技能：

• 预测任意单变量时间序列（销售额、需求、传感器数据、生命体征、价格、天气）
• 需要零样本预测，而无需训练自定义模型
• 需要带校准预测区间（分位数）的概率预测
• 时间序列的长度不限（模型支持 1–16,384 个上下文点）
• 需要高效地对数百或数千个序列进行批量预测
• 希望采用基础模型方案，而不是手动调整 ARIMA/ETS 参数

在以下情况下不要使用此技能：

• 需要能够解释系数的经典统计模型 → 使用 statsmodels
• 需要进行时间序列分类或聚类 → 使用 aeon
• 需要多变量向量自回归或格兰杰因果检验 → 使用 statsmodels
• 数据是表格型数据（非时间序列）→ 使用 scikit-learn

异常检测说明：TimesFM 没有内置异常检测功能，但你可以 将分位数预测用作预测区间——90% 置信区间（q10–q90）之外的值在统计上属于异常值。完整示例请参阅 examples/anomaly-detection/ 目录。

⚠️ 强制预检：系统要求检查

重要——首次加载模型前务必运行系统检查器。

python scripts/check_system.py

此脚本会检查：

1. 可用 RAM——低于 4 GB 时发出警告，低于 2 GB 时阻止运行
2. GPU 可用性——检测 CUDA/MPS 设备和 VRAM
3. 磁盘空间——确认有足够空间下载约 800 MB 的模型
4. Python 版本——需要 3.10+
5. 现有安装——检查是否已安装 timesfm 和 torch

注意：模型权重不会存储在此代码库中。TimesFM 权重（约 800 MB） 首次使用时会按需从 HuggingFace 下载，并缓存到 ~/.cache/huggingface/。 预检检查器会在开始任何下载前确认资源充足。

flowchart TD
    accTitle: Preflight System Check
    accDescr: Decision flowchart showing the system requirement checks that must pass before loading TimesFM.

    start["🚀 Run check_system.py"] --> ram{"RAM ≥ 4 GB?"}
    ram -->|"Yes"| gpu{"GPU available?"}
    ram -->|"No (2-4 GB)"| warn_ram["⚠️ Warning: tight RAM<br/>CPU-only, small batches"]
    ram -->|"No (< 2 GB)"| block["🛑 BLOCKED<br/>Insufficient memory"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
    gpu -->|"CPU only"| cpu_ok["✅ CPU mode<br/>Slower but works"]
    vram -->|"Yes"| gpu_ok["✅ GPU mode<br/>Fast inference"]
    vram -->|"No"| cpu_ok
    gpu_ok --> disk{"Disk ≥ 2 GB free?"}
    cpu_ok --> disk
    disk -->|"Yes"| ready["✅ READY<br/>Safe to load model"]
    disk -->|"No"| block_disk["🛑 BLOCKED<br/>Need space for weights"]

    classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warn fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef block fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

    class ready,gpu_ok,cpu_ok ok
    class warn_ram warn
    class block,block_disk block
    class start,ram,gpu,vram,disk neutral

各模型版本的硬件要求

模型	参数量	RAM（CPU）	VRAM（GPU）	磁盘	上下文
TimesFM 2.5（推荐）	200M	≥ 4 GB	≥ 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

建议：除非有特定理由使用较旧的检查点，否则请始终使用 TimesFM 2.5。 它更小、更快，并支持长 8 倍的上下文。

🔧 安装

步骤 1：验证系统（始终首先执行）

python scripts/check_system.py

步骤 2：安装 TimesFM

# Using uv (recommended by this repo)
uv pip install timesfm[torch]

# For JAX/Flax backend (faster on TPU/GPU)
uv pip install timesfm[flax]

步骤 3：根据硬件安装 PyTorch

# CUDA 12.1 (NVIDIA GPU)
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121

# CPU only
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  # MPS support is built-in

步骤 4：验证安装

import timesfm
import numpy as np
print(f"TimesFM version: {timesfm.__version__}")
print("Installation OK")

🎯 快速入门

最简示例（5 行）

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)),  # any 1-D array
])
# point.shape == (1, 24)        — median forecast
# quantiles.shape == (1, 24, 10) — 10th–90th percentile bands

从 CSV 进行预测

import pandas as pd, numpy as np

df = pd.read_csv("monthly_sales.csv", parse_dates=["date"], index_col="date")

# Convert each column to a list of arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

point, quantiles = model.forecast(horizon=12, inputs=inputs)

# Build a results DataFrame
for i, col in enumerate(df.columns):
    last_date = df[col].dropna().index[-1]
    future_dates = pd.date_range(last_date, periods=13, freq="MS")[1:]
    forecast_df = pd.DataFrame({
        "date": future_dates,
        "forecast": point[i],
        "lower_80": quantiles[i, :, 2],  # 20th percentile
        "upper_80": quantiles[i, :, 8],  # 80th percentile
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

使用协变量进行预测（XReg）

TimesFM 2.5+ 通过 forecast_with_covariates() 支持外生变量。需要安装 timesfm[xreg]。

# Requires: 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",  # or "timesfm + xreg"
)

协变量类型	描述	示例
dynamic_numerical	随时间变化的数值	价格、温度、促销支出
dynamic_categorical	随时间变化的类别	节假日标记、星期几
static_numerical	每条序列对应的数值	店铺规模、账户年限
static_categorical	每条序列对应的类别	店铺类型、地区、产品类别

XReg 模式：

• "xreg + timesfm"（默认）：TimesFM 先进行预测，然后由 XReg 调整残差
• "timesfm + xreg"：XReg 先拟合，然后由 TimesFM 预测残差

完整示例（使用合成零售数据）请参见 examples/covariates-forecasting/。

异常检测（通过分位数区间）

TimesFM 没有内置异常检测功能，但分位数预测会自然生成预测区间，可用于检测异常：

point, q = model.forecast(horizon=H, inputs=[values])

# 90% prediction interval
lower_90 = q[0, :, 1]  # 10th percentile
upper_90 = q[0, :, 9]  # 90th percentile

# Detect anomalies: values outside the 90% CI
actual = test_values  # your holdout data
anomalies = (actual < lower_90) | (actual > upper_90)

# Severity levels
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # outside 80% CI
is_critical = anomalies  # outside 90% CI

严重程度	条件	说明
正常	在 80% 置信区间内	符合预期的行为
警告	超出 80% 置信区间	异常但仍有可能
严重	超出 90% 置信区间	统计上较为罕见（概率 < 10%）

带可视化的完整示例请参见 examples/anomaly-detection/。

# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temperature": temp_arrays},
    dynamic_categorical_covariates={"day_of_week": dow_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"
)

输出、配置、工作流与调优

• references/output_and_config.md：读取点预测和 10 个分位数区间、推导预测区间，以及 ForecastConfig 的所有字段。
• references/workflows.md：标准预测流程、从宽格式 CSV 预测多个序列，以及通过区间覆盖率进行回测。
• references/performance_tuning.md：GPU 和 TF32 设置、根据可用内存选择 per_core_batch_size，以及内存管理。
• references/examples_and_validation.md：可运行示例、质量检查清单、常见错误和回归检查。

🔗 与其他技能集成

与 statsmodels 配合

使用 statsmodels 进行经典模型（ARIMA、SARIMAX）预测，作为比较基线：

# TimesFM forecast
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[values])

# statsmodels ARIMA forecast
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)

# Compare
print(f"TimesFM MAE: {np.mean(np.abs(actual - tfm_point[0])):.2f}")
print(f"ARIMA MAE:   {np.mean(np.abs(actual - arima_forecast)):.2f}")

与 matplotlib / scientific-visualization 配合

绘制带预测区间的预测图，生成适合发表的图表。

与 exploratory-data-analysis 配合

在预测前对时间序列进行 EDA，以了解趋势、季节性和平稳性。

📚 可用脚本

scripts/check_system.py

**强制执行的预检工具。**首次加载模型前运行。

python scripts/check_system.py

输出示例：

=== TimesFM System Requirements Check ===

[RAM]       Total: 32.0 GB | Available: 24.3 GB  ✅ PASS
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ PASS
[Disk]      Free: 142.5 GB                        ✅ PASS
[Python]    3.12.1                                 ✅ PASS
[timesfm]   Installed (2.5.0)                      ✅ PASS
[torch]     Installed (2.4.1+cu121)                ✅ PASS

VERDICT: ✅ System is ready for TimesFM 2.5 (GPU mode)
Recommended: per_core_batch_size=128

scripts/forecast_csv.py

通过自动系统检查，端到端完成 CSV 预测。

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

📖 参考文档

详细指南位于 references/：

文件	内容
references/system_requirements.md	硬件等级、GPU/CPU 选择、内存估算公式
references/api_reference.md	完整的 ForecastConfig 文档、from_pretrained 选项、输出形状
references/data_preparation.md	输入格式、NaN 处理、CSV 加载、协变量设置

常见陷阱

1. 未运行系统检查 → 在 RAM 较小的机器上加载模型时会崩溃。务必先运行 check_system.py。
2. 忘记调用 model.compile() → RuntimeError: Model is not compiled。必须先调用 compile()，再调用 forecast()。
3. 未设置 normalize_inputs=True → 对数值较大的序列进行预测时结果不稳定。
4. 在 RAM 小于 32 GB 的机器上使用 v1/v2 → 改用 TimesFM 2.5（200M 参数）。
5. 未设置 fix_quantile_crossing=True → 分位数可能不单调（q10 > q50）。
6. 在小型 GPU 上设置过大的 per_core_batch_size → CUDA 内存不足。从较小的值开始，逐步增大。
7. 传入二维数组 → TimesFM 需要的是一维数组列表，而不是二维矩阵。
8. 忘记调用 torch.set_float32_matmul_precision("high") → 在 Ampere 及更新型号的 GPU 上推理速度会变慢。
9. 未处理输出中的 NaN → 序列非常短时可能遇到边缘情况。务必检查 np.isnan(point).any()。
10. 对可能为负值的序列设置 infer_is_positive=True → 预测值会被限制为不小于零。对于温度、收益等数据，请设为 False。

模型版本

timeline
    accTitle: TimesFM Version History
    accDescr: Timeline of TimesFM model releases showing parameter counts and key improvements.

    section 2024
        TimesFM 1.0 : 200M params, 2K context, JAX only
        TimesFM 2.0 : 500M params, 2K context, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M params, 16K context, quantile head, no frequency indicator

版本	参数量	上下文长度	分位数输出头	频率标志	状态
2.5	200M	16,384	✅ 连续型（30M）	❌ 已移除	最新
2.0	500M	2,048	✅ 固定分桶	✅ 必需	已归档
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 博客：https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/
• BigQuery 集成：https://cloud.google.com/bigquery/docs/timesfm-model

相关技能

• aeon：适用于时间序列机器学习任务，包括分类、回归、聚类、预测、异常检测……
• statsmodels：Python 统计模型库。
• segment-anything-model：用于图像分割并支持零样本迁移的基础模型。