---
title: "Model Inference Requirements"
description: "How Koios builds input tensors and what your model file needs to look like"
source_url: https://ai-ops.com/docs/models/inference-requirements
---

# Model Inference Requirements

This page explains how Koios prepares data for your model and what shape your exported model file needs to be. Koios is an inference engine — models must be [trained externally](https://ai-ops.com/docs/models/training-a-model.md) and exported as ONNX or TFLite.

## Input Tensor Shape

Koios supports two input shapes — pick the one that matches how your model was trained:

| Shape | Rank | Label in UI | Use Case |
|-------|------|------|----------|
| `[1, num_inputs]` | 2 | **Flat** (depth 1) | Single-step models — RL policies, simple regressors, classifiers reading the *current* sensor snapshot only |
| `[1, input_depth, num_inputs]` | 3 | **Time-series** (depth > 1) | Models that consume a window of recent history (forecasters, LSTMs, transformers, time-series classifiers) |

Koios detects the shape from the model graph at upload time and validates it against the model's embedded metadata. Model list and detail pages label each model as "5 inputs, depth 1" (flat) or "5 inputs, depth 6" (time-series) so you can tell them apart at a glance.

In both shapes:

- **Batch size is always 1.**
- **`num_inputs`** is the number of input features, one per input binding.
- **`input_depth`** (rank-3 only) is the number of historical time steps Koios queries per scan.

### Flat models (rank-2)

A flat model reads three input tags as a single row:

```text
                  Binding 1        Binding 2        Binding 3
                Supply Temp °C   Return Temp °C    Fan Speed %
                (normalized)     (normalized)      (normalized)
              ┌─────────────────────────────────────────────────┐
  current     │     0.47             0.60             0.83      │
              └─────────────────────────────────────────────────┘
Shape: [1, 3]   No time dimension — just the most recent sample per binding.
```

### Time-series models (rank-3)

A time-series model reading the same three tags with input depth 6 and sample rate 10s:

```text
                  Binding 1        Binding 2        Binding 3
                Supply Temp °C   Return Temp °C    Fan Speed %
                (normalized)     (normalized)      (normalized)
              ┌─────────────────────────────────────────────────┐
  t₀ (oldest) │     0.42             0.65             0.80      │
  t₁ (-40s)   │     0.43             0.64             0.80      │
  t₂ (-30s)   │     0.45             0.63             0.81      │
  t₃ (-20s)   │     0.44             0.62             0.79      │
  t₄ (-10s)   │     0.46             0.61             0.82      │
  t₅ (newest) │     0.47             0.60             0.83      │
              └─────────────────────────────────────────────────┘
Shape: [1, 6, 3]   Time flows top → bottom. Columns ordered by binding order.
```

### Key Rules

- **Batch size is always 1**
- **Time flows forward** in rank-3 — row 0 is oldest, last row is newest
- **Columns match binding order** — binding 1 is column 0, binding 2 is column 1, etc.
- **Values are normalized** (unless using "None" normalization)
- **Input shape is fixed** — read from your model file and cannot be changed after upload

---

## Data Preparation Pipeline

On every scan, Koios:

1. **Query** — fetch historical data for each input tag covering `input_depth × sample_rate` seconds
2. **Interpolate** — resample to an evenly-spaced time grid using PCHIP interpolation (monotone cubic, no artificial peaks)
3. **Normalize** — scale each value using the binding's normalization type and source
4. **Assemble** — stack columns by binding order, wrap in batch dimension → `[1, input_depth, num_inputs]`

> [!NOTE] At least 2 data points required
> Interpolation needs at least 2 raw data points. If a tag is new, use **Initialize History** on the model overview page.

---

## Output Tensor Shape

Three output shapes are supported:

| Shape | Use Case |
|-------|----------|
| `[]` or `[1]` | Single prediction → output binding 1 |
| `[1, num_outputs]` | One prediction per output binding |
| `[1, output_depth, num_outputs]` | Multi-step forecast — each binding's **output index** selects which time step to use |

---

## Model File Requirements

| Format | Extension | Runtime |
|--------|-----------|---------|
| **ONNX** | `.onnx` | ONNX Runtime (CPU) |
| **TFLite** | `.tflite` | TFLite Runtime (CPU) |

### What Koios Reads from Your File

| Property | Used For |
|----------|----------|
| **num_inputs** | Number of input bindings to create |
| **num_outputs** | Number of output bindings to create |
| **input_depth** | Historical samples queried per scan |
| **output_depth** | Future time steps the model predicts |

### Shape Convention

Koios accepts two input shapes:

- **Flat:** `[batch_size, features]` — no time dimension; used by single-step models (RL policies, regressors, classifiers)
- **Time-series:** `[batch_size, time_steps, features]` — time/depth dimension must be static
- **Output:** `[batch, time, features]`, `[batch, features]`, or scalar
- **Data type:** float32
- **ONNX:** batch dimension can be dynamic; time dimension must be static
- **TFLite:** input must have at least 2 dimensions

> [!WARNING] Test your model file before uploading
> Run a quick inference locally with a dummy input of the expected shape before uploading to Koios.

---

## Quick Reference

| Concept | Value |
|---------|-------|
| Flat input shape | `[1, num_inputs]` |
| Time-series input shape | `[1, input_depth, num_inputs]` |
| Time direction | Oldest first → newest last (rank-3 only) |
| Interpolation | PCHIP (monotone cubic Hermite) |
| Min data points | 2 per input tag (rank-3); 1 (rank-2) |
| Data type | float32 |
| Batch size | Always 1 |
| Binding order | 1-based (binding 1 → column 0) |
| Output index | 1-based (step 1 → array index 0) |