New example and updated ai-hun upload order (#4)
Co-authored-by: samirodr <sami.rodrigue@slalom.com> Reviewed-on: #4
This commit was merged in pull request #4.
This commit is contained in:
266
examples/meter-detection/README.md
Normal file
266
examples/meter-detection/README.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# 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: onnx
|
||||
input_specs:
|
||||
images: [[1, 3, 640, 640], float32]
|
||||
job_name: meter-detection
|
||||
model_name: meter-detection
|
||||
output_dir: build/qai-hub/meter-detection
|
||||
```
|
||||
|
||||
The ONNX graph is the source of truth. The export normally uses the same value as `sagemaker.training.hyperparameters.imgsz`, but changing `config.yaml` after training does not resize an existing model. For example, a model exported 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]`.
|
||||
|
||||
## 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`, and runs the following AI Hub workflow:
|
||||
|
||||
1. Compile the external ONNX to a Workbench-optimized ONNX model.
|
||||
2. Quantize the optimized ONNX model.
|
||||
3. Compile the quantized model when the configured deployment runtime is not `onnx`.
|
||||
4. Validate and profile the final model.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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`.
|
||||
Reference in New Issue
Block a user