Example: YOLO video demo

mlops-edge-demo runs YOLO object detection on a video and reports the results to Central. Instead of running the agent (geo-mlops-edge) as a separate service, it embeds the SDK runtime (EdgeRuntime) inside the application. The source is public: https://github.com/osom8979/mlops-edge.

How it fits together#

What travels between the device and Central:

Prerequisites#

• uv. uv installs Python 3.12 to match the repository's .python-version.
• A display for the window. On a device without one, run with --no-show.
• (Optional) An NVIDIA GPU. Without one, inference runs on the CPU.
• Outbound HTTPS from the device to the Central API address, and a tenant ADMIN account to register the device (🔑 SettingsADMIN).

git clone https://github.com/osom8979/mlops-edge.git
cd mlops-edge
uv sync

On Linux this also installs a CUDA build of PyTorch and the GPU libraries (about 3 GB in total). If a slow line gives Failed to download distribution due to network timeout, run UV_HTTP_TIMEOUT=600 uv sync.

1. Create the device and the dataset#

2. Configure#

Change three places in the repository's edge.yaml.

central:
  base_url: https://mlops.example.com   # Central API address

device:
  id: edge-yolo-01                      # the device ID from step 1

collectors:
  - type: frames
    name: demo-frames
    priority: 30                        # lower than inference results (50): results go first on a narrow line
    options:
      every_n_frames: 30                # one frame per second for a 30 fps video
      dataset_id: "ds-0123456789ab"     # the dataset ID from step 1; empty means Collected data
      labels: true                      # send LabelMe pre-labels too
      label_conf: 0.5                   # only detections at or above this confidence become pre-labels

Keep the token in .env, not in the config file.

cp .env.example .env
# put in .env: GEO_EDGE_CENTRAL__TOKEN=<device-token>

• Precedence is environment variables > .env > edge.yaml > defaults, the same as the SDK. See Configuration reference for every key.
• The demo's edge.yaml sets the heartbeat to 10 seconds (default 30) so the screens update quickly.
• It runs without a token too. Results only build up in the local queue (data/edge/) and are sent once you add the token and run again.

3. Run#

uv run mlops-edge-demo

With no argument it downloads the default video (17 seconds of city driving) once into cache/videos/ and plays it in a loop. The yolo26n.pt weights (COCO-pretrained) are downloaded into cache/weights/. Press q or ESC in the window to quit.

The status overlay at the top left of the window:

Other videos and modes:

uv run mlops-edge-demo ./line-camera.mp4            # local file (opened directly, no download)
uv run mlops-edge-demo rtsp://192.0.2.10/stream     # RTSP stream
uv run mlops-edge-demo --no-show                    # device without a display; logs the status every 5 seconds

The runtime inside the demo opens the local API (127.0.0.1:8600), so the SDK CLI can query it (CLI).

uv run geo-mlops-edge status --config edge.yaml          # link, backlog, models, attention items
uv run geo-mlops-edge queue --config edge.yaml --limit 5

If a geo-mlops-edge agent on the same PC already holds port 8600, the demo only turns off its local API (local API disabled warning) and keeps talking to Central.

4. Check on Central#

• File names are <video name>_<6-digit frame number>.jpg. For a video downloaded from a URL, the video name is the cache file name (a 12-character URL hash + the original name), for example c5144a2b5077-kitti-inference-vid_000420.jpg.
• Pre-labels are the current model's predictions. Training on them as they are teaches the model its own mistakes, so a person has to review them before training.
• Looping or restarting does not resend frames that were already queued. The record is data/edge/collectors/demo-frames.seen.

5. Swap in a trained model#

Send a model trained on the collected frames back to this device.

• Only YOLO-framework models are shown in the window. A model of another framework only logs a warning, and playback continues with the current model.
• A cached model is activated again on the next run. See Models and inference for the activation rules.
• Approval (promotion to Production) and the deployment screens do not send a model to the device. The three ways to send one are the pull_model command, the device CLI and the local API.

Restart and exit#

• Quitting with q, ESC, Ctrl-C or SIGTERM lets the runtime settle the queue and close its database before exiting.
• Restart (재시작) on the device detail page, or a restart command, makes the demo exit with code 3. Run it under a supervisor such as systemd to have it start again (Deploy, Commands, policy and retention).

Code layout#

The key to embedding the runtime in an application is separate threads. The OpenCV window wants the main thread and EdgeRuntime needs an asyncio event loop, so the runtime runs on a loop in its own thread and the video loop hands work over with asyncio.run_coroutine_threadsafe without waiting.

# edge.py, condensed. Runs on the runtime thread
runtime = EdgeRuntime(settings)
runtime.events.add_listener(on_event)   # notified when pull_model activates a model
await runtime.start()                   # registration, heartbeat, commands, uploader, collectors
await serve(runtime, settings, stop)    # local API (geo_mlops_sdk.edge.daemon.serve)

# On the video loop (main thread): encode only the frames to collect, hand them to the frames collector
if frames.wants(source, index, seekable=True):
    ok, jpeg = cv2.imencode(".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, 90])
    asyncio.run_coroutine_threadsafe(
        frames.collect(source, index, jpeg.tobytes(), output, model=model_ref), loop
    )

See Data collectors for the frames collector API and Models and inference for the inference output format (InferenceOutput).