173 lines
4.8 KiB
Markdown
173 lines
4.8 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
|
|
|
|
- AWS credentials configured for the profile in `config.yaml`
|
|
- Infrastructure already deployed with `uv run qc-cli infra setup`
|
|
- A Roboflow API key exported as `ROBOFLOW_API_KEY`
|
|
- `curl` and `unzip` available locally
|
|
|
|
Install or sync the project dependencies:
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
Set the Roboflow API key for the current shell:
|
|
|
|
```bash
|
|
export ROBOFLOW_API_KEY=your-roboflow-api-key
|
|
```
|
|
|
|
## 1. Download The Dataset
|
|
|
|
Download version 1 of the dataset in YOLO format. The script uses the Roboflow REST API directly and does not require Python:
|
|
|
|
```bash
|
|
bash examples/meter-detection/download_dataset.sh
|
|
```
|
|
|
|
Confirm the extracted 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
|
|
```
|
|
|
|
The expected layout is similar to:
|
|
|
|
```text
|
|
examples/meter-detection/data/electric-meter-detection/
|
|
data.yaml
|
|
train/
|
|
valid/
|
|
test/
|
|
```
|
|
|
|
The `test/` split may be absent depending on the exported dataset version.
|
|
|
|
## 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
|
|
uv run 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`:
|
|
|
|
```bash
|
|
uv run qc-cli upload examples/meter-detection/data/electric-meter-detection --config config.yaml
|
|
```
|
|
|
|
Directory uploads preserve paths relative to the uploaded directory, so SageMaker receives the dataset root with `data.yaml` plus the split directories.
|
|
|
|
## 5. Start Training
|
|
|
|
Submit the SageMaker training job:
|
|
|
|
```bash
|
|
uv run qc-cli train start --config config.yaml
|
|
```
|
|
|
|
The command prints the submitted SageMaker job name. Check progress with:
|
|
|
|
```bash
|
|
uv run qc-cli train status --config config.yaml
|
|
```
|
|
|
|
Or pass the job name explicitly:
|
|
|
|
```bash
|
|
uv run qc-cli train status qc-cli-YYYYMMDD-HHMMSS --config config.yaml
|
|
```
|
|
|
|
## 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`.
|
|
|
|
## 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 `SM_CHANNEL_TRAIN`. |
|
|
|
|
Do not set `train-dir` or `model-dir` in normal SageMaker runs. SageMaker sets those automatically through `SM_CHANNEL_TRAIN` and `SM_MODEL_DIR`.
|