# 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:

```text
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:

```text
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:

```text
examples/meter-detection/data/electric-meter-detection
```

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

```text
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:

```bash
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:

```yaml
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:

```text
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:

```yaml
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:

```yaml
      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:

```yaml
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:

```bash
qc-cli infra status
```

## 4. Upload The Dataset

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

```bash
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:

```bash
qc-cli train start
```

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

```bash
qc-cli train status
```

Or pass the job name explicitly:

```bash
qc-cli train status qc-cli-YYYYMMDD-HHMMSS
```

## SageMaker Outputs

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

This example writes:

```text
best.pt
model.onnx
metrics.json
```

The archive is stored under the configured `s3.model_prefix`.

## 6. Configure Qualcomm AI Hub

Authenticate with Qualcomm AI Hub:

```bash
qai-hub configure --api_token
```

Add AI Hub settings to `config.yaml`. The input name and image size must match the ONNX model exported by this example:

```yaml
aihub:
  device:
    name: Dragonwing IQ-9075 EVK
  target_runtime: tflite
  input_specs:
    images: [[1, 3, 640, 640], float32]
  job_name: meter-detection
  model_name: meter-detection
  output_dir: build/qai-hub/meter-detection
```

Use the same image size configured in `sagemaker.training.hyperparameters.imgsz`. For example, a smoke-test model trained with `imgsz: 320` requires `images: [[1, 3, 320, 320], float32]`.

## 7. Prepare AI Hub Inputs

Generate calibration samples and a validation input from the downloaded dataset:

```bash
uv run python examples/meter-detection/prepare_aihub_inputs.py --image-size 640
```

This writes:

```text
examples/meter-detection/data/aihub_calibration/*.npy
examples/meter-detection/data/inputs.npz
```

The script applies the preprocessing expected by the exported YOLO model: aspect-ratio-preserving letterboxing, RGB channel order, channel-first layout, and pixel values normalized to `[0, 1]`.

Set `--image-size` to the training `imgsz` value when it is not `640`.

## 8. Upload To Qualcomm AI Hub

Use the SageMaker job name printed by `qc-cli train start`:

```bash
qc-cli ai-hub upload \
  examples/meter-detection/data/aihub_calibration \
  examples/meter-detection/data/inputs.npz \
  --from-job qc-cli-YYYYMMDD-HHMMSS
```

The command downloads the job's `model.tar.gz`, finds `model.onnx`, uploads it to AI Hub, and runs quantization, compilation, validation, and profiling. The uploaded source model uses the configured `aihub.model_name`.

The training example sanitizes the Ultralytics ONNX export before saving `model.onnx`. This removes graph input or output names, such as `output0`, that are duplicated in the ONNX `value_info` metadata and rejected by AI Hub.

For a model already downloaded by a failed upload attempt, sanitize the extracted ONNX file and retry using the local model. Replace the job name in both paths:

```bash
uv run --with onnx python examples/meter-detection/source/sanitize_onnx.py \
  build/qai-hub/meter-detection/qc-cli-YYYYMMDD-HHMMSS/source/extracted/model.onnx \
  --output build/qai-hub/meter-detection/model.aihub.onnx

qc-cli ai-hub upload \
  examples/meter-detection/data/aihub_calibration \
  examples/meter-detection/data/inputs.npz \
  --onnx-path build/qai-hub/meter-detection/model.aihub.onnx
```

If the meter-detection job is still the last training job in `.qc-cli.json`, `--from-job` can be omitted. Keeping it explicit prevents accidentally uploading an artifact from a different training run.

To resume after a completed step, use one of:

```bash
qc-cli ai-hub upload \
  examples/meter-detection/data/aihub_calibration \
  examples/meter-detection/data/inputs.npz \
  --from-step compile
```

```bash
qc-cli ai-hub upload \
  examples/meter-detection/data/aihub_calibration \
  examples/meter-detection/data/inputs.npz \
  --from-step validate
```

Download the compiled artifact after the workflow completes:

```bash
qc-cli ai-hub download --output build/qai-hub/meter-detection/model.tflite
```

## 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`.