Skill instructions
platform-cli32.9 KB
View saved version →
---
name: platform-cli
description: >
Use when operating Ultralytics Platform from a terminal or script with the ul cloud CLI (ul cloud RESOURCE OPERATION key=value, PyPI package ultralytics-platform) — listing, creating, updating, cloning, or moving projects, datasets, and models; inspecting dataset images, statistics, metadata, duplicates, and similar images; starting and monitoring cloud training runs; per-image model validation analysis; downloading weights; exports, deployments, uploads, trash and restore, storage integrations, and account usage, storage, and billing; and building Agents (YOLO, LLM, gate, and alert workflows). For the Platform web UI or local yolo commands, see yolo; for choosing what to train and how to improve it, see yolo-training and yolo-tuning.
---
# Platform CLI (`ul cloud`)
`ul` needs Python 3.11+ and comes with `pip install ultralytics` or `pip install ultralytics-platform`. `ul cloud <resource> <operation>` calls the Platform API through the generated SDK; `ul login`, `ul train`, `ul predict`, the `ul cloud train|predict|export|download` shortcuts (see `yolo`), and the other local commands delegate to the `ultralytics` package. This skill covers Platform operations, not model selection or hyperparameter tuning.
```bash
pip install ultralytics # or `pip install ultralytics-platform`
export ULTRALYTICS_API_KEY="YOUR_API_KEY" # or `ul login API_KEY`
ul cloud --help # every resource and operation
ul cloud training start --help # one operation's arguments, types, and choices
```
## Canonical command shapes
```bash
ul cloud account summary # plan, credits, counts; `username` is your workspace
ul cloud datasets list owner=WS # owner=TEAM for a team
ul cloud projects create owner=WS project=helmets name="Helmet Detection" visibility=private
ul cloud models create body='{"owner":"WS","project":"helmets","model":"exp1","name":"Experiment 1"}'
ul cloud training start model_id=MODEL_ID gpu_type=l4 \
train_args='{"model":"yolo26n.pt","data":"ul://WS/datasets/helmets","epochs":50}'
ul cloud models training owner=WS project=helmets model=exp1 # live status, epoch progress, metrics
ul cloud models files owner=WS project=helmets model=exp1 # short-lived weights download URL
```
Argument rules:
- Use the command shapes shown here without a preliminary `--help` call. Check operation help when a needed argument is missing or after an argument error.
- Arguments are SDK Python names as `key=value` (`gpu_type`, `project_id`), never `--key value`. A boolean key given without `=value` means `true`. Quote JSON for the shell.
- An operation takes one `body=` JSON object exactly when its help lists `body (dict[str, Any])`. These are the operations whose API request is a union of shapes: `models create`, `deployments update`, `images update`, `lifecycle delete-trash`, `datasets ingest`, `datasets create-batch`, `upload signed-url`, `storage-integrations create`/`discover`, and `models predict`/`deployments predict`. Every other operation takes flat fields; nested objects such as `train_args`, `metadata`, and `args` are still JSON values.
- Object and array values accept `@file.json` or `@-` for stdin. Multipart binaries such as the predict `file` field accept `@path` only.
- For body keys and value types, read only the operation's request schema, such as `paths["/api/models"].post.requestBody`, from the production contract at `https://platform.ultralytics.com/openapi.json`, instead of guessing or loading the whole file.
Behavior rules:
- Output is the complete API response on stdout, printed as JSON, text, or bytes according to its content type. `omit=key1,key2` drops those keys from JSON at any depth when the question does not need them, such as `omit=trainArgs` on `projects retrieve` when run configurations are not compared, or `omit=labels,scatterSample` on `models retrieve ... analysis=1` (add `examples` to drop the per-image rows and keep thPreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
yolo8.91 KB
View saved version →
---
name: yolo
description: >
Use for ANY task involving Ultralytics Platform, the ultralytics Python package, yolo CLI, YOLO model weights (.pt), dataset annotation, training, validation, prediction, tracking, export, deployment, or the detect / segment / semantic / depth / classify / pose / OBB vision tasks.
---
# Ultralytics YOLO
Run the same lifecycle on three complementary surfaces:
- **[Ultralytics Platform](https://platform.ultralytics.com)** — the fastest start: upload or clone data, annotate in the browser, train on cloud GPUs, inspect metrics, test predictions, export, and deploy a dedicated endpoint without local setup.
- **`ultralytics` package / `yolo` CLI** — use local or remote compute, scripts, notebooks, custom pipelines, and exported artifacts directly.
- **`ul` CLI** (Python 3.11+, installed by `ultralytics` or `ultralytics-platform`) — script the Platform API itself: `ul cloud <resource> <operation> key=value` lists, creates, clones, trains, exports, and deploys Platform resources from a terminal (see `platform-cli`).
`ul cloud train|predict|export` upload local inputs as needed and run on Platform. Training returns after submission; add `watch` to follow and download results. `ul cloud download` uses the printed model URI and waits if needed; Ctrl-C stops waiting without canceling training. All four shortcuts need `ultralytics` installed; the `ul cloud <resource> <operation>` commands do not.
```bash
ul cloud train model=yolo26n.pt data=ul://username/datasets/helmets epochs=100 project=helmets name=exp1 # → run URI and download command
ul cloud download model=ul://username/helmets/exp1 # → weights/best.pt and results
ul cloud predict model=ul://username/helmets/exp1 source=video.mp4 # → annotated output
ul cloud export model=ul://username/helmets/exp1 format=onnx # → downloaded artifact
```
Mix them freely. Set `ULTRALYTICS_API_KEY`, use a Platform dataset as `data=ul://username/datasets/dataset-slug`, and set `project=username/project-slug name=experiment` during local training to stream its metrics back to Platform.
The `yolo` CLI and Python share one API. The CLI grammar is `yolo TASK MODE arg=value ...`, and Python takes the same argument names:
```bash
yolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640
```
```python
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
model.train(data="data.yaml", epochs=100, imgsz=640)
```
- TASK ∈ `detect` `segment` `semantic` `depth` `classify` `pose` `obb` — usually inferred from the weights, so it can be omitted.
- MODE ∈ `train` `val` `predict` `track` `export` `benchmark`.
- Install/upgrade: `pip install -U ultralytics`. Environment check: `yolo checks`.
- macOS ships its own `/usr/bin/ul` (a text-underlining tool), so `ul: cloud: No such file or directory` means that binary won: put the environment's `bin/` first on `PATH` or run `python -m ultralytics_platform.cli cloud ...`.
## Whole lifecycle in five commands
```bash
yolo detect train data=data.yaml model=yolo26n.pt epochs=100 # → runs/detect/train/weights/best.pt
yolo val model=best.pt data=data.yaml # mAP, per-class metrics
yolo predict model=best.pt source=video.mp4 save=True # any source: image/dir/URL/RTSP/webcam
yolo track model=best.pt source=video.mp4 # + persistent object IDs
yolo export model=best.pt format=onnx # exported model loads back into YOLO()
```
## Whole lifecycle in Platform
1. Open [Platform](https://platform.ultralytics.com) and choose the data region during onboarding.
2. Clone a public dataset from **Explore**, or create one under **Annotate** and upload images, videos, an archive, or NDJSON.
3. Label in the fullscreen editor; use SAM or a compatible YOLO model in **Smart** mode where available.
4. Create a project, click **New Model**, sePreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
yolo-datasets7.47 KB
View saved version →
---
name: yolo-datasets
description: >
Use when uploading, annotating, building, converting, analyzing, or debugging datasets in Ultralytics Platform or local YOLO — Platform dataset management and Smart Annotation, data.yaml, YOLO label .txt formats, COCO/DOTA/mask conversion, auto-labeling, splits, validation, and errors like "no labels found" or mAP near 0. Covers detect, segment, semantic, depth, classify, pose, and OBB data.
---
# Ultralytics YOLO datasets
The #1 cause of silent training failure is a malformed dataset — validate before training.
## Fastest route: prepare data in Platform
1. Open [Platform](https://platform.ultralytics.com), create a dataset under **Annotate**, and choose its task.
2. Upload images, videos, ZIP/TAR archives, or NDJSON. Existing YOLO labels and COCO JSON can be imported; cloud-storage integrations can keep supported data in place.
3. Open an image in the fullscreen editor. Use manual tools for detect, segment, semantic, classify, pose, or OBB. Switch to **Smart** mode to label with SAM (detect, segment, semantic, OBB) or a compatible official/custom YOLO model (those tasks plus pose).
4. Review the **Classes**, **Charts**, and **Errors** tabs, fix the split, and create a numbered dataset version before important runs.
Platform datasets cover all seven YOLO tasks. Depth targets are imported rather than drawn in the editor. See [Platform Data](https://docs.ultralytics.com/platform/data) and the [Annotation Editor](https://docs.ultralytics.com/platform/data/annotation).
To train on the same dataset from local code, create an API key under **Settings > API Keys**, set `ULTRALYTICS_API_KEY`, and pass the dataset's `ul://` URI as `data`:
```bash
yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug epochs=100
```
Export NDJSON when you need a portable snapshot instead of live Platform access.
## The `images` → `labels` mirror rule
Ultralytics finds a label file by replacing the **last** `/images/` path segment with `/labels/` and the image extension with `.txt`:
```
dataset/
├── data.yaml
├── images/train/ img001.jpg ... ├── images/val/ ...
└── labels/train/ img001.txt ... └── labels/val/ ...
```
- Labels next to images in an `images/` dir, or in a dir not named `labels`, are **not found** → training stops with `No labels found`; if only some are missing, those images train as backgrounds.
- Filenames must match stems exactly (case-sensitive on Linux).
- An image with no/empty label file trains as a **background image**. A few percent of true backgrounds reduce false positives; accidentally missing labels destroy recall.
## data.yaml anatomy
```yaml
path: /abs/dataset/root # absolute, or omit to use this yaml's folder; a relative value (even `.`) resolves from the CWD (datasets_dir if missing there)
train: images/train # dir, .txt file of image paths, or list of dirs
val: images/val
test: images/test # optional
names: # 0-based, contiguous indices
0: person
1: helmet
# pose only:
kpt_shape: [17, 3] # [num_keypoints, dims]; dims 2 (x,y) or 3 (x,y,visibility)
flip_idx: [0, 2, 1, ...] # L/R keypoint swap map — without it, flip augs are auto-disabled
# semantic only (optional — polygon .txt labels in labels/ also work):
masks_dir: masks # per-pixel PNG mask images
# depth only (replace names above; pair depth/{train,val}/*.png or float .npy maps):
# nc: 1
# names: {0: depth}
# depth_scale: 1000 # PNG units per meter; default millimeters
```
- Classification datasets use **no yaml**: folder structure is the label (`dataset/train/<class>/*.jpg`, `dataset/val/<class>/*.jpg`); train with `data=path/to/dataset`.
- Per-task label line formats and their gotchas: read `label-formats.md` (this folder) whenever writing or debugging label files.
## Converting from other formats — use built-ins first
```python
from ultralytics.data.converter import convert_coco
convert_coco(labels_dir="coco/annotations/", use_segments=True, cls91to80=False) # → segment
convert_Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
yolo-export12.8 KB
View saved version →
---
name: yolo-export
description: >
Use when exporting or deploying Ultralytics YOLO models in Platform or code — the Platform Export tab and yolo export/model.export() for ONNX, TensorRT, CoreML, Core AI, OpenVINO, LiteRT, NCNN, ExecuTorch, and NPUs (RKNN, QNN, Hailo, Ascend, IMX, Axelera, DeepX, Xilinx, NXP), FP16/INT8 quantization, benchmarking, and non-Python runtimes. For inference with .pt weights or Platform endpoints, see yolo-inference.
---
# Export, quantization & deployment
## Fastest route: export in Platform
Open a completed model's **Export** tab, select a format, configure its arguments, and click **Start Export**. Platform runs CPU exports directly and asks for a target GPU where the format requires one (notably TensorRT); download the artifact when the job completes. For TensorRT, select the deployment device's GPU family or Jetson target; if its TensorRT/CUDA versions differ from the device's, export locally on that device instead.
Use Platform when you do not want to install each exporter toolchain locally. Use the Python/CLI path below for custom calibration, repeatable automation, local hardware builds, or immediate parity validation. See [Platform model export](https://docs.ultralytics.com/platform/train/models#export-model).
## Quickstart
```python
from ultralytics import YOLO
model = YOLO("runs/detect/train/weights/best.pt")
path = model.export(format="onnx") # returns the exported file/dir path
```
```bash
yolo export model=best.pt format=onnx
```
Exports load straight back into `YOLO()` for predict/val — same API:
```python
model = YOLO("best.onnx") # or best.engine, best_openvino_model/, ...
```
## Choose format by target hardware
| Target | `format=` | Why |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| NVIDIA GPU / Jetson | `engine` (TensorRT) | fastest on NVIDIA; **build on the deployment device** — engines are not portable across GPUs/TRT versions |
| Intel CPU/iGPU/NPU | `openvino` | up to 3× CPU speedup on Intel |
| Apple iOS/macOS | `coreml` | broad OS coverage, Vision/iOS/Flutter support |
| Apple iOS 27+/macOS 27+ | `coreai` | native `.aimodel`; iOS/Flutter SDKs default to `coreml`; export on Apple silicon macOS 26+ or x86_64 Linux |
| Android | `litert` (renamed from `tflite`) or `ncnn` | NCNN strong on ARM |
| Raspberry Pi | `ncnn` | best ARM CPU latency |
| PyTorch Edge | `executorch` | Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
yolo-inference9.79 KB
View saved version →
---
name: yolo-inference
description: >
Use when testing, running, or deploying Ultralytics YOLO inference in Platform or code on images, video, webcams, or streams — Platform Predict and dedicated endpoints, model.predict()/yolo predict, Results API boxes/masks/keypoints, persistent tracking, annotated video, and Solutions such as counting, heatmaps, speed, queues, and parking. For optimized runtime exports, see yolo-export.
---
# Inference, Results API & tracking
## Fastest route: test and deploy in Platform
Every Platform model has a **Predict** tab: upload an image, choose an example, or capture a webcam frame; inference runs automatically and shows the task overlay, summary, raw JSON, and timing. Adjust `conf`, `iou`, and `imgsz` with the same meanings used below.
For production, open **Deploy**, choose a nearby region, and wait for the dedicated endpoint to become **Ready**. Its deployment page provides health, metrics, logs, a Predict panel, and ready-to-use Python/JavaScript/cURL examples. Call `/predict` with the deployment's bound API key as a bearer token:
```python
import requests
with open("image.jpg", "rb") as image_file:
response = requests.post(
"https://YOUR_DEPLOYMENT_URL.run.app/predict",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"file": image_file},
data={"conf": 0.25, "iou": 0.5, "imgsz": 640},
)
response.raise_for_status()
print(response.json())
```
Default-size endpoints scale to zero, so expect a cold start after idle periods; custom sizes keep a warm instance billed for uptime. See [Platform Inference](https://docs.ultralytics.com/platform/deploy/inference) and [Dedicated Endpoints](https://docs.ultralytics.com/platform/deploy/endpoints).
## Quickstart
```python
from ultralytics import YOLO
model = YOLO("yolo26n.pt") # or your runs/detect/train/weights/best.pt
results = model("https://ultralytics.com/images/bus.jpg") # list[Results], one per image
results[0].show()
```
```bash
yolo predict model=yolo26n.pt # source= omitted → the bundled bus.jpg and zidane.jpg, saved to runs/detect/predict
```
**The one rule for video/streams: `stream=True`.** The default builds a list of ALL results in RAM — OOM on long videos. `stream=True` returns a generator:
```python
for r in model("video.mp4", stream=True):
...
```
## Sources
Accepted directly: image/video path, directory, glob, URL, webcam index (`0`), RTSP/RTMP/HTTP streams, YouTube URL (needs `pytubefix`), PIL image, numpy array (assumed BGR), torch tensor, or a list of these. `vid_stride=N` processes every Nth frame.
## Arguments that matter
| Arg | Default | Notes |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `conf` | 0.25 | lower → more recall + more false positives |
| `iou` | 0.5 | NMS threshold; ignored by the NMS-free head (`nms=False`) |
| `nms` | None | default: one-to-many head + NMS; `False`: faster NMS-free YOLO26 head; `True`: embed NMS on export. Exports keep that choice |
| `imgsz` | model | inherited from the checkpoint; set explicitly for a different shape (static exports always run at their export size) |
| `classes` | None | keep only these ids, e.g. `classes=[0]` |
| `max_det` | 300 | raise for dense scenes |
| `quantize` | None | `16` selects FP16 compute for PyTorch/TorchScript off CPU; artifact/runtime precision oPreview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
yolo-models8.46 KB
View saved version →
---
name: yolo-models
description: >
Use when choosing or comparing Ultralytics models in Platform or code — picking a model family (YOLO26/YOLO11/YOLOv8, YOLO-World, YOLOE, SAM/SAM2/FastSAM, RT-DETR, YOLO-NAS), size (n/s/m/l/x), task variant (-seg, -sem, -cls, -pose, -obb, -depth), pretrained checkpoint, open-vocabulary or promptable detection/segmentation, custom architecture, Platform Explore, or exact weight names and availability.
---
# Choosing an Ultralytics model
**Default recommendation: YOLO26, pretrained.** Latest generation, with an optional NMS-free head (`nms=False`) for the fastest CPU inference and simplest deployment. Use YOLO11/YOLOv8 only to match an existing codebase or a deployment target that doesn't support YOLO26 yet. Most official weights auto-download on first use; `sam3.pt` and `sam3.1_multiplex.pt` require manual access and download.
## Choose in Platform
For the quickest no-code start, click **New Model** in a project. Its **Official** tab lists YOLO26 (recommended), YOLO11, YOLOv8, and YOLOv5 models whose task can train the selected dataset; **My Models** lists your completed or uploaded checkpoints for further fine-tuning. To browse the official models first, open the `@ultralytics` projects under **Projects** in [Platform Explore](https://platform.ultralytics.com/explore).
Use a Platform model page to inspect metrics, test it in **Predict**, export it, deploy it, clone a public model into your workspace, or download its `.pt` weights for the Python/CLI workflows below. See [Platform Models](https://docs.ultralytics.com/platform/train/models) and [Explore](https://docs.ultralytics.com/platform/explore).
## Model = family + size + task suffix
`yolo26` + `n/s/m/l/x` + task suffix → `yolo26s-seg.pt`
| Size | COCO mAP<sub>50-95</sub> | Params | T4 TensorRT | Pick for |
| ---- | ------------------------ | ------ | ----------- | ------------------------------------------ |
| n | 40.9 | 2.4M | ~1.7 ms | edge/mobile, CPU realtime, first prototype |
| s | 48.6 | 9.5M | ~2.5 ms | balanced default for most projects |
| m | 53.1 | 20.4M | ~4.7 ms | GPU server, accuracy matters |
| l | 55.0 | 24.8M | ~6.2 ms | accuracy-critical, ample GPU |
| x | 57.5 | 55.7M | ~11.8 ms | max accuracy, offline/batch |
Strategy: prototype on `n` to validate the pipeline cheaply, then scale up until accuracy stops paying for the latency. A bigger model never fixes bad labels.
| Suffix | Task | Output |
| -------- | ------------------------------- | -------------------- |
| _(none)_ | detect | boxes |
| `-seg` | instance segmentation | polygons + boxes |
| `-sem` | semantic segmentation (YOLO26+) | per-pixel class mask |
| `-depth` | monocular depth (YOLO26+) | depth map |
| `-cls` | classification | class probabilities |
| `-pose` | pose/keypoints | keypoints + boxes |
| `-obb` | oriented boxes | rotated boxes |
Notes on the newer tasks:
- **semantic** (`-sem`): dataset uses PNG masks via `masks_dir` (default `masks/`) or polygon labels; metric is mIoU.
- **depth** (`-depth`): targets are scaled uint16 PNG maps (preferred) or floating-point `.npy` maps in meters; metric is δ<sub>1</sub>. Depth models also expose `model.calibrate(data=...)`, which fits a metric-scale correction; persist it with `model.save(...)`.
## Family cheat sheet
| Family | Class | When
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
yolo-training11.1 KB
View saved version →
---
name: yolo-training
description: >
Use when training, fine-tuning, or validating Ultralytics YOLO models in Platform, cloud GPUs, or local code — model.train(), yolo train/val, remote metric streaming, epochs, batch, imgsz, devices, augmentation, multi-GPU, resumes, results, and fixing OOM, NaN loss, low mAP, or overfitting. For hyperparameter search and systematic improvement loops, see yolo-tuning.
---
# Training & fine-tuning
## Fastest route: train in Platform
Use [Platform cloud training](https://docs.ultralytics.com/platform/train/cloud-training) when you want to start in a few clicks without configuring a local GPU:
1. Click **New Model** on a project page, or on a dataset page to preselect that dataset.
2. Select a compatible pretrained model, ready dataset, GPU, epochs, image size, and batch size.
3. Click **Start Training** and watch live charts, console logs, and system metrics.
4. Open the completed model to inspect validation plots and use its **Predict**, **Export**, or **Deploy** tab. Platform preserves `best.pt` automatically.
Cloud jobs require at least one train image, one val/test image, and one labeled image. Use local/Colab training when you already have compute or need more control, while keeping Platform datasets and experiment tracking:
```bash
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug \
epochs=100 project=username/project-slug name=experiment-1
```
With `ultralytics>=8.4.120` on Python 3.11+, the `ul://` URI downloads the Platform dataset, and while an API key is available (`ULTRALYTICS_API_KEY` or the `api_key` setting), any `project=` value — even a local folder — streams metrics and uploads weights to Platform. Omit `project` to keep a run local; a list `data=` sets it internally, so unset the key for those runs.
## Quickstart (detection)
```python
from ultralytics import YOLO
model = YOLO("yolo26n.pt") # ALWAYS start from pretrained weights
results = model.train(data="data.yaml", epochs=100, imgsz=640, batch=16, device=0)
```
```bash
yolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640 batch=16 device=0
```
Class-count changes are automatic — a 3-class data.yaml on an 80-class pretrained model just works (head re-initializes, backbone transfers; `cls_remap=True` even re-maps head rows for classes whose names match).
## Base arguments worth setting (task trainers can override them)
| Arg | Default | Notes |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `epochs` | 100 | 100–300 for fine-tuning; rely on early stopping, not guesses |
| `patience` | 100 | epochs without val improvement before early stop; ~20–50 for quick iterations |
| `imgsz` | task/model | global fallback 640; classify uses 224 when unset; explicit values win |
| `batch` | 16 | `-1` auto-fits ~60% VRAM (single GPU); float like `0.8` = VRAM fraction; else integer |
| `device` | None | `0`, `[0,1]` (DDP), `cpu`, `mps`, `-1` picks an idle GPU |
| `cache` | False | `True` (RAM) Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
yolo-tuning5.59 KB
View saved version →
---
name: yolo-tuning
description: >
Use when improving or comparing Ultralytics YOLO models in Platform or code, or running hyperparameter search/autotraining — Platform experiment comparison, the systematic improvement playbook, model.tune() genetic evolution, Ray Tune, search spaces, and deciding whether tuning is worthwhile. For one training run and its arguments, see yolo-training.
---
# Improving models & hyperparameter tuning
## The improvement playbook (follow in order — tuning is the LAST step)
Hyperparameter tuning is expensive and usually not the bottleneck. Escalate in this order, re-validating after each step:
1. **Fix the data** — check `confusion_matrix.png` and `train_batch*.jpg` for label noise; review the top false-negative/false-positive val images; add examples of failing classes and true-background images. Data quality beats every other lever.
2. **Train longer** — if val mAP was still rising at the end: more `epochs`, higher `patience`.
3. **Bigger input** — small objects or mAP<sub>50</sub> ≫ mAP<sub>50-95</sub>: raise `imgsz` (640 → 960/1280).
4. **Bigger model** — underfitting (train and val both mediocre): n → s → m → l.
5. **Domain-matched augmentation** — aerial `degrees=180 flipud=0.5`, crowded scenes `mixup=0.1` (plus `copy_paste=0.3` for segment/OBB), color-critical classes lower `hsv_h` (see yolo-training's `training-args.md`).
6. **Only now: hyperparameter tuning** — worth ~0.5–2 mAP when everything above is exhausted.
Decision signals: overfitting (val drops while train improves) → more data/aug or smaller model, NOT tuning. Underfitting → bigger model/longer, NOT tuning. Label noise in the confusion matrix → nothing else matters until fixed.
## Compare experiments in Platform
Keep candidates in one [Platform project](https://docs.ultralytics.com/platform/train/projects). Train from the **New Model** dialog, ask **Ask AI** to run and compare experiments ([AutoTrain](https://docs.ultralytics.com/platform/train/autotrain)), or stream authenticated local runs by setting `project=username/project-slug` and a unique `name`. Select models together in the project charts, or use **Table > Diff** to compare training arguments and final metrics.
Platform tracks and charts experiments; the built-in genetic tuner and Ray Tune below run only in Python. Use a completed Platform model as the next base checkpoint, or download its `.pt` file, after the comparison identifies a winner.
## Built-in genetic tuner
```python
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
model.tune(data="data.yaml", epochs=30, iterations=300, plots=False, save=False, val=False)
```
Tuning is Python-only — there is no `yolo tune` CLI mode (MODES are train/val/predict/export/track/benchmark).
- Each iteration = one full (short) training with mutated hyperparameters; fitness is read from the run's val metrics. Iterations set `project` internally, so with an API key available on Python 3.11+ each one uploads to Platform; unset the key to tune locally.
- Default search space: 26 keys — `lr0`, `lrf`, `momentum`, `weight_decay`, `warmup_epochs`, `warmup_momentum`, loss weights (`box`, `cls`, `cls_pw`, `dfl`), augmentation knobs (`hsv_*`, `degrees`, `translate`, `scale`, `shear`, `perspective`, `flipud`, `fliplr`, `bgr`, `mosaic`, `mixup`, `cutmix`, `copy_paste`), `close_mosaic`.
- Custom space (subset + ranges as `(min, max)`):
```python
model.tune(data="data.yaml", epochs=30, iterations=100, space={"lr0": (1e-5, 1e-2), "mosaic": (0.5, 1.0)})
```
- Results: `runs/<task>/tune/` — `best_hyperparameters.yaml`, `tune_results.ndjson`, fitness plots. Retrain fully with those values and `optimizer=AdamW` (the tuner's default); `optimizer=auto` would ignore the tuned `lr0` and `momentum`.
- Distributed tuning across machines: pass `mongodb_uri=` (+ optional `mongodb_db=`, `mongodb_collection=`) — workers share one result pool via MongoDB.
## Ray Tune (advanced search algorithms, parallel trials)
```python
model = YOPreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
