{"id":48157,"plugin_id":"plugins_6ac51f0691748191b2d31e8c84d99c62","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:35:34.380Z","digest":"9b1fd9e5909afc459336f8d93b615034d3117c432a0e59bed65a464de2b994e8","against":null,"payload":{"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.\n","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":286}],"name":"yolo-tuning","skill_md_contents":"---\nname: yolo-tuning\ndescription: >\n  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.\n---\n\n# Improving models & hyperparameter tuning\n\n## The improvement playbook (follow in order — tuning is the LAST step)\n\nHyperparameter tuning is expensive and usually not the bottleneck. Escalate in this order, re-validating after each step:\n\n1. **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.\n2. **Train longer** — if val mAP was still rising at the end: more `epochs`, higher `patience`.\n3. **Bigger input** — small objects or mAP50 ≫ mAP50-95: raise `imgsz` (640 → 960/1280).\n4. **Bigger model** — underfitting (train and val both mediocre): n → s → m → l.\n5. **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`).\n6. **Only now: hyperparameter tuning** — worth ~0.5–2 mAP when everything above is exhausted.\n\nDecision 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.\n\n## Compare experiments in Platform\n\nKeep 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.\n\nPlatform 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.\n\n## Built-in genetic tuner\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\nmodel.tune(data=\"data.yaml\", epochs=30, iterations=300, plots=False, save=False, val=False)\n```\n\nTuning is Python-only — there is no `yolo tune` CLI mode (MODES are train/val/predict/export/track/benchmark).\n\n- Each iteration = one full (short) training with mutated hyperparameters; fitness is read from the run's val metrics.\n- 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`.\n- Custom space (subset + ranges as `(min, max)`):\n  ```python\n  model.tune(data=\"data.yaml\", epochs=30, iterations=100, space={\"lr0\": (1e-5, 1e-2), \"mosaic\": (0.5, 1.0)})\n  ```\n- 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`.\n- Distributed tuning across machines: pass `mongodb_uri=` (+ optional `mongodb_db=`, `mongodb_collection=`) — workers share one result pool via MongoDB.\n\n## Ray Tune (advanced search algorithms, parallel trials)\n\n```python\nmodel = YOLO(\"yolo26n.pt\")\nresult_grid = model.tune(use_ray=True, data=\"data.yaml\", iterations=20, epochs=30, gpu_per_trial=1)\n```\n\n- Requires `pip install \"ray[tune]\"`. Default scheduler is ASHA (early-kills bad trials after `grace_period` epochs, default 10).\n- `search_alg=` defaults to `\"optuna\"`; other strings are `\"ax\"`, `\"bayesopt\"`, `\"bohb\"`, `\"hebo\"`, `\"hyperopt\"`, `\"nevergrad\"`, `\"zoopt\"`, and `\"random\"`, or pass any Ray Tune searcher object (BOHB swaps ASHA for HyperBandForBOHB).\n- W&B logs each trial when `wandb` is installed and enabled (`yolo settings wandb=True`). Use Ray when you have multiple GPUs to parallelize trials or want smarter-than-genetic search; the built-in tuner is simpler and has no extra dependency.\n\n## Evolution best practices (\"autotraining\" recipe)\n\n- **Search cheap, retrain expensive**: tune with a small model (`n`/`s`), reduced `epochs` (~30), `plots=False save=False val=False`; then retrain the best config at full size/epochs.\n- Budget: iterations × epochs × time-per-epoch. 100–300 iterations is a realistic minimum for the genetic tuner to beat defaults.\n- Keep `data` fixed during the search — changing data invalidates all prior fitness.\n- One fitness target: the tuner maximizes validation `fitness` (mAP50-95(B) for detect; segment and pose combine box and mask/pose mAP50-95); confirm that matches what you actually care about before burning GPU days.\n- Sanity-check the winner on the val AND test split — tuned configs can overfit the val split when iterations are high.\n\nIf the installed version rejects an argument (`yolo checks` shows the version), trust the error text and `yolo cfg` over this file.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}