> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ovalbee.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ovalbee.com/_mcp/server. # Train YOLO > Train a YOLO object detection or instance segmentation model directly on OvalBee datasets. Runs on: gpu Dockerfile > **Note** > > First run can take longer while the worker pulls the configured Docker image. ## Overview Fine-tunes a YOLO model from your workspace registry on an OvalBee train and validation dataset, and registers the result as a new version of that model. The node converts both datasets to YOLO format itself, so no conversion or upload node sits on either side of it. What the model learns comes from the task type of the model you pick, not from a setting on this node: * **Object detection** models train on bounding boxes. * **Instance segmentation** models train on masks, exported as YOLO polygon labels. Classification and pose models aren't supported. The run's live report opens from the node, and the **Best Loss** badge shows the lowest training loss reached. ```mermaid flowchart LR n1["Dataset"] --> n2["Train/validation split"] --> n3["Train YOLO"] --> n4["Model version"] ``` ### Pretrained models The model catalog ships these COCO-pretrained detectors. Copy one into your workspace from the **Model** picker to use it. OvalBee hosts none of these weights: Ultralytics downloads the checkpoint by name on first use. | Model | Checkpoint | Input size | COCO val mAP50-95 | Parameters, M | FLOPs, B | | ------- | ------------ | ---------: | ----------------: | ------------: | -------: | | YOLOv8n | `yolov8n.pt` | 640 | 37.3 | 3.2 | 8.7 | | YOLOv8s | `yolov8s.pt` | 640 | 44.9 | 11.2 | 28.6 | | YOLOv8m | `yolov8m.pt` | 640 | 50.2 | 25.9 | 78.9 | | YOLOv8l | `yolov8l.pt` | 640 | 52.9 | 43.7 | 165.2 | | YOLOv8x | `yolov8x.pt` | 640 | 53.9 | 68.2 | 257.8 | | YOLOv9c | `yolov9c.pt` | 640 | 53.0 | 25.5 | 102.8 | | YOLOv9e | `yolov9e.pt` | 640 | 55.6 | 58.1 | 192.5 | | YOLO11n | `yolo11n.pt` | 640 | 39.5 | 2.6 | 6.5 | | YOLO11s | `yolo11s.pt` | 640 | 47.0 | 9.4 | 21.5 | | YOLO11m | `yolo11m.pt` | 640 | 51.5 | 20.1 | 68.0 | | YOLO11l | `yolo11l.pt` | 640 | 53.4 | 25.3 | 86.9 | | YOLO11x | `yolo11x.pt` | 640 | 54.7 | 56.9 | 194.9 | > **Note** > > These numbers come from the [Ultralytics 8.4.33 COCO benchmarks](https://github.com/ultralytics/ultralytics/tree/v8.4.33), the same mAP and parameter figures the catalog shows for each model. > They do not guarantee the same performance on an OvalBee worker. > Speed is omitted because YOLOv8 uses A100 results, YOLO11 uses T4 results, and YOLOv9 does not publish speed results. > The catalog has no segmentation checkpoints. For instance segmentation, the workspace needs a YOLO model registered as instance segmentation, such as a `-seg` checkpoint added with [Upload model](/node-library/nodes/models-general-upload-model). ## Prerequisites | Requirement | What you need | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GPU worker** | A worker with GPU execution enabled. | | **Annotated datasets** | A train and a validation dataset with object annotations, holding different images, e.g. the outputs of [Train/validation split](/node-library/nodes/sample-train-validation-split). Instance segmentation needs polygon or mask annotations. | | **YOLO model** | A YOLO model in the workspace registry: a catalog model copied in from the picker, a version from an earlier training run, or a checkpoint registered with Upload model. | #### Exported YOLO dataset structure The node writes this tree into the task's own working directory before training: ```text 📁 dataset/ ├── 📄 data.yaml ├── 📁 images/ │ ├── 📁 train/ │ └── 📁 val/ └── 📁 labels/ ├── 📁 train/ └── 📁 val/ ``` Instance segmentation runs write the same tree, with polygon label lines instead of boxes. Both datasets are exported in a single pass so the two splits share one class index space. The tree is rebuilt from the datasets on every run and nothing downstream can read it. ## How it works Exports the train and validation datasets to a YOLO-format tree, as boxes or polygons depending on the model's task type. Loads the starting weights of the picked version and checks that they match its task type. Trains with Ultralytics. The new version is created as training starts and receives checkpoints while the run goes, and the live report updates beside it. Predicts on up to eight validation images with the best checkpoint and adds them to the report. Uploads the final checkpoints and metrics, marks the version ready, and returns it on **Model**. ## FAQ #### What happens when I rerun the node? Every run adds a new version to the model, or to **Destination model** when one is set. Earlier versions stay in the registry and the source datasets aren't changed. When **Model** names the model itself rather than a pinned version, it follows the newest ready version, so a rerun that trains into the same model fine-tunes the previous run's result. Pick a specific version to start every run from the same weights. #### What happens if training fails partway through? The version is created before training starts and receives the latest best and last checkpoints about every two minutes. A run that fails keeps what it uploaded, and its version is marked failed, so it isn't offered in the model pickers. If uploading fails five times in a row, the node stops training rather than carry on with no way to save the result. #### What does the trained version record? The version holds `best.pt` and `last.pt` (intermediate epoch checkpoints are not kept), the Ultralytics results and plots, your hyperparameters as typed, and the full argument set Ultralytics resolved. It also records the class list, the train and validation datasets, the version training started from, the training report, and the last epoch's mAP50, mAP50-95, precision, and recall. Segmentation runs add mask mAP50 and mask mAP50-95. #### Which classes does the model learn? When the train dataset is pinned to an ontology, the model learns that ontology's object classes in its order, and labels of any other class are skipped. Otherwise the classes come from the annotations in the datasets. Tags never become classes. #### Which annotations are used for each task type? Detection trains on boxes: polygons, masks, and other shapes are converted to their bounding boxes. Instance segmentation trains on polygons, with masks converted to polygons. Rectangles are skipped, and a run whose datasets hold only rectangles stops with an error. #### How is the Best Loss badge calculated? For each epoch, the node adds up the box, classification, and distribution focal training losses, plus the segmentation loss on segmentation runs. The badge shows the lowest sum as `Loss: value` with four decimal places. It stays empty if Ultralytics logged no readable loss rows. #### Why does the run stop with a dataset error? The datasets hold no annotated object classes, so there is nothing to train on. The check uses the datasets' computed statistics before anything is downloaded, and the export repeats it. For instance segmentation the datasets must also hold polygon or mask annotations. Check the dataset contents, then rerun. #### Why does training fail as soon as it starts? **Hyperparameters** may not be a YAML mapping, or it may contain an invalid Ultralytics argument. Fix the YAML and check its arguments against the pinned Ultralytics configuration reference. #### Why can't the node load the selected model? The model's task type must be object detection or instance segmentation. The version must also have weights to start from: a checkpoint in its asset, or a checkpoint name Ultralytics can download. A catalog checkpoint that contradicts the task type, such as a `-seg` checkpoint on a detection model, is rejected. #### Why are the gallery, metrics, plots, or checkpoint widgets empty? Checkpoint saving or validation may be disabled, or Ultralytics may not have produced the required files. Keep `save` and `val` enabled and check the effective training configuration. #### Why can't I open the report? Training continues when the report asset cannot be created. Check the run logs and workspace asset permissions. ## Inputs **`Train dataset`** `dataset` — required Dataset to train on. Its assets and annotations are converted to YOLO format for you, so nothing has to convert them first. Key: `TRAIN_DATASET`. --- **`Validation dataset`** `dataset` — required Dataset held out to measure quality while training runs. Converted together with the training dataset, so both share the same class list. Key: `VAL_DATASET`. --- **`Model`** `model` — required Model to fine-tune, trained in this workspace or installed from the zoo. Training starts from the weights of the version you pick, and the result is registered as a new version of this model unless Destination model names another one. Key: `MODEL`. --- **`Destination model`** `model` Model the trained version is registered under, when it should not go to the one being fine-tuned. Leave empty to add the new version to the Model above. Key: `DESTINATION_MODEL`. --- **`Hyperparameters`** `yaml` — required Ultralytics training settings in YAML - number of epochs, image size, batch size and the rest. Dataset paths and the output location are filled in for you and cannot be set here. Key: `CONFIG`. --- ## Outputs **`Report Asset`** `report` ID of the asset containing the live YOLO training report. Shown as an artifact. Key: `REPORT_ID`. --- **`Model`** `model` Reference to the registry version this run produced, as `<model id>@<version id>`. It wires into the Model input of a predict, export or evaluate node and pins it to exactly these weights. Empty when the run could not be registered. Shown as an artifact. Key: `MODEL`. --- **`Best Loss`** `string` Lowest total training loss achieved (shown as a badge). Shown on the node as a badge. Key: `BEST_LOSS`. --- ## Models and configuration **Model** is both what training starts from and where its result is filed: the run adds a version to that model. Set **Destination model** to file the result elsewhere. The trained version is created there instead, and **Model** is then only the starting weights. Both pickers list only YOLO models of this workspace, and only their ready versions. #### Checkpoint selection details A version produced by training or registered by upload starts from the checkpoint stored with it, the best one when there are several. A version copied from the catalog hosts no weights of its own, so Ultralytics downloads its checkpoint by name. Either way the new version records the picked version as its starting point. #### Default hyperparameters OvalBee starts with these values in **Hyperparameters**: | Setting | Default | Meaning | | ---------- | ------: | ------------------------------------- | | `epochs` | `100` | Maximum training epochs | | `imgsz` | `640` | Training and validation image size | | `batch` | `16` | Batch size passed to Ultralytics | | `patience` | `20` | Early-stopping patience | | `workers` | `8` | Data-loading workers | | `plots` | `true` | Generate Ultralytics diagnostic plots | | `save` | `true` | Save checkpoints | | `val` | `true` | Run validation during training | Delete a value to use the pinned Ultralytics default instead. #### Configuration **Hyperparameters** must be a YAML mapping. The effective configuration follows this order: 1. Values present in **Hyperparameters** override Ultralytics 8.4.33 defaults. 2. The selected **Model** overrides and removes `model`. 3. The node overrides `data`, `project`, `name`, and `exist_ok` so the exported dataset and the task's artifacts directory are used. 4. Other valid Ultralytics training arguments pass through unchanged. ## Report The report appears near the start of training and updates as new metrics and files arrive. It tracks metrics, losses, learning rates, plots, TensorBoard, and checkpoints. A final update after training adds the predictions gallery and a download panel for the trained checkpoints. #### Report sections | Section | What it shows | When it appears | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **Overview** | mAP50-95, mAP50, precision, and recall, a one-line verdict, and the run's model, epochs, duration, image counts, and classes. A warning appears when training and validation hold the same images. | From the first report sync. Metrics read `N/A` until a validation row exists. | | **Predictions** | Predictions from the best checkpoint on a fixed sample of up to eight validation images. | After training. Skipped when validation images, classes, or a saved checkpoint are unavailable. | | **Evaluation metrics** | The same four box metrics, from the epoch with the best validation mAP50-95. | From the first report sync. | | **Training curves** | Every loss, metric, and learning-rate series Ultralytics logs per epoch. | From the first report sync. The charts fill as epochs complete. | | **Diagnostic plots** | Results, confusion matrices, and precision-recall, precision, recall, and F1 curves rendered by Ultralytics. | After at least one plot exists. | | **TensorBoard** | The TensorBoard event stream. | From the first report sync. Empty until Ultralytics writes events. | | **Artifacts** | Saved `.pt` checkpoints and their sizes, replaced by a checkpoint download panel after training. | The list updates during training. | | **Classes** | Each class with its model output index. | Once class names are known. | | **Hyperparameters** | The **Hyperparameters** YAML as the node read it. | When **Hyperparameters** is not empty. | | **How to use the trained model** | A minimal local Ultralytics example that loads `best.pt` and predicts an image. | From the first report sync. | ## Runtime GPU memory use depends on the model, image size, and batch size. OvalBee does not list specific RTX models as supported because the runtime image has no pinned digest or recorded end-to-end hardware matrix. #### Details * Configured image: `ovalbee/node-yolo:0.0.21`. * Upstream base: the Docker Hardened PyTorch image, with `ultralytics==8.4.33` installed on top. * Added components: OvalBee SDK, TensorBoard, and the Ultralytics TensorBoard integration. * Exact CUDA, PyTorch, NVIDIA driver, and GPU compatibility depends on the image digest deployed by the worker. ## JSON config Machine-readable node interface for automation and advanced usage. #### Show JSON ```json { "name": "Train YOLO", "description": "Train a YOLO object detection or instance segmentation model directly on OvalBee datasets.", "category": "Train", "namespace": "ovalbee", "templateKey": "models/yolo/train_yolo", "version": "v1", "inputs": [ { "key": "TRAIN_DATASET", "label": "Train dataset", "type": "dataset", "description": "Dataset to train on. Its assets and annotations are converted to YOLO format for you, so nothing has to convert them first.", "required": true, "default": null, "visibleWhen": null, "options": { "creatable": false } }, { "key": "VAL_DATASET", "label": "Validation dataset", "type": "dataset", "description": "Dataset held out to measure quality while training runs. Converted together with the training dataset, so both share the same class list.", "required": true, "default": null, "visibleWhen": null, "options": { "creatable": false } }, { "key": "MODEL", "label": "Model", "type": "model", "description": "Model to fine-tune, trained in this workspace or installed from the zoo. Training starts from the weights of the version you pick, and the result is registered as a new version of this model unless Destination model names another one.\n", "required": true, "default": null, "visibleWhen": null, "options": { "scope": "my", "framework": "yolo" } }, { "key": "DESTINATION_MODEL", "label": "Destination model", "type": "model", "description": "Model the trained version is registered under, when it should not go to the one being fine-tuned. Leave empty to add the new version to the Model above.\n", "required": false, "default": null, "visibleWhen": null, "options": { "scope": "my", "framework": "yolo" } }, { "key": "CONFIG", "label": "Hyperparameters", "type": "yaml", "description": "Ultralytics training settings in YAML - number of epochs, image size, batch size and the rest. Dataset paths and the output location are filled in for you and cannot be set here.", "required": true, "default": "epochs: 100\nimgsz: 640\nbatch: 16\npatience: 20\nworkers: 8\nplots: true\nsave: true\nval: true\n", "visibleWhen": null } ], "outputs": [ { "key": "REPORT_ID", "label": "Report Asset", "type": "report", "description": "ID of the asset containing the live YOLO training report.", "artifact": true, "badge": false, "badgeOpens": null, "hidden": false }, { "key": "MODEL", "label": "Model", "type": "model", "description": "Reference to the registry version this run produced, as `@`. It wires into the Model input of a predict, export or evaluate node and pins it to exactly these weights. Empty when the run could not be registered.\n", "artifact": true, "badge": false, "badgeOpens": null, "hidden": false }, { "key": "BEST_LOSS", "label": "Best Loss", "type": "string", "description": "Lowest total training loss achieved (shown as a badge).", "artifact": false, "badge": true, "badgeOpens": null, "hidden": false } ], "runtime": { "type": "docker", "devices": [ "gpu" ], "dockerImage": "ovalbee/node-yolo:0.0.21" }, "widgets": { "widget": { "id": "report-preview", "settings": { "reportAsset": { "type": "variable", "value": "self.outputs.REPORT_ID" }, "name": { "type": "input", "value": "Open training report" } } } } } ``` ## References #### Sources and related pages * [Evaluate object detection](/node-library/nodes/evaluate-evaluate-object-detection) * [Predict YOLO](/node-library/nodes/models-yolo-predict-yolo) * [Export YOLO](/node-library/nodes/models-yolo-export-yolo) * [Ultralytics repository at v8.4.33](https://github.com/ultralytics/ultralytics/tree/v8.4.33) * [Training mode documentation at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/modes/train.md) * [Configuration and hyperparameter documentation at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/usage/cfg.md) * [Default configuration at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/ultralytics/cfg/default.yaml) * [YOLOv8 benchmark table at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/models/yolov8.md#L62-L72) * [YOLOv9 benchmark table at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/models/yolov9.md#L98-L106) * [YOLO11 benchmark table at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/models/yolo11.md#L69-L79) * [Ultralytics license at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/LICENSE)