|
| 1 | +--- |
| 2 | +title: "Granite Time Series" |
| 3 | +weight: 2 |
| 4 | +bookToc: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Granite Time Series |
| 8 | + |
| 9 | +Zerfoo supports IBM Granite Time Series foundation models for time-series |
| 10 | +inference. Three model families are available, each targeting different tasks. |
| 11 | + |
| 12 | +## Model Families |
| 13 | + |
| 14 | +| Model | Parameters | Tasks | Key Feature | |
| 15 | +|-------|-----------|-------|-------------| |
| 16 | +| **Granite TTM** | 1M-5M | Forecasting | Zero-shot and few-shot forecasting with channel mixing | |
| 17 | +| **Granite FlowState** | 2M-10M | Forecasting | Continuous forecasting across arbitrary timescales | |
| 18 | +| **Granite TSPulse** | 1M-5M | Anomaly detection, classification, imputation, embedding | Lightweight encoder for multi-task time-series analysis | |
| 19 | + |
| 20 | +## Supported Tasks |
| 21 | + |
| 22 | +- **Forecasting** -- predict future values from historical context (TTM, FlowState) |
| 23 | +- **Anomaly detection** -- identify outliers and anomalous patterns (TSPulse) |
| 24 | +- **Classification** -- classify time-series segments (TSPulse) |
| 25 | +- **Imputation** -- fill in missing values (TSPulse) |
| 26 | +- **Embedding** -- extract fixed-size representations for downstream tasks (TSPulse) |
| 27 | + |
| 28 | +## Converting Models |
| 29 | + |
| 30 | +Granite Time Series models are published on HuggingFace in SafeTensors format. |
| 31 | +Use the `granite2gguf` converter (part of `zonnx`) to produce GGUF files: |
| 32 | + |
| 33 | +```bash |
| 34 | +go install github.com/zerfoo/zonnx/cmd/granite2gguf@latest |
| 35 | + |
| 36 | +# Convert a TTM model |
| 37 | +granite2gguf \ |
| 38 | + --model ibm-granite/granite-timeseries-ttm-r2 \ |
| 39 | + --output granite-ttm-r2.gguf |
| 40 | + |
| 41 | +# Convert a FlowState model |
| 42 | +granite2gguf \ |
| 43 | + --model ibm-granite/granite-timeseries-flowstate \ |
| 44 | + --output granite-flowstate.gguf |
| 45 | + |
| 46 | +# Convert a TSPulse model |
| 47 | +granite2gguf \ |
| 48 | + --model ibm-granite/granite-timeseries-tspulse \ |
| 49 | + --output granite-tspulse.gguf |
| 50 | +``` |
| 51 | + |
| 52 | +The converter downloads weights from HuggingFace, maps the architecture to GGUF |
| 53 | +tensor names, and writes a self-contained `.gguf` file. |
| 54 | + |
| 55 | +## Running Inference |
| 56 | + |
| 57 | +### Forecasting (TTM) |
| 58 | + |
| 59 | +```go |
| 60 | +import "github.com/zerfoo/zerfoo/inference/timeseries" |
| 61 | + |
| 62 | +model, err := timeseries.LoadGGUF("granite-ttm-r2.gguf", engine) |
| 63 | +if err != nil { |
| 64 | + log.Fatal(err) |
| 65 | +} |
| 66 | +defer model.Close() |
| 67 | + |
| 68 | +// Input: [batch, channels, context_length] |
| 69 | +// Output: [batch, channels, forecast_length] |
| 70 | +input := tensor.New[float32](engine, []int{1, 3, 512}) |
| 71 | +// ... fill input with historical data ... |
| 72 | + |
| 73 | +forecast, err := model.Forecast(ctx, input) |
| 74 | +if err != nil { |
| 75 | + log.Fatal(err) |
| 76 | +} |
| 77 | +fmt.Println("forecast shape:", forecast.Shape()) |
| 78 | +``` |
| 79 | + |
| 80 | +### Anomaly Detection (TSPulse) |
| 81 | + |
| 82 | +```go |
| 83 | +model, err := timeseries.LoadGGUF("granite-tspulse.gguf", engine) |
| 84 | +if err != nil { |
| 85 | + log.Fatal(err) |
| 86 | +} |
| 87 | +defer model.Close() |
| 88 | + |
| 89 | +scores, err := model.DetectAnomalies(ctx, input) |
| 90 | +if err != nil { |
| 91 | + log.Fatal(err) |
| 92 | +} |
| 93 | +// scores: per-timestep anomaly scores |
| 94 | +``` |
| 95 | + |
| 96 | +### Embedding Extraction (TSPulse) |
| 97 | + |
| 98 | +```go |
| 99 | +embeddings, err := model.Embed(ctx, input) |
| 100 | +if err != nil { |
| 101 | + log.Fatal(err) |
| 102 | +} |
| 103 | +// embeddings: [batch, embed_dim] fixed-size representations |
| 104 | +``` |
| 105 | + |
| 106 | +## Architecture Details |
| 107 | + |
| 108 | +All three model families use a patch-based transformer encoder architecture: |
| 109 | + |
| 110 | +1. **Patching** -- the input time series is segmented into fixed-size patches |
| 111 | +2. **Channel mixing** -- multivariate channels are projected into a shared space |
| 112 | +3. **Transformer encoder** -- standard multi-head self-attention over patches |
| 113 | +4. **Task head** -- a linear projection head specific to the task (forecast, classify, reconstruct, embed) |
| 114 | + |
| 115 | +GGUF metadata stores the model family (`granite-ttm`, `granite-flowstate`, |
| 116 | +`granite-tspulse`), context length, forecast length, patch size, and number of |
| 117 | +channels. The inference runtime auto-configures based on these fields. |
| 118 | + |
| 119 | +## Model Sources |
| 120 | + |
| 121 | +| Model | HuggingFace Repo | |
| 122 | +|-------|-----------------| |
| 123 | +| Granite TTM R2 | [ibm-granite/granite-timeseries-ttm-r2](https://huggingface.co/ibm-granite/granite-timeseries-ttm-r2) | |
| 124 | +| Granite FlowState | [ibm-granite/granite-timeseries-flowstate](https://huggingface.co/ibm-granite/granite-timeseries-flowstate) | |
| 125 | +| Granite TSPulse | [ibm-granite/granite-timeseries-tspulse](https://huggingface.co/ibm-granite/granite-timeseries-tspulse) | |
0 commit comments