Update to Ultralytics YOLO

{
  "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.\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 263
    },
    {
      "relative_path": "training-args.md",
      "size_in_bytes": 10048
    }
  ],
  "name": "yolo-training",
  "skill_md_contents": "---\nname: yolo-training\ndescription: >\n  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.\n---\n\n# Training & fine-tuning\n\n## Fastest route: train in Platform\n\nUse [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:\n\n1. Click **New Model** on a project page, or on a dataset page to preselect that dataset.\n2. Select a compatible pretrained model, ready dataset, GPU, epochs, image size, and batch size.\n3. Click **Start Training** and watch live charts, console logs, and system metrics.\n4. Open the completed model to inspect validation plots and use its **Predict**, **Export**, or **Deploy** tab. Platform preserves `best.pt` automatically.\n\nCloud 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:\n\n```bash\nexport ULTRALYTICS_API_KEY=\"YOUR_API_KEY\"\nyolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug \\\n  epochs=100 project=username/project-slug name=experiment-1\n```\n\nWith `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.\n\n## Quickstart (detection)\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")  # ALWAYS start from pretrained weights\nresults = model.train(data=\"data.yaml\", epochs=100, imgsz=640, batch=16, device=0)\n```\n\n```bash\nyolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640 batch=16 device=0\n```\n\nClass-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).\n\n## Base arguments worth setting (task trainers can override them)\n\n| Arg              | Default     | Notes                                                                                                                                                                           |\n| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `epochs`         | 100         | 100–300 for fine-tuning; rely on early stopping, not guesses                                                                                                                    |\n| `patience`       | 100         | epochs without val improvement before early stop; ~20–50 for quick iterations                                                                                                   |\n| `imgsz`          | task/model  | global fallback 640; classify uses 224 when unset; explicit values win                                                                                                          |\n| `batch`          | 16          | `-1` auto-fits ~60% VRAM (single GPU); float like `0.8` = VRAM fraction; else integer                                                                                           |\n| `device`         | None        | `0`, `[0,1]` (DDP), `cpu`, `mps`, `-1` picks an idle GPU                                                                                                                        |\n| `cache`          | False       | `True` (RAM) or `\"disk\"` for I/O-bound training                                                                                                                                 |\n| `workers`        | 8           | lower if RAM/shared-memory errors                                                                                                                                               |\n| `freeze`         | None        | freeze first N layers (`freeze=10` ≈ backbone) for small datasets                                                                                                               |\n| `optimizer`      | auto        | leave on auto (MuSGD above 10k iterations, else AdamW); depth fine-tuning overrides it below                                                                                    |\n| `lr0` / `lrf`    | 0.01 / 0.01 | `lr0` ignored by `optimizer=auto`; set an explicit optimizer to use it (see depth recipe)                                                                                       |\n| `fraction`       | 1.0         | subset training — `fraction=0.1` for smoke tests                                                                                                                                |\n| `resume`         | False       | continue an interrupted run (see recipes)                                                                                                                                       |\n| `project`/`name` | None        | output folder: relative `project` → `runs/<task>/<project>/<name>`, absolute → `<project>/<name>`. With an API key available on Python 3.11+, any `project` uploads to Platform |\n| `seed`           | 0           | reproducible with `deterministic=True` (default)                                                                                                                                |\n| `compile`        | False       | torch.compile; also `\"max-autotune-no-cudagraphs\"` etc.                                                                                                                         |\n| `time`           | None        | max training hours — overrides epochs                                                                                                                                           |\n\nFull argument, augmentation, and loss-weight tables: `training-args.md` (this folder) — read before changing anything not listed above. `yolo cfg` shows the base schema and defaults; task trainers, checkpoints, and explicit arguments determine effective values.\n\n## Recipes\n\n- **Resume interrupted run**: `YOLO(\"runs/detect/train/weights/last.pt\").train(resume=True)`. Resume finishes the original `epochs`; to train longer after completion, start a NEW training from `best.pt` (resume can't extend a finished run).\n- **Multi-GPU**: `device=[0,1]` with an integer `batch` (AutoBatch is single-GPU only). DDP workers rebuild from a generated script that cloudpickles the trainer, model, and callbacks; official Windows PyTorch>=2.4 wheels can't launch DDP, so use Linux or WSL2.\n- **Small detect-style dataset (<~1k images)**: pretrained + `freeze=10`, `n`/`s` model, default augmentation, watch val curves.\n- **Depth fine-tuning**: start from `-depth.pt` and use `optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4`.\n- **Small objects**: try `imgsz=1280` (more compute/VRAM; reduce batch if needed), or `tile=True` to train, validate, and predict on overlapping native-resolution windows of large images.\n- **Experiment hygiene**: self-describing run names (`name=0811_yolo26s_helmets_e100`), one variable per run; each run's full config is saved in `runs/<task>/<name>/args.yaml` — diff those to compare runs.\n- **Logging integrations**: `yolo settings tensorboard=True` (likewise `wandb`), then train normally. `mlflow`, `comet`, and `clearml` are on by default and activate once their package is installed.\n- **Knowledge distillation**: `distill_model=yolo26l.pt dis=6.0` trains the student with a larger teacher.\n\n## Validation\n\n```bash\nyolo val model=runs/detect/train/weights/best.pt data=data.yaml # split=val by default\n```\n\nPer-task headline metrics: detect/obb `mAP50-95(B)`, segment `(M)`, pose `(P)`, semantic `mIoU`, depth `delta1`, classify `accuracy_top1`. Val base defaults are `conf=0.001` (`0.01` for OBB), `iou=0.7`, and `nms=None` (one-to-many head + NMS); `nms=False` validates YOLO26's NMS-free head, where `iou` is inactive. Use `split=test` for the test set and `save_json=True` for COCO-format eval.\n\n## Reading a finished run (`runs/<task>/<name>/`)\n\n- `weights/best.pt` — highest val fitness; **use this one**. `last.pt` — for resuming.\n- `results.csv` / `results.png` — per-epoch losses and val metrics. Interpretation: train loss ↓ while val mAP plateaus-then-drops = **overfitting** (more data/aug, smaller model — `best.pt` already kept the good checkpoint). Both flat and low = **underfitting** (bigger model, more epochs, higher imgsz, check labels). mAP<sub>50</sub> good but mAP<sub>50-95</sub> poor = sloppy localization (higher imgsz, better boxes).\n- `train_batch*.jpg` — augmented images with labels drawn. **Look once per project**: wrong labels are instantly visible here.\n- `confusion_matrix.png` — off-diagonal cluster between two classes = inconsistent labels or genuinely similar classes. Axes are predicted (y) × true (x): heavy background **row** = missed detections (that class needs more/better examples); heavy background **column** = false positives (add background images or raise `conf` at inference).\n\n## Troubleshooting\n\n| Symptom                       | Fix, in order                                                                                          |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------ |\n| CUDA out of memory            | lower `batch` (or `batch=-1`), lower `imgsz`, smaller model; kill zombie python processes holding VRAM |\n| NaN / exploding loss          | set `optimizer=AdamW lr0=0.001` (`auto` ignores `lr0`); check labels; try `amp=False`                  |\n| mAP near 0                    | dataset problem 95% of the time — see yolo-datasets, check `train_batch*.jpg`                          |\n| mAP plateaus low              | more/better data first; then imgsz ↑, bigger model, more epochs; see yolo-tuning playbook              |\n| Stopped earlier than expected | that's `patience` — raise it or accept `best.pt`                                                       |\n| Dataloader slow / GPU idle    | `cache=True`/`\"disk\"`, raise `workers`, data on SSD                                                    |\n| Val metrics zero mid-run      | classes missing from the val split                                                                     |\n\nAnti-patterns: `pretrained=False` \"to train properly\" (needs ~100× more data); benchmarking model sizes on 50 images; copying 30-argument commands (start from defaults); tuning hyperparameters while the confusion matrix screams label noise.\n\n## Related pages\n\n- `training-args.md` — full train/augmentation/loss-weight argument tables. Read before setting any argument not in the table above.\n\nIf the installed version rejects an argument (`yolo checks` shows the version), trust the error text and `yolo cfg` over this file.\n"
}