> 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. # Predict YOLO > Run a YOLO detection or instance segmentation model on a dataset and write the images with their predictions to the output dataset. Runs on: gpu, cpu Dockerfile > **Note** > > First run can take longer while the worker pulls the configured Docker image. ## Overview Runs a YOLO model from your workspace registry on an image or video dataset and writes the assets with their predictions to the output dataset. The input dataset stays unchanged. Pick a **Destination dataset** to add the predictions to a dataset you already have, such as a labeling pool or an active-learning set: it keeps what it holds, and an image it already annotates gets the new prediction instead. Leave it empty and the node writes into a dataset of its own, one version per run. The output geometry follows the task type of the model you pick, not a setting on this node: * **Object detection** models produce bounding boxes. * **Instance segmentation** models produce one mask per instance on images. Videos always get bounding boxes. Each prediction carries its score in a `confidence` tag. Classification and pose models aren't supported. The **Prediction Count** badge shows how many assets were processed and opens the output dataset. ```mermaid flowchart LR n1["Train YOLO"] --> n2["Predict YOLO"] --> n3["Evaluate object detection"] ``` ### 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. | | **YOLO model** | A YOLO model in the workspace registry: a catalog model copied in from the picker, a version trained by [Train YOLO](/node-library/nodes/models-yolo-train-yolo), or a checkpoint registered with Upload model. | ## How it works Takes the destination dataset, or the node's own output dataset - created on the first run, a new empty version of it on a rerun - and adds the input dataset's images and videos to it without duplicating them. Pins the output dataset to the model's ontology and loads the version's checkpoint. Runs inference in batches, keeping only the classes ticked in **Predict classes** when any are. Uploads one prediction annotation per asset, then refreshes the output dataset's statistics. ## FAQ #### Does the output dataset keep the input's annotations? No. The output holds the same image and video assets as the input, but only the predictions from this run as annotations. Because both datasets share the assets, you can use them as ground truth and predictions in [Evaluate object detection](/node-library/nodes/evaluate-evaluate-object-detection). #### What data can Predict YOLO process? Images and videos. If the dataset holds at least one image, only images are predicted: videos are still added to the output dataset but get no predictions in that run. Use separate datasets when you need inference on both. Videos are predicted frame by frame, and each detection becomes a single-frame box object. #### How is the output dataset named? The first run names it after the input dataset with a `__yolo_predict` suffix. Reruns add versions to that same dataset, so earlier results stay in its version history. #### What does each prediction record? Each annotation is tagged with the task that produced it, the model version, and the model's name. Every box or mask stores its score in the numeric `confidence` tag. #### Which class names do predictions use? The class list recorded on the model version, in its order. When the version records none, the names stored in the checkpoint are used. #### What does the Prediction Count badge count? Processed assets, not boxes. An asset still counts when it ends up with no predictions, e.g. after class filtering. #### Why is the output empty and the badge \`0\`? The input dataset has no image or video assets. The output dataset is still created or versioned, but stays empty. #### Why can't the node load the selected model? The model's task type must be object detection or instance segmentation, and the checkpoint's own task must match it. The version must also have weights: a checkpoint in its asset, or a checkpoint name Ultralytics can download. Register a working checkpoint with [Upload model](/node-library/nodes/models-general-upload-model) if the version has none. #### Why does prediction fail when inference starts? **Config** may not be a YAML mapping, `batch` may be below `1`, or an Ultralytics argument may be unsupported or conflict with a value set by the node, such as `source`. Fix the YAML and remove conflicting arguments. ## Inputs **`Dataset`** `dataset` — required Dataset to run the model on. The output dataset holds these same assets (same ids, not copies) with the predictions, so this dataset keeps its annotations. An empty dataset gives an empty output and the run still succeeds. Key: `DATASET`. --- **`Destination dataset`** `dataset` Dataset the predictions are added to, keeping what it already holds. An image it already annotates gets the new prediction instead. Leave empty to use the node's own output dataset, which a rerun writes a new version of. Key: `DST_DATASET`. --- **`Model`** `model` — required Model to run inference with, trained in this workspace or installed from the zoo. Whether the run produces boxes or masks follows the model you pick. Key: `MODEL`. --- **`Predict classes`** `ontology` — required Classes to keep in the predictions. Leave empty to keep everything the model detects. Values come from `MODEL`. Key: `CLASSES`. --- **`Config`** `yaml` — required Ultralytics prediction settings in YAML - confidence threshold, image size, batch size and the rest. Where images are read from and whether results are saved to disk are set for you. Key: `CONFIG`. --- **`Download batch size`** `integer` — required, default: 64 Number of assets downloaded at once while the model works through the previous ones. Raise it when downloading cannot keep up with inference. Minimum: `1`. Key: `DOWNLOAD_BATCH_SIZE`. --- **`Prefetch batches`** `integer` — required, default: 4 How many batches of downloaded assets may wait on local disk ahead of the model. Higher values ride out slow downloads at the cost of disk space. Minimum: `1`. Key: `PREFETCH_BATCHES`. --- ## Outputs **`Output Dataset`** `dataset` Dataset with the input images plus the YOLO prediction annotations: the destination dataset when one is picked, otherwise the node's own. Shown as an artifact. Key: `OUTPUT_DATASET`. --- **`Prediction Count`** `string` Badge showing the number of images annotated. Shown on the node as a badge. Selecting the badge opens `OUTPUT_DATASET`. Key: `PRED_COUNT`. --- ## Models and configuration **Model** picks the version used for inference. The picker lists the workspace's YOLO models and their ready versions. Picking the model itself follows its newest ready version at every run, and picking a version pins it. #### Checkpoint and class selection details A version produced by training or registered by upload runs 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. **Predict classes** lists the classes of the model's ontology. Tick the ones to keep, or leave it empty to keep every class the model predicts. #### Default inference settings OvalBee starts with these values in **Config**: | Setting | Default | Meaning | | --------- | ------: | ------------------------------------- | | `batch` | `16` | Image inference batch size | | `imgsz` | `640` | Inference image size | | `conf` | `0.25` | Minimum detection confidence | | `iou` | `0.7` | Non-maximum suppression IoU threshold | | `max_det` | `300` | Maximum detections per image | | `verbose` | `false` | Ultralytics prediction logging | #### Advanced inference settings **Config** must be a YAML mapping. Other valid Ultralytics prediction arguments pass through under these rules: * `batch` must be at least 1. It controls the image inference batches and is removed for video inference. * The node always sets `save`, `save_txt`, and `save_conf` to `false` because results are uploaded as OvalBee annotations rather than written as Ultralytics output files. * Instance segmentation runs always return masks at the original image resolution. * The node supplies the current image batch or video as `source`, so don't set `source` yourself. * **Download batch size**, default `64`, controls how many image assets are requested in each download group. * **Prefetch batches**, default `4`, bounds the queued image downloads and uploads. Neither setting affects video inference. ## Runtime GPU memory use depends on the model, image size, and inference 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 component: OvalBee SDK for downloading assets and uploading annotations. * 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": "Predict YOLO", "description": "Run a YOLO detection or instance segmentation model on a dataset and write the images with their predictions to the output dataset.", "category": "Predict", "namespace": "ovalbee", "templateKey": "models/yolo/predict_yolo", "version": "v1", "inputs": [ { "key": "DATASET", "label": "Dataset", "type": "dataset", "description": "Dataset to run the model on. The output dataset holds these same assets (same ids, not copies) with the predictions, so this dataset keeps its annotations. An empty dataset gives an empty output and the run still succeeds.", "required": true, "default": null, "visibleWhen": null, "options": { "creatable": false } }, { "key": "DST_DATASET", "label": "Destination dataset", "type": "dataset", "description": "Dataset the predictions are added to, keeping what it already holds. An image it already annotates gets the new prediction instead. Leave empty to use the node's own output dataset, which a rerun writes a new version of.", "required": false, "default": null, "visibleWhen": null }, { "key": "MODEL", "label": "Model", "type": "model", "description": "Model to run inference with, trained in this workspace or installed from the zoo. Whether the run produces boxes or masks follows the model you pick.\n", "required": true, "default": null, "visibleWhen": null, "options": { "framework": "yolo" } }, { "key": "CLASSES", "label": "Predict classes", "type": "ontology", "description": "Classes to keep in the predictions. Leave empty to keep everything the model detects.", "required": true, "default": null, "visibleWhen": null, "options": { "ref": "MODEL", "selectable": true } }, { "key": "CONFIG", "label": "Config", "type": "yaml", "description": "Ultralytics prediction settings in YAML - confidence threshold, image size, batch size and the rest. Where images are read from and whether results are saved to disk are set for you.", "required": true, "default": "batch: 16\nimgsz: 640\nconf: 0.25\niou: 0.7\nmax_det: 300\nverbose: false\n", "visibleWhen": null }, { "key": "DOWNLOAD_BATCH_SIZE", "label": "Download batch size", "type": "number", "description": "Number of assets downloaded at once while the model works through the previous ones. Raise it when downloading cannot keep up with inference.", "required": true, "default": 64, "visibleWhen": null, "options": { "type": "integer", "min": 1 } }, { "key": "PREFETCH_BATCHES", "label": "Prefetch batches", "type": "number", "description": "How many batches of downloaded assets may wait on local disk ahead of the model. Higher values ride out slow downloads at the cost of disk space.", "required": true, "default": 4, "visibleWhen": null, "options": { "type": "integer", "min": 1 } } ], "outputs": [ { "key": "OUTPUT_DATASET", "label": "Output Dataset", "type": "dataset", "description": "Dataset with the input images plus the YOLO prediction annotations: the destination dataset when one is picked, otherwise the node's own.", "artifact": true, "badge": false, "badgeOpens": null, "hidden": false }, { "key": "PRED_COUNT", "label": "Prediction Count", "type": "string", "description": "Badge showing the number of images annotated.", "artifact": false, "badge": true, "badgeOpens": "OUTPUT_DATASET", "hidden": false } ], "runtime": { "type": "docker", "devices": [ "gpu", "cpu" ], "dockerImage": "ovalbee/node-yolo:0.0.21" }, "widgets": { "widget": { "id": "asset-preview", "settings": { "datasetId": { "type": "variable", "value": "self.outputs.OUTPUT_DATASET" } } } } } ``` ## References #### Sources and related pages * [Evaluate object detection](/node-library/nodes/evaluate-evaluate-object-detection) * [Train YOLO](/node-library/nodes/models-yolo-train-yolo) * [Ultralytics repository at v8.4.33](https://github.com/ultralytics/ultralytics/tree/v8.4.33) * [Prediction mode documentation at v8.4.33](https://github.com/ultralytics/ultralytics/blob/v8.4.33/docs/en/modes/predict.md) * [Configuration 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)