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.

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:

Collect member models: all enabled models in the group with valid bindings and model files
Gather tag IDs: union of all input and output tag IDs across every member model
On-demand read (if enabled): single batched read of all gathered tags; wait for fresh values
Run inference: each member model executes concurrently
On-demand write (if enabled): single batched write of all output tags
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

Click Scan Groups in the sidebar, under AI Models
Click Add Scan Group
Enter a name, optional description, and scan rate
Toggle On-Demand if you want synchronized reads and writes
Click Create Scan Group

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.

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

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.

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

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 for the group. Switch between Live Polling, which follows the group as it runs, and 24h History.

Four cards sit above the chart:

Card	Description
Set Scan Rate	The group's configured scan rate
Avg Cycle Time	Average end-to-end cycle time (read + inference + write + overhead) across the cycles currently loaded
Latest Inference Time	Time the most recent cycle spent running all member models
Models Succeeded	Models that completed without error in the most recent cycle, out of the models in that cycle

Below the cards, Live Execution Timeline stacks each recent cycle into Inference Time, On-Demand Read, On-Demand Write, and Overhead, so you can see which phase dominates. Historical Performance plots Average Cycle Time with Min Cycle Time and Max Cycle Time over the same 24 hours.

Logs Tab

Streams the group's predict engine log. The log-level selector above the log sets the group's verbosity (Debug, Info, Warning, Error) — it is a live setting, not part of the group's saved configuration.

Error Codes

Code	Meaning	What to do
0 — None	Running normally	Nothing
2 — On-Demand Read Failed	The group's shared on-demand read timed out or errored	Trace it to the underlying device or tag — see Troubleshoot a Connection

2 — On-Demand Read Failed is the only error code a scan group reports. A group that cannot keep up with its scan rate is not an error code: it stays Running with code 0 and Koios attaches a warning message to the group's status — for example Scan group execution (14.2s) exceeded scan rate (10s) with 32 models. You see that as the amber running-with-warning state, in the group's status tooltip, and in the group's log.

Overscan will not show up in an error-code filter

Because an overscanning group keeps error code 0, filtering or searching the scan group list by error code will not find it. Slow the scan rate or move members to another group. See Service Health & Resource Alarms.

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: how on-demand works at the individual model level
On-Demand Scanning: device-side freshness and batch window settings

On-Demand Inference Importing & Exporting Models