# How to Use YOLO Models for Real-Time Object Detection with ailia-models

> Easily implement real-time object detection using YOLO models with ailia-models. Leverage GPU acceleration and automatic model downloads for fast image, video, and webcam analysis.

- Repository: [axinc-ai/ailia-models](https://github.com/axinc-ai/ailia-models)
- Tags: tutorial
- Published: 2026-02-25

---

**The ailia-models repository provides ready-to-run implementations of YOLO families (YOLOv5, YOLOv8, YOLOX, etc.) using the ailia SDK, enabling real-time object detection on images, videos, and webcam streams with automatic model downloading and GPU acceleration.**

The **axinc-ai/ailia-models** repository offers production-ready implementations for real-time object detection using popular YOLO architectures. Whether you need to process static images, video files, or live webcam feeds, these scripts handle the entire pipeline from model downloading to visualization. This guide explains how to use YOLO models for real-time object detection by leveraging the repository's common architecture built on the ailia SDK.

## The YOLO Inference Pipeline

All YOLO implementations in the repository follow a standardized nine-step execution flow. The process begins in scripts like [`object_detection/yolov5/yolov5.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolov5/yolov5.py) with `get_base_parser()`, which configures model names, detection thresholds, and input sources.

Model initialization uses `check_and_download_models(WEIGHT_PATH, MODEL_PATH, REMOTE_PATH)` to fetch ONNX files automatically, followed by `ailia.Net(MODEL_PATH, WEIGHT_PATH, env_id=args.env_id)` to instantiate the inference engine.

Preprocessing varies by variant: `yolov5_utils.letterbox_convert` (line 86) handles YOLOv5 resizing, `yolox_utils.preproc` (line 9) manages YOLOX transformation, and `yolov8.preprocess` (line 46) prepares YOLOv8 inputs. Inference executes through `detector.predict([img])` in YOLOv5 (line 42) or `net.predict([img])` in YOLOv8 (line 50).

Post-processing applies variant-specific NMS implementations: `yolov5_utils.post_processing` (line 86), `yolox_utils.predictions_to_object` (line 38), or `yolov8.post_processing` (line 78). These convert raw tensors to `ailia.DetectorObject` instances containing normalized bounding boxes and class probabilities. Visualization uses `plot_results(detect_object, org_img, COCO_CATEGORY)` to render outputs. For video streams, `recognize_from_video` (line 73 in yolov5.py) loops these steps continuously using `webcamera_utils.get_capture` for frame acquisition.

## Real-Time Object Detection with YOLOv5

YOLOv5 implementations support single images, video files, and webcam streams through a unified CLI interface.

Run detection on a static image:

```bash
python object_detection/yolov5/yolov5.py \
    -a yolov5s \
    -i input.jpg \
    -o result.png \
    -th 0.3 \
    -iou 0.45

```

The `-a` flag selects the architecture (yolov5s, yolov5m, etc.), while `-th` and `-iou` control confidence and NMS thresholds. The script automatically downloads `yolov5s.onnx` from remote storage if absent.

For video processing, the `recognize_from_video` function (line 73 in [`yolov5.py`](https://github.com/axinc-ai/ailia-models/blob/main/yolov5.py)) manages the capture loop:

```bash
python object_detection/yolov5/yolov5.py \
    -a yolov5s \
    -v input_video.mp4 \
    -o output_video.mp4 \
    -th 0.25 \
    -iou 0.45

```

This leverages `webcamera_utils.get_capture` for input and OpenCV's `VideoWriter` for encoded output.

## Webcam Detection Using YOLOX

YOLOX utilizes the ailia Detector API for optimized real-time performance on edge devices. The implementation in [`object_detection/yolox/yolox.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolox/yolox.py) uses `ailia.Detector` instead of raw network inference.

```python
import cv2
import ailia
from yolox import yolox
from yolox_utils import preproc, plot_results

# Initialize detector with YOLOX-nano

detector = ailia.Detector(
    'yolox_nano.onnx.prototxt',
    'yolox_nano.onnx',
    len(yolox.COCO_CATEGORY),
    format=ailia.NETWORK_IMAGE_FORMAT_BGR,
    channel=ailia.NETWORK_IMAGE_CHANNEL_FIRST,
    range=ailia.NETWORK_IMAGE_RANGE_U_INT8,
    algorithm=ailia.DETECTOR_ALGORITHM_YOLOX,
)

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # Pre-process (line 9 in yolox_utils.py)

    img, ratio = preproc(frame, (416, 416))
    
    # Inference

    detector.compute(frame, 0.3, 0.45)
    
    # Visualize (line 54 in yolov5.py/yolox.py)

    result = plot_results(detector, frame, yolox.COCO_CATEGORY)
    cv2.imshow('YOLOX-nano', result)
    
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

```

## Programmatic YOLOv8 Integration

YOLOv8 implementations in [`object_detection/yolov8/yolov8.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolov8/yolov8.py) provide flexible model selection with ONNX Runtime fallback support.

```python
import cv2
import ailia
from yolov8 import load_image, preprocess, post_processing, convert_to_detector_object, plot_results

# Load model (downloads automatically if missing)

net = ailia.Net('yolov8n.onnx.prototxt', 'yolov8n.onnx')

# Prepare input

img = load_image('demo.jpg')
img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)

# Pre-process (line 46)

input_img = preprocess(img, input_shape=(640, 640))

# Inference (line 50)

output = net.predict([input_img])

# Post-process (line 78)

preds = post_processing(output, conf_thres=0.25, iou_thres=0.45)

# Convert to DetectorObject (line 22)

det_objs = convert_to_detector_object(preds, img.shape[1], img.shape[0])

# Draw and save

out = plot_results(det_objs, img, COCO_CATEGORY)
cv2.imwrite('yolov8_result.png', out)

```

## Key Implementation Files

Understanding the source structure enables custom modifications and debugging:

- [`object_detection/yolov5/yolov5.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolov5/yolov5.py) – Main CLI entry point with `get_base_parser()` and `recognize_from_video()` (line 73)
- [`object_detection/yolov5/yolov5_utils.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolov5/yolov5_utils.py) – `letterbox_convert` (line 86), `post_processing`, and NMS implementations
- [`object_detection/yolox/yolox.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolox/yolox.py) – YOLOX-specific CLI using `ailia.Detector` API
- [`object_detection/yolox/yolox_utils.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolox/yolox_utils.py) – `preproc` (line 9) and `predictions_to_object` (line 38)
- [`object_detection/yolov8/yolov8.py`](https://github.com/axinc-ai/ailia-models/blob/main/object_detection/yolov8/yolov8.py) – YOLOv8 inference with `preprocess` (line 46), `post_processing` (line 78), and `convert_to_detector_object` (line 22)
- [`util/detector_utils.py`](https://github.com/axinc-ai/ailia-models/blob/main/util/detector_utils.py) – Shared visualization via `plot_results` and image loading utilities
- [`util/webcamera_utils.py`](https://github.com/axinc-ai/ailia-models/blob/main/util/webcamera_utils.py) – Video capture and `VideoWriter` management
- [`util/model_utils.py`](https://github.com/axinc-ai/ailia-models/blob/main/util/model_utils.py) – Automatic model downloading via `check_and_download_models`

## Summary

- The **ailia-models** repository provides unified YOLO implementations (v5, v8, X) with consistent preprocessing, inference, and post-processing patterns
- **Model initialization** uses `ailia.Net` or `ailia.Detector` with automatic downloading via `check_and_download_models`
- **Preprocessing** varies by variant: `letterbox_convert` (YOLOv5), `preproc` (YOLOX), and `preprocess` (YOLOv8)
- **Post-processing** includes variant-specific NMS implementations that output standardized `ailia.DetectorObject` instances
- **Real-time processing** relies on `recognize_from_video` functions and `webcamera_utils.get_capture` for frame-by-frame analysis

## Frequently Asked Questions

### What YOLO variants are supported in ailia-models?

The repository supports YOLOv5 (s, m, l, x), YOLOv8 (n, s, m, l, x), YOLOX (nano, tiny, s, m, l, x), and YOLOv4. Each variant offers trade-offs between speed and accuracy, with nano and n variants optimized for edge devices and real-time webcam processing.

### How does the ailia SDK achieve real-time performance?

The ailia SDK utilizes Vulkan and Metal GPU acceleration on desktop platforms and optimized inference engines for edge devices like Jetson and Raspberry Pi. Single-stage detection architectures in YOLO models perform bounding box regression and classification in one forward pass, enabling processing rates exceeding 30 FPS on modern CPUs and 100+ FPS on GPUs for lightweight variants like YOLOv5-nano or YOLOv8-n.

### Can I run these models without GPU acceleration?

Yes. The scripts accept an `env_id` parameter (set via `ailia.Net` initialization) that allows CPU-only inference. While frame rates decrease without GPU acceleration, lightweight variants like YOLOX-nano or YOLOv8-n maintain usable performance on modern CPUs for real-time applications.

### How do I adjust detection sensitivity and reduce false positives?

Modify the confidence threshold (`-th` or `threshold` parameter, typically 0.25-0.5) and NMS IoU threshold (`-iou` or `iou_thres`, typically 0.45-0.65) through CLI arguments or function parameters. Higher confidence thresholds filter low-probability detections, while adjusting the IoU threshold controls how aggressively overlapping boxes are suppressed during post-processing.