timesfm-forecasting

TimesFM-Prognose

Überblick

TimesFM (Time Series Foundation Model) ist ein vortrainiertes, Decoder-only Foundation Model, das von Google Research für Zeitreihenprognosen entwickelt wurde. Es funktioniert Zero-Shot – füttere es mit einer beliebigen univariaten Zeitreihe und es gibt Punktprognosen mit kalibrierten Quantil-Vorhersageintervallen zurück, ohne dass ein Training erforderlich ist.

Dieses Skill kapselt TimesFM für eine sichere, agentenfreundliche lokale Inferenz. Es enthält einen obligatorischen Preflight-System-Checker, der RAM, GPU-Speicher und Festplattenplatz überprüft, bevor das Modell jemals geladen wird, sodass der Agent niemals den Rechner des Benutzers zum Absturz bringt.

Wichtige Zahlen: TimesFM 2.5 verwendet 200 Millionen Parameter (~800 MB auf der Festplatte, ~1,5 GB RAM auf der CPU, ~1 GB VRAM auf der GPU). Das archivierte v1/v2 500M-Parameter-Modell benötigt ~32 GB RAM. Führe immer zuerst den System-Checker aus.

Wann dieses Skill verwendet werden sollte

Verwende dieses Skill, wenn:

• Prognosen für beliebige univariate Zeitreihen (Verkauf, Nachfrage, Sensor, Vitaldaten, Preis, Wetter) benötigt werden
• Zero-Shot-Prognosen ohne Training eines benutzerdefinierten Modells erforderlich sind
• Probabilistische Prognosen mit kalibrierten Vorhersageintervallen (Quantilen) gewünscht werden
• Zeitreihen beliebiger Länge vorliegen (das Modell verarbeitet 1–16.384 Kontextpunkte)
• Hunderte oder Tausende von Serien effizient als Batch prognostiziert werden müssen
• Ein Foundation-Model-Ansatz anstelle von manuell abgestimmten ARIMA/ETS-Parametern bevorzugt wird

Verwende dieses Skill nicht, wenn:

• Klassische statistische Modelle mit Koeffizienteninterpretation benötigt werden → verwende statsmodels
• Zeitreihenklassifikation oder -clustering benötigt wird → verwende aeon
• Multivariate Vektorautoregression oder Granger-Kausalität benötigt wird → verwende statsmodels
• Die Daten tabellarisch (nicht zeitlich) sind → verwende scikit-learn

Hinweis zur Anomalieerkennung: TimesFM hat keine integrierte Anomalieerkennung, aber du kannst die Quantil-Prognosen als Vorhersageintervalle verwenden – Werte außerhalb des 90%-KI (q10–q90) sind statistisch ungewöhnlich. Siehe das Verzeichnis examples/anomaly-detection/ für ein vollständiges Beispiel.

⚠️ Obligatorischer Preflight: Systemanforderungsprüfung

KRITISCH – Führe IMMER den System-Checker aus, bevor das Modell zum ersten Mal geladen wird.

python scripts/check_system.py

Dieses Skript prüft:

1. Verfügbarer RAM – warnt, wenn unter 4 GB, blockiert, wenn unter 2 GB
2. GPU-Verfügbarkeit – erkennt CUDA/MPS-Geräte und VRAM
3. Festplattenspeicher – überprüft ausreichend Platz für den ~800 MB Modell-Download
4. Python-Version – erfordert 3.10+
5. Vorhandene Installation – prüft, ob timesfm und torch installiert sind

Hinweis: Modellgewichte werden NICHT in diesem Repository gespeichert. TimesFM-Gewichte (~800 MB) werden bei der ersten Verwendung on-demand von HuggingFace heruntergeladen und in ~/.cache/huggingface/ zwischengespeichert. Der Preflight-Checker stellt sicher, dass ausreichende Ressourcen vorhanden sind, bevor ein Download beginnt.

flowchart TD
    accTitle: Preflight System Check
    accDescr: Entscheidungsflussdiagramm, das die Systemanforderungsprüfungen zeigt, die vor dem Laden von TimesFM bestanden werden müssen.

    start["🚀 Führe check_system.py aus"] --> ram{"RAM ≥ 4 GB?"}
    ram -->|"Ja"| gpu{"GPU verfügbar?"}
    ram -->|"Nein (2-4 GB)"| warn_ram["⚠️ Warnung: Knapper RAM<br/>Nur CPU, kleine Batches"]
    ram -->|"Nein (< 2 GB)"| block["🛑 GESPERRT<br/>Unzureichender Speicher"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
    gpu -->|"Nur CPU"| cpu_ok["✅ CPU-Modus<br/>Langsamer, aber funktionsfähig"]
    vram -->|"Ja"| gpu_ok["✅ GPU-Modus<br/>Schnelle Inferenz"]
    vram -->|"Nein"| cpu_ok
    gpu_ok --> disk{"Festplatte ≥ 2 GB frei?"}
    cpu_ok --> disk
    disk -->|"Ja"| ready["✅ BEREIT<br/>Sicheres Laden des Modells"]
    disk -->|"Nein"| block_disk["🛑 GESPERRT<br/>Speicherplatz für Gewichte benötigt"]

    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

Hardware-Anforderungen nach Modellversion

Modell	Parameter	RAM (CPU)	VRAM (GPU)	Festplatte	Kontext
TimesFM 2.5 (empfohlen)	200M	≥ 4 GB	≥ 2 GB	~800 MB	bis zu 16.384
TimesFM 2.0 (archiviert)	500M	≥ 16 GB	≥ 8 GB	~2 GB	bis zu 2.048
TimesFM 1.0 (archiviert)	200M	≥ 8 GB	≥ 4 GB	~800 MB	bis zu 2.048

Empfehlung: Verwende immer TimesFM 2.5, es sei denn, du hast einen bestimmten Grund, einen älteren Checkpoint zu verwenden. Es ist kleiner, schneller und unterstützt 8× längeren Kontext.

🔧 Installation

Schritt 1: System überprüfen (immer zuerst)

python scripts/check_system.py

Schritt 2: TimesFM installieren

# Mit uv (von diesem Repository empfohlen)
uv pip install timesfm[torch]

# Für JAX/Flax-Backend (schneller auf TPU/GPU)
uv pip install timesfm[flax]

Schritt 3: PyTorch für deine Hardware installieren

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

# Nur 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  # MPS-Unterstützung ist integriert

Schritt 4: Installation überprüfen

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

🎯 Schnellstart

Minimalbeispiel (5 Zeilen)

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)),  # beliebiges 1-D-Array
])
# point.shape == (1, 24)        — Median-Prognose
# quantiles.shape == (1, 24, 10) — 10. bis 90. Perzentil-Bänder

Prognose aus einer CSV

import pandas as pd, numpy as np

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

# Jede Spalte in eine Liste von Arrays konvertieren
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

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

# Ergebnis-DataFrame erstellen
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],  # 20. Perzentil
        "upper_80": quantiles[i, :, 8],  # 80. Perzentil
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

Prognose mit Kovariaten (XReg)

TimesFM 2.5+ unterstützt exogene Variablen über forecast_with_covariates(). Erfordert timesfm[xreg].

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

Kovariatentyp	Beschreibung	Beispiel
dynamic_numerical	Zeitvariierende numerische	Preis, Temperatur, Werbeausgaben
dynamic_categorical	Zeitvariierende kategoriale	Feiertagsflagge, Wochentag
static_numerical	Pro-Serie numerische	Filialgröße, Kontosaldo
static_categorical	Pro-Serie kategoriale	Filialtyp, Region, Produktkategorie

XReg-Modi:

• "xreg + timesfm" (Standard): TimesFM prognostiziert zuerst, dann passt XReg die Residuen an
• "timesfm + xreg": XReg passt zuerst, dann prognostiziert TimesFM die Residuen

Siehe examples/covariates-forecasting/ für ein vollständiges Beispiel mit synthetischen Einzelhandelsdaten.

Anomalieerkennung (über Quantilintervalle)

TimesFM hat keine integrierte Anomalieerkennung, aber die Quantil-Prognosen liefern auf natürliche Weise Vorhersageintervalle, die Anomalien erkennen können:

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

# 90%-Vorhersageintervall
lower_90 = q[0, :, 1]  # 10. Perzentil
upper_90 = q[0, :, 9]  # 90. Perzentil

# Anomalien erkennen: Werte außerhalb des 90%-KI
actual = test_values  # deine Holdout-Daten
anomalies = (actual < lower_90) | (actual > upper_90)

# Schweregrade
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # außerhalb des 80%-KI
is_critical = anomalies  # außerhalb des 90%-KI

Schweregrad	Bedingung	Interpretation
Normal	Innerhalb des 80%-KI	Erwartetes Verhalten
Warnung	Außerhalb des 80%-KI	Ungewöhnlich, aber möglich
Kritisch	Außerhalb des 90%-KI	Statistisch selten (< 10% Wahrscheinlichkeit)

Siehe examples/anomaly-detection/ für ein vollständiges Beispiel mit Visualisierung.

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

Ausgabe, Konfiguration, Arbeitsabläufe und Optimierung

• references/output_and_config.md: Lesen der Punktprognose und der 10 Quantilbänder, Ableiten von Vorhersageintervallen und jedes ForecastConfig-Feld.
• references/workflows.md: Der standardmäßige Prognoseablauf, Prognosen für viele Serien aus einer breiten CSV und Backtesting mit Intervallabdeckung.
• references/performance_tuning.md: GPU- und TF32-Einrichtung, per_core_batch_size nach verfügbarem Speicher und Speicherverwaltung.
• references/examples_and_validation.md: Ausführbare Beispiele, die Qualitätscheckliste, häufige Fehler und Regressionsprüfungen.

🔗 Integration mit anderen Skills

Mit statsmodels

Verwende statsmodels für klassische Modelle (ARIMA, SARIMAX) als Vergleichsbasis:

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

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

# Vergleiche
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}")

Mit matplotlib / scientific-visualization

Erstelle publikationsreife Grafiken von Prognosen mit Vorhersageintervallen.

Mit exploratory-data-analysis

Führe vor der Prognose eine explorative Datenanalyse der Zeitreihe durch, um Trends, Saisonalität und Stationarität zu verstehen.

📚 Verfügbare Skripte

scripts/check_system.py

Obligatorischer Preflight-Checker. Vor dem ersten Modellladen ausführen.

python scripts/check_system.py

Beispielausgabe:

=== TimesFM System Requirements Check ===

[RAM]       Gesamt: 32.0 GB | Verfügbar: 24.3 GB  ✅ BESTANDEN
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ BESTANDEN
[Festplatte] Frei: 142.5 GB                       ✅ BESTANDEN
[Python]    3.12.1                                 ✅ BESTANDEN
[timesfm]   Installiert (2.5.0)                    ✅ BESTANDEN
[torch]     Installiert (2.4.1+cu121)              ✅ BESTANDEN

URTEIL: ✅ System ist bereit für TimesFM 2.5 (GPU-Modus)
Empfohlen: per_core_batch_size=128

scripts/forecast_csv.py

End-to-End-CSV-Prognose mit automatischem Systemcheck.

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

📖 Referenzdokumentation

Ausführliche Anleitungen in references/:

Datei	Inhalt
references/system_requirements.md	Hardware-Stufen, GPU/CPU-Auswahl, Speicherschätzformeln
references/api_reference.md	Vollständige ForecastConfig-Dokumentation, from_pretrained-Optionen, Ausgabeformen
references/data_preparation.md	Eingabeformate, NaN-Behandlung, CSV-Laden, Kovariateneinrichtung

Häufige Fallstricke

1. Systemcheck nicht ausgeführt → Modellladen stürzt auf Maschinen mit wenig RAM ab. Führe immer zuerst check_system.py aus.
2. model.compile() vergessen → RuntimeError: Model is not compiled. Vor forecast() muss compile() aufgerufen werden.
3. normalize_inputs=True nicht gesetzt → instabile Prognosen für Serien mit großen Werten.
4. Verwendung von v1/v2 auf Maschinen mit < 32 GB RAM → stattdessen TimesFM 2.5 (200M Parameter) verwenden.
5. fix_quantile_crossing=True nicht gesetzt → Quantile sind möglicherweise nicht monoton (q10 > q50).
6. Große per_core_batch_size auf kleiner GPU → CUDA OOM. Klein anfangen, steigern.
7. 2-D-Arrays übergeben → TimesFM erwartet eine Liste von 1-D-Arrays, keine 2-D-Matrix.
8. torch.set_float32_matmul_precision("high") vergessen → langsamere Inferenz auf Ampere+ GPUs.
9. NaN in der Ausgabe nicht behandelt → Grenzfälle mit sehr kurzen Serien. Immer np.isnan(point).any() prüfen.
10. infer_is_positive=True für Serien, die negativ sein können → klemmt Prognosen auf Null. Setze False für Temperatur, Renditen usw.

Modellversionen

timeline
    accTitle: TimesFM Versionsverlauf
    accDescr: Zeitleiste der TimesFM-Modellveröffentlichungen mit Parameteranzahl und wichtigsten Verbesserungen.

    section 2024
        TimesFM 1.0 : 200M Parameter, 2K Kontext, nur JAX
        TimesFM 2.0 : 500M Parameter, 2K Kontext, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M Parameter, 16K Kontext, Quantilkopf, kein Frequenzindikator

Version	Parameter	Kontext	Quantilkopf	Frequenz-Flag	Status
2.5	200M	16.384	✅	❌	Aktuell
2.0	500M	2.048	❌	✅	Archiviert
1.0	200M	2.048	❌	✅	Archiviert

Weitere Informationen findest du in references/system_requirements.md.

📄 Lizenz

Dieses Skill enthält den Code aus dem offiziellen Google TimesFM Repository, das unter der Apache License 2.0 lizenziert ist.