feat(skill): add timesfm-forecasting Agent Skill (agentskills.io)
Add a self-contained AI agent skill for TimesFM that teaches coding agents (Claude Code, OpenCode, Cursor, Codex) how to use the TimesFM API correctly — safe model loading, zero-shot forecasting, covariate workflows, anomaly detection, and the most common pitfalls. Files added: - AGENTS.md — auto-loaded skill document (root of repo) - claude-skill/scripts/check_system.py — mandatory preflight RAM/GPU/disk checker - claude-skill/scripts/forecast_csv.py — CLI wrapper for CSV forecasting - claude-skill/references/ — ForecastConfig API ref, data prep, HW reqs - claude-skill/examples/global-temperature/ — basic forecast + PNG/GIF pipeline - claude-skill/examples/anomaly-detection/ — two-phase detrend+Z-score + quantile PI - claude-skill/examples/covariates-forecasting/ — forecast_with_covariates() XReg demo - .gitattributes — Git LFS rules for PNG/GIF binary outputs Contributed by Clayton Young / Superior Byte Works LLC (@borealBytes) Apache 2.0 — same license as this repository
This commit is contained in:
Clayton Young
@@ -0,0 +1,201 @@
|
||||
# System Requirements for TimesFM
|
||||
|
||||
## Hardware Tiers
|
||||
|
||||
TimesFM can run on a variety of hardware configurations. This guide helps you
|
||||
choose the right setup and tune performance for your machine.
|
||||
|
||||
### Tier 1: Minimal (CPU-Only, 4–8 GB RAM)
|
||||
|
||||
- **Use case**: Light exploration, single-series forecasting, prototyping
|
||||
- **Model**: TimesFM 2.5 (200M) only
|
||||
- **Batch size**: `per_core_batch_size=4`
|
||||
- **Context**: Limit `max_context=512`
|
||||
- **Expected speed**: ~2–5 seconds per 100-point series
|
||||
|
||||
```python
|
||||
model.compile(timesfm.ForecastConfig(
|
||||
max_context=512,
|
||||
max_horizon=128,
|
||||
per_core_batch_size=4,
|
||||
normalize_inputs=True,
|
||||
use_continuous_quantile_head=True,
|
||||
fix_quantile_crossing=True,
|
||||
))
|
||||
```
|
||||
|
||||
### Tier 2: Standard (CPU 16 GB or GPU 4–8 GB VRAM)
|
||||
|
||||
- **Use case**: Batch forecasting (dozens of series), evaluation, production prototypes
|
||||
- **Model**: TimesFM 2.5 (200M)
|
||||
- **Batch size**: `per_core_batch_size=32` (CPU) or `64` (GPU)
|
||||
- **Context**: `max_context=1024`
|
||||
- **Expected speed**: ~0.5–1 second per 100-point series (GPU)
|
||||
|
||||
```python
|
||||
model.compile(timesfm.ForecastConfig(
|
||||
max_context=1024,
|
||||
max_horizon=256,
|
||||
per_core_batch_size=64,
|
||||
normalize_inputs=True,
|
||||
use_continuous_quantile_head=True,
|
||||
fix_quantile_crossing=True,
|
||||
))
|
||||
```
|
||||
|
||||
### Tier 3: Production (GPU 16+ GB VRAM or Apple Silicon 32+ GB)
|
||||
|
||||
- **Use case**: Large-scale batch forecasting (thousands of series), long context
|
||||
- **Model**: TimesFM 2.5 (200M)
|
||||
- **Batch size**: `per_core_batch_size=128–256`
|
||||
- **Context**: `max_context=4096` or higher
|
||||
- **Expected speed**: ~0.1–0.3 seconds per 100-point series
|
||||
|
||||
```python
|
||||
model.compile(timesfm.ForecastConfig(
|
||||
max_context=4096,
|
||||
max_horizon=256,
|
||||
per_core_batch_size=128,
|
||||
normalize_inputs=True,
|
||||
use_continuous_quantile_head=True,
|
||||
fix_quantile_crossing=True,
|
||||
))
|
||||
```
|
||||
|
||||
### Tier 4: Legacy Models (v1.0/v2.0 — 500M parameters)
|
||||
|
||||
- **⚠️ WARNING**: TimesFM v2.0 (500M) requires **≥ 16 GB RAM** (CPU) or **≥ 8 GB VRAM** (GPU)
|
||||
- **⚠️ WARNING**: TimesFM v1.0 legacy JAX version may require **≥ 32 GB RAM**
|
||||
- **Recommendation**: Unless you specifically need a legacy checkpoint, use TimesFM 2.5
|
||||
|
||||
## Memory Estimation
|
||||
|
||||
### CPU Memory (RAM)
|
||||
|
||||
Approximate RAM usage during inference:
|
||||
|
||||
| Component | TimesFM 2.5 (200M) | TimesFM 2.0 (500M) |
|
||||
| --------- | ------------------- | ------------------- |
|
||||
| Model weights | ~800 MB | ~2 GB |
|
||||
| Runtime overhead | ~500 MB | ~1 GB |
|
||||
| Input/output buffers | ~200 MB per 1000 series | ~500 MB per 1000 series |
|
||||
| **Total (small batch)** | **~1.5 GB** | **~3.5 GB** |
|
||||
| **Total (large batch)** | **~3 GB** | **~6 GB** |
|
||||
|
||||
**Formula**: `RAM ≈ model_weights + 0.5 GB + (0.2 MB × num_series × context_length / 1000)`
|
||||
|
||||
### GPU Memory (VRAM)
|
||||
|
||||
| Component | TimesFM 2.5 (200M) |
|
||||
| --------- | ------------------- |
|
||||
| Model weights | ~800 MB |
|
||||
| KV cache + activations | ~200–500 MB (scales with context) |
|
||||
| Batch buffers | ~100 MB per 100 series at context=1024 |
|
||||
| **Total (batch=32)** | **~1.2 GB** |
|
||||
| **Total (batch=128)** | **~1.8 GB** |
|
||||
| **Total (batch=256)** | **~2.5 GB** |
|
||||
|
||||
### Disk Space
|
||||
|
||||
| Item | Size |
|
||||
| ---- | ---- |
|
||||
| TimesFM 2.5 safetensors | ~800 MB |
|
||||
| Hugging Face cache overhead | ~200 MB |
|
||||
| **Total download** | **~1 GB** |
|
||||
|
||||
Model weights are downloaded once from Hugging Face Hub and cached in
|
||||
`~/.cache/huggingface/` (or `$HF_HOME`).
|
||||
|
||||
## GPU Selection Guide
|
||||
|
||||
### NVIDIA GPUs (CUDA)
|
||||
|
||||
| GPU | VRAM | Recommended batch | Notes |
|
||||
| --- | ---- | ----------------- | ----- |
|
||||
| RTX 3060 | 12 GB | 64 | Good entry-level |
|
||||
| RTX 3090 / 4090 | 24 GB | 256 | Excellent for production |
|
||||
| A100 (40 GB) | 40 GB | 512 | Cloud/HPC |
|
||||
| A100 (80 GB) | 80 GB | 1024 | Cloud/HPC |
|
||||
| T4 | 16 GB | 128 | Cloud (Colab, AWS) |
|
||||
| V100 | 16–32 GB | 128–256 | Cloud |
|
||||
|
||||
### Apple Silicon (MPS)
|
||||
|
||||
| Chip | Unified Memory | Recommended batch | Notes |
|
||||
| ---- | -------------- | ----------------- | ----- |
|
||||
| M1 | 8–16 GB | 16–32 | Works, slower than CUDA |
|
||||
| M1 Pro/Max | 16–64 GB | 32–128 | Good performance |
|
||||
| M2/M3/M4 Pro/Max | 18–128 GB | 64–256 | Excellent |
|
||||
|
||||
### CPU Only
|
||||
|
||||
Works on any CPU with sufficient RAM. Expect 5–20× slower than GPU.
|
||||
|
||||
## Python and Package Requirements
|
||||
|
||||
| Requirement | Minimum | Recommended |
|
||||
| ----------- | ------- | ----------- |
|
||||
| Python | 3.10 | 3.12+ |
|
||||
| numpy | 1.26.4 | latest |
|
||||
| torch | 2.0.0 | latest |
|
||||
| huggingface_hub | 0.23.0 | latest |
|
||||
| safetensors | 0.5.3 | latest |
|
||||
|
||||
### Optional Dependencies
|
||||
|
||||
| Package | Purpose | Install |
|
||||
| ------- | ------- | ------- |
|
||||
| jax | Flax backend | `pip install jax[cuda]` |
|
||||
| flax | Flax backend | `pip install flax` |
|
||||
| scikit-learn | XReg covariates | `pip install scikit-learn` |
|
||||
|
||||
## Operating System Compatibility
|
||||
|
||||
| OS | Status | Notes |
|
||||
| -- | ------ | ----- |
|
||||
| Linux (Ubuntu 20.04+) | ✅ Fully supported | Best performance with CUDA |
|
||||
| macOS 13+ (Ventura) | ✅ Fully supported | MPS acceleration on Apple Silicon |
|
||||
| Windows 11 + WSL2 | ✅ Supported | Use WSL2 for best experience |
|
||||
| Windows (native) | ⚠️ Partial | PyTorch works, some edge cases |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Out of Memory (OOM)
|
||||
|
||||
```python
|
||||
# Reduce batch size
|
||||
model.compile(timesfm.ForecastConfig(
|
||||
per_core_batch_size=4, # Start very small
|
||||
max_context=512, # Reduce context
|
||||
...
|
||||
))
|
||||
|
||||
# Process in chunks
|
||||
for i in range(0, len(inputs), 50):
|
||||
chunk = inputs[i:i+50]
|
||||
p, q = model.forecast(horizon=H, inputs=chunk)
|
||||
```
|
||||
|
||||
### Slow Inference on CPU
|
||||
|
||||
```python
|
||||
# Ensure matmul precision is set
|
||||
import torch
|
||||
torch.set_float32_matmul_precision("high")
|
||||
|
||||
# Use smaller context
|
||||
model.compile(timesfm.ForecastConfig(
|
||||
max_context=256, # Shorter context = faster
|
||||
...
|
||||
))
|
||||
```
|
||||
|
||||
### Model Download Fails
|
||||
|
||||
```bash
|
||||
# Set a different cache directory
|
||||
export HF_HOME=/path/with/more/space
|
||||
|
||||
# Or download manually
|
||||
huggingface-cli download google/timesfm-2.5-200m-pytorch
|
||||
```
|
||||
Reference in New Issue
Block a user