---
title: "Scan Groups"
description: "Group models for synchronized execution with shared on-demand reads and writes"
source_url: https://ai-ops.com/docs/models/scan-groups
---

# Scan Groups

A **scan group** runs multiple AI models together on a shared schedule. All member models execute in the same inference cycle, and when on-demand mode is enabled, their device reads and writes are consolidated into a single batched request per device.

The primary benefit is efficiency on slow industrial networks. Instead of each model independently issuing its own on-demand read, the scan group computes the union of all tag IDs needed by every member model and requests them in one round-trip.

```text
Without scan groups — each model reads independently

Model A fires:  read tags A,B,C from Device 1   (round-trip 1)
Model B fires:  read tags B,D,E from Device 1   (round-trip 2)
Model C fires:  read tags A,F,G from Device 1   (round-trip 3)

With a scan group — one shared read

Scan group fires:
  Union of all tags: {A,B,C,D,E,F,G}
  Single read from Device 1                      (round-trip 1)
  All 3 models infer in parallel
  Single write of all outputs to Device 1
```

---

## How a Scan Group Executes

When the group's timer fires:

1. **Collect member models** — all enabled models in the group with valid bindings and model files
2. **Gather tag IDs** — union of all input and output tag IDs across every member model
3. **On-demand read** (if enabled) — single batched read of all gathered tags; wait for fresh values
4. **Run inference** — each member model executes concurrently
5. **On-demand write** (if enabled) — single batched write of all output tags
6. **Record timing** — per-cycle metrics (total time, read time, inference time, write time)

If the on-demand read times out (step 3), the entire cycle fails. No inference runs and no writes are triggered.

---

## Creating a Scan Group

1. Navigate to **Models > Scan Groups** in the sidebar
2. Click **Create Scan Group**
3. Enter a name, optional description, and scan rate
4. Toggle **On-Demand** if you want synchronized reads and writes
5. Click **Create**

The scan group starts disabled. Add models to it and enable it when ready.

### Adding Models

On the scan group's detail page, go to the **Models** tab, click **Add Models**, and select from ungrouped models. A model can only belong to one scan group at a time.

> [!WARNING] Memory-only models cannot join a scan group
> Models with the memory-only option store history in process memory and are incompatible with scan groups.

---

## Settings

### General

| Setting | Description | Default | Range |
|---------|-------------|---------|-------|
| **Name** | Unique name | — | Max 128 chars |
| **Description** | Optional notes | — | Max 256 chars |
| **Scan Rate** | How often the group runs (seconds) | 30s | 0.01–3,600s |

### Advanced

| Setting | Description | Default | Range |
|---------|-------------|---------|-------|
| **On-Demand** | Synchronized reads before inference, writes after | Off | — |
| **On-Demand Timeout** | Max wait for fresh device reads before cycle fails | 3s | 0.5–30s |
| **Log Level** | Verbosity of predict engine logs for this group | INFO | DEBUG / INFO / WARNING / ERROR |

> [!NOTE] Group settings override model settings
> When a model belongs to a scan group, the group's scan rate, on-demand, and on-demand timeout override the model's own values. The model's individual settings are disabled in the UI.

---

## On-Demand Mode in Scan Groups

When on-demand is enabled, the cycle coordinates with the datacollector:

- **Before inference** — the group collects every input and output tag ID across all member models and sends a single on-demand read request. The datacollector groups those tags by device and performs one network read per device.
- **After inference** — the group sends a single on-demand write request covering all output tags from models that succeeded.

### Shared Timeout

The timeout applies to the combined read covering all devices. Set it high enough for your slowest device. If your scan group includes a fast local device (100ms response) and a slow remote device (2–3s response), the timeout must accommodate the slowest.

### When On-Demand Adds the Most Value

- **Models share devices** — the shared read saves N-1 round-trips
- **Devices are slow** — OPC-UA over VLAN, Modbus TCP with large tag counts
- **Models write control outputs** — synchronized writes ensure all control actions use consistent predictions
- **Scan group rate is similar to device scan rate** — without on-demand, models may read data that's nearly a full cycle old

### When to Skip On-Demand

- Devices have fast scan rates relative to the group scan rate (cache is nearly always fresh)
- Models only read (no output writes)

For device-side on-demand settings (freshness, batch window), see [On-Demand Scanning](https://ai-ops.com/docs/devices/on-demand-scanning.md#on-demand-freshness).

---

## Scan Group vs. Individual On-Demand Models

| | Per-Model On-Demand | Scan Group On-Demand |
|--|---------------------|----------------------|
| **Reads per cycle** | One per model | One per device (shared) |
| **Inference timing** | Each model on its own schedule | All models together at group scan rate |
| **Write timing** | Each model writes after its own inference | All outputs written in a single request |
| **Best for** | Models with different scan rates | Models that share devices and need a synchronized cycle |

> [!TIP] Scan groups require a common scan rate
> A model's individual scan rate is not used while it belongs to a scan group. If your models need significantly different scan rates, keep them independent.

---

## Overscan

If a cycle takes longer than the scan rate, the next scheduled cycle is skipped and rescheduled. This is called **overscan** and typically happens when:

- The on-demand read is slow (device unresponsive, too many tags)
- Inference takes longer than expected (large models, many members)
- The scan rate is too aggressive

**To resolve:** increase the scan rate, reduce member count, increase the device's batch window, or investigate slow devices.

---

## Monitoring

### Overview Tab

Shows status, last scan time, model count, scan rate, scan progress ring, configuration summary, and recent events.

### Execution Tab

Per-cycle timing metrics from the last 24 hours:

| Metric | Description |
|--------|-------------|
| **Total Cycle Time** | End-to-end (read + inference + write) |
| **On-Demand Read Time** | Time waiting for fresh device reads |
| **Inference Time** | Time running all member models |
| **On-Demand Write Time** | Time writing outputs to devices |
| **Models Succeeded** | Count of models that completed without error |

### Error Codes

| Error | Meaning |
|-------|---------|
| **Overscan** | Previous cycle still running when next was scheduled |
| **On-Demand Read Failed** | Read request timed out or encountered an error |
| **On-Demand Write Failed** | Write request failed |
| **Generic Exception** | Unexpected error — check logs tab |

---

## Example: Five Models on a Shared OPC-UA Server

Five models all read from the same OPC-UA server that takes 800ms–1.2s to respond. Each model reads ~20 tags.

**Without a scan group:** Five on-demand requests fire within milliseconds of each other. Five sequential reads total 4–6 seconds.

**With a scan group:**

| Setting | Value |
|---------|-------|
| Scan rate | 60s |
| On-Demand | On |
| On-Demand Timeout | 10s |

The scan group collects all ~100 tag IDs, sends one read to the OPC-UA server (800ms–1.2s total), runs all five models in parallel, and writes outputs in a single request.

---

## What's Next

- [On-Demand Inference](https://ai-ops.com/docs/models/on-demand-inference.md) — how on-demand works at the individual model level
- [On-Demand Scanning](https://ai-ops.com/docs/devices/on-demand-scanning.md) — device-side freshness and batch window settings