---
title: "Assigning Bindings"
description: "Bind model inputs and outputs to tags for real-time AI inference"
source_url: https://ai-ops.com/docs/models/assigning-bindings
---

# Assigning Bindings

## What Are Bindings?

Bindings connect your AI model to live data. Every model has **inputs** (data the model reads) and **outputs** (predictions the model writes). Bindings map each input and output to a **tag** — a live data point collected from a connected device.

Without bindings, the model has no data to process and nowhere to write its results. Once bindings are assigned and configured, the Predict Engine automatically feeds live tag values into the model at each scan cycle and writes the model's predictions back to the output tags.

```text
  Tags (live data)          Model               Tags (predictions)
┌──────────────────┐    ┌───────────┐    ┌──────────────────────┐
│ Temperature  ────│───►│           │───►│  Predicted Failure   │
│ Pressure     ────│───►│   ONNX    │───►│  Recommended Action  │
│ Flow Rate    ────│───►│   Model   │    └──────────────────────┘
│ Vibration    ────│───►│           │
└──────────────────┘    └───────────┘
     Input Bindings                        Output Bindings
```

### How the Predict Engine Uses Bindings

At each scan cycle, the Predict Engine:

1. **Reads** the recent history of each input tag (the number of samples depends on the model's `sample_rate` configuration)
2. **Calibrates** each value by applying the binding's gain and bias (no-op when both are at defaults)
3. **Normalizes** each value according to the binding's scaling configuration (e.g., Min-Max scales to 0–1)
4. **Runs inference** — feeds the normalized input history through the model
5. **Denormalizes** each output back to real-world units
6. **Calibrates inversely** on outputs to convert from model space back to engineering units
7. **Writes** the result to each output tag
8. **Validates** that input values are within expected ranges (failure detection)

This happens automatically and continuously once the model is enabled.

---

## The Bindings Tab

Navigate to a model's detail page and select the **Bindings** tab. The tab displays a two-column layout:

- **Left column** — Input bindings (data the model reads)
- **Right column** — Output bindings (predictions the model writes)

Each binding appears as a card showing:

- **Binding order number** — the position in the model's input or output array
- **Tag name** — the assigned tag, or "Unassigned" if no tag is linked
- **Live values** — for inputs, the raw tag value and its normalized model input; for outputs, the model's raw output and the denormalized tag value
- **Failure bounds** — the expected value range for failure detection
- **Status indicator** — running, stopped, error, or unassigned

> [!NOTE] Bindings are created automatically
> When you upload a model file, Koios reads the model's input and output dimensions and creates the corresponding bindings automatically. You don't create bindings manually — you assign tags to them.

---

## Assigning a Tag

Click any binding card to open its configuration drawer. The **Tag** section at the top contains a tag picker where you assign which tag feeds data into (or receives data from) this binding.

1. Click the binding card to open the drawer
2. In the **Tag** section, use the tag picker to search and select a tag
3. The binding saves automatically when you close the drawer

For **output bindings**, the tag picker only shows writable tags — tags configured with output usage that can accept written values.

> [!WARNING] Assign all input bindings
> A warning appears on the Bindings tab if any input bindings are unassigned. The model cannot run inference correctly with missing inputs.

### Training Metadata

If the model file includes training metadata (embedded via `koios-model-utils`), each binding may show a **"From training"** info box. This displays the binding's original name and description from training, helping you match bindings to the correct tags. For example, a binding named `temperature_sensor_1` tells you which physical measurement it expects.

---

## Scaling (Normalization)

Most ML models expect inputs in a specific numeric range (e.g., 0 to 1, or -1 to 1). Raw tag values like temperature (20–200) or pressure (0–500) need to be scaled before the model can process them. The **Scaling** section configures this transformation.

### Scaling Methods

| Method | Formula | Output Range | Use Case |
|--------|---------|--------------|----------|
| **None** | No transformation | Raw values | Model trained on raw data |
| **Min-Max** | (value - min) / (max - min) | 0 to 1 | Most common for neural networks |
| **Symmetric** | 2 * (value - min) / (max - min) - 1 | -1 to 1 | Models using tanh activation |
| **Z-Score** | (value - mean) / std | Centered at 0 | Standardized features |

### Parameter Source

When using Min-Max or Symmetric scaling, you choose where the min/max parameters come from:

- **Tag Range** — Uses the `rangeMin` and `rangeMax` configured on the assigned tag. This is convenient when your tag ranges already match the training data ranges.
- **Custom** — You provide explicit minimum and maximum values. Use this when the tag range doesn't match what the model was trained on.

> [!TIP] Z-Score always uses Custom
> Z-Score normalization requires a mean and standard deviation, which cannot be derived from a tag's range. When you select Z-Score, the source is automatically set to Custom and you enter the mean and standard deviation values.

### Clamp Output

For **output bindings**, an optional **Clamp Output** toggle constrains the model's prediction to the binding's configured range. When enabled, if the model produces a value outside the normalization bounds, it is clamped to the minimum or maximum before being written to the tag. This prevents unexpected extreme values from reaching the output device.

### Output Index

For models that forecast multiple future time steps (output depth > 1), each output binding has an **Output Index** setting (1-based) that selects which time step to use as its prediction. For example, if a model outputs 12 future steps and you only care about step 12, set the output index to 12. See [Model Inference Requirements](https://ai-ops.com/docs/models/inference-requirements.md#output-tensor-shape) for details on multi-step output shapes.

---

## Calibration (Gain & Bias)

Every binding can apply a linear transform on top of the raw value. The Scaling tab exposes two fields:

| Field | Default | Description |
|---|---|---|
| **Gain** | `1.0` | Multiplier applied to the value. Cannot be zero. |
| **Bias** | `0.0` | Offset added after the gain. |

Use calibration to correct sensor drift, convert engineering units, or fine-tune a model's response — without retraining or re-uploading the model file. Both values are non-nullable and default to the identity transform, so existing bindings see no change after upgrading to v1.1.0.

### How Calibration Is Applied

**Input bindings:**

```text
calibrated_value = (raw_tag_value × gain) + bias
```

Calibration runs **before** range checks, rate-of-change detection, and normalization, so every downstream check operates in the calibrated value space. If your gain or bias is non-default, the normalization source is automatically set to **Custom** — the tag's native range no longer matches what the model sees.

**Output bindings (inverse):**

```text
tag_value = (denormalized_model_output − bias) / gain
```

Calibration is the final step before the value is written back to the tag.

> [!TIP] When to use calibration vs normalization
> Use **normalization** to match the value range the model was trained on. Use **calibration** for physical-world adjustments — a sensor that reads 2°C low, a transducer with a 0.98 scale factor, a setpoint that needs to be offset by 5 units. The two are independent and compose cleanly.

---

## Failure Detection

Failure detection monitors whether input values fall outside expected bounds. If an input is out of range, it may indicate a sensor fault, a disconnected device, or abnormal process conditions — any of which could cause the model to produce unreliable predictions.

### Failure Range Mode

| Mode | Behavior |
|------|----------|
| **Disabled** | No range checking performed |
| **Normalization Range** | Uses the same min/max bounds configured in the Scaling section |
| **Custom** | You provide separate minimum and maximum failure bounds |

### Failure Evaluation

When the model uses interpolated samples (multiple data points per scan), this setting controls how samples are evaluated against the failure bounds:

| Evaluation | Behavior |
|------------|----------|
| **Any** | Fails if any single sample is out of range |
| **Latest** | Only checks the most recent sample |
| **Average** | Checks the average of all samples |

### Failure Debounce

The debounce count prevents transient spikes from triggering failures. Set the number of **consecutive** scans that must fail before the binding enters a failure state. A value of 0 means failure triggers immediately on the first out-of-range scan.

### Recovery Hysteresis

Once a binding enters a failure state, it doesn't recover the instant values return within bounds. The hysteresis percentage defines how far **inside** the range values must return before the binding recovers. This prevents rapid toggling between failed and healthy states when values hover near the boundary.

For example, with a range of 0–100 and 5% hysteresis, a failed binding only recovers when the value drops below 95 (or rises above 5).

---

## Rate of Change Detection

Rate of Change (ROC) detection flags values that are changing too quickly, which can indicate equipment malfunction, sudden process upsets, or noisy sensors even when the value itself is within the normal range.

| Setting | Description |
|---------|-------------|
| **ROC Enabled** | Toggle rate-of-change detection on or off |
| **ROC Threshold** | Maximum allowed change per minute |
| **Threshold Mode** | Express the threshold in raw units per minute or as a percentage of the normalization range per minute |
| **Direction** | Detect rising changes, falling changes, or both |
| **ROC Window** | Time window (in seconds) over which the rate of change is calculated |

---

## Stale Data Detection

The **Allowed Missed Samples** setting controls how many consecutive scan cycles a tag can miss (produce no new data) before the binding is flagged as stale. This protects against situations where a device disconnects or a tag stops updating — the model would otherwise keep using the last known value indefinitely.

---

## Binding Name and Description

Each binding has an editable **name** and **description** visible at the top of the configuration drawer. Click either field to edit it inline. If the model file included training metadata, the name and description are auto-populated from the metadata.

These fields are for your reference only — they help you identify which physical measurement or prediction each binding represents. They do not affect how the Predict Engine processes the binding.

---

## Typical Workflow

1. **Upload a model file** — bindings are created automatically from the model's input/output dimensions
2. **Review training metadata** — if present, use the binding names to understand what each input/output expects
3. **Assign tags** — click each binding and select the appropriate tag
4. **Configure scaling** — set the normalization method and parameters to match how the model was trained
5. **Set failure detection** — define acceptable ranges to catch sensor faults or abnormal data
6. **Enable the model** — once all bindings are assigned and configured, enable the model to start inference

> [!TIP] Match your training configuration
> The scaling method and parameters must match how the model was trained. If the model was trained with Min-Max normalization using a range of 0–500 for a pressure input, configure that binding with Min-Max scaling and Custom source with minimum 0 and maximum 500.

---

## What's Next

- [Configuring a Model](https://ai-ops.com/docs/models/configuring-a-model.md) — scan rate, sample rate, on-demand, and other model settings
- [On-Demand Inference](https://ai-ops.com/docs/models/on-demand-inference.md) — synchronize inference with fresh device data
- [Monitoring a Model](https://ai-ops.com/docs/models/enabling-a-model.md) — live values, diagnostics, execution performance, and trends
- [Managing Model Files](https://ai-ops.com/docs/models/model-files.md#embedded-metadata) — embedded metadata that auto-populates binding settings