272 lines
7.7 KiB
Markdown
272 lines
7.7 KiB
Markdown
# 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`.
|
|
|
|
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`.
|