qai-cli/examples/meter-detection/README.md

YOLO26 Electric Meter Detection Example

This example trains a YOLO26 object detection model on the Roboflow Universe electric meter dataset using the existing qc-cli SageMaker training flow.

The workflow is intentionally command driven. Run each step yourself so you can inspect the dataset, update config.yaml, and decide when to submit the SageMaker job.

Dataset:

https://universe.roboflow.com/kemals-workspace-kbc8l/electric-meter-detection-o4tfi/dataset/1

Prerequisites

• Install or sync the project dependencies: uv sync
• The virtual environment is activated.
• AWS credentials configured for the profile in config.yaml
• Infrastructure already deployed with qc-cli infra setup

1. Download The Dataset

Register or sign in to Roboflow, then open the dataset page:

https://universe.roboflow.com/kemals-workspace-kbc8l/electric-meter-detection-o4tfi/dataset/1

Download the dataset in YOLOv26 format from the Roboflow UI, then extract the downloaded archive into:

examples/meter-detection/data/electric-meter-detection

The data.yaml file should be directly under that folder:

examples/meter-detection/data/electric-meter-detection/data.yaml

Do not move data.yaml into the train/ split folder.

After extracting, confirm the dataset has a YOLO data file and image splits:

find examples/meter-detection/data/electric-meter-detection -maxdepth 2 -type d | sort
find examples/meter-detection/data/electric-meter-detection -name data.yaml -print

Open examples/meter-detection/data/electric-meter-detection/data.yaml and make sure the split paths are relative to that folder:

path: .
train: train/images
val: valid/images
test: test/images

If your downloaded dataset does not include a test/ folder, remove the test: line.

The expected layout is similar to:

examples/meter-detection/data/electric-meter-detection/
  data.yaml
  train/
  valid/
  test/

2. Configure SageMaker Training

Update config.yaml so the training section points at this example's source directory:

sagemaker:
  training:
    image_uri: 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:2.6-cpu-py312-ubuntu22.04-sagemaker-v1
    instance_type: ml.g4dn.xlarge
    instance_count: 1
    source_dir: examples/meter-detection/source
    entry_point: train.py
    hyperparameters:
      model: yolo26n.pt
      epochs: 25
      imgsz: 640
      batch: 16
      workers: 2

Use yolo26n.pt for a lightweight first YOLO26 run. If those weights are unavailable in the installed Ultralytics package, use yolo11n.pt as the established fallback:

      model: yolo11n.pt

The source/requirements.txt file is installed by the SageMaker PyTorch container before running train.py.

For a CPU smoke test, use a CPU instance and reduce the workload:

sagemaker:
  training:
    image_uri: 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:2.6-cpu-py312-ubuntu22.04-sagemaker-v1
    instance_type: ml.m4.xlarge
    instance_count: 1
    source_dir: examples/meter-detection/source
    entry_point: train.py
    hyperparameters:
      model: yolo26n.pt
      epochs: 1
      imgsz: 320
      batch: 4
      workers: 2

3. Check Infrastructure

Confirm the CLI can see the configured SageMaker role and S3 bucket:

qc-cli infra status --config config.yaml

4. Upload The Dataset

Upload the downloaded Roboflow dataset to the s3.data_prefix configured in config.yaml:

qc-cli upload examples/meter-detection/data/electric-meter-detection

Directory uploads preserve paths relative to the uploaded directory, so SageMaker receives the dataset root with data.yaml plus the split directories.

In SageMaker, this uploaded dataset root is mounted at /opt/ml/input/data/train. That train path is the SageMaker channel name, not the YOLO train/ split folder.

5. Start Training

Submit the SageMaker training job:

qc-cli train start

The command prints the submitted SageMaker job name. Check progress with:

qc-cli train status

Or pass the job name explicitly:

qc-cli train status qc-cli-YYYYMMDD-HHMMSS

Outputs

When the job completes, SageMaker packages the files written under /opt/ml/model into model.tar.gz.

This example writes:

best.pt
model.onnx
metrics.json

The archive is stored under the configured s3.model_prefix.

Training Hyperparameters

Values under sagemaker.training.hyperparameters are passed to source/train.py as command-line arguments.

Name	Type	Default	Description
model	string	yolo26n.pt	Ultralytics model weights or model YAML.
epochs	int	25	Number of training epochs.
imgsz	int	640	Square training image size.
batch	int	16	Images per training batch.
workers	int	2	DataLoader worker count.
patience	int	20	Early stopping patience.
device	string	auto	Optional Ultralytics device value such as 0 or cpu.
data-yaml	string	auto	Optional path to data.yaml; normally discovered from the uploaded dataset root.
dataset-dir	string	SM_CHANNEL_TRAIN	Uploaded dataset root mounted by SageMaker.

Do not set dataset-dir or model-dir in normal SageMaker runs. SageMaker sets those automatically through SM_CHANNEL_TRAIN and SM_MODEL_DIR.