> 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 DEIM > Train a DEIM object detection 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 DEIM object detector from your workspace registry on OvalBee datasets, and registers the result as a new version of that model. The node exports the train and validation datasets to COCO format inside its own working directory, trains on them, and uploads the checkpoints to the new version, so no conversion or upload node sits in between. The run publishes a live report that updates while it goes, and the **Best Loss** badge shows the lowest training loss reached. DEIM covers three architecture families, from tiny HGNetV2 variants that suit an edge device to DINOv3 backbones that trade speed for accuracy. Every entry is Apache-2.0, DEIMv2 included: its weights are the ones it published before it moved to a non-commercial license. The DINOv3 entries are built with DINOv3 and also carry Meta's [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/) for their backbone. ```mermaid flowchart LR n1["Dataset"] --> n2["Train/validation split"] --> n3["Train DEIM"] --> n4["Model version"] ``` #### Pretrained Models * DEIMv2 HGNetV2-Atto * DEIMv2 HGNetV2-Femto * DEIMv2 HGNetV2-Pico * DEIMv2 HGNetV2-N * DEIMv2 DINOv3-S * DEIMv2 DINOv3-M * DEIMv2 DINOv3-L * DEIMv2 DINOv3-X * D-FINE HGNetV2-N * D-FINE HGNetV2-S * D-FINE HGNetV2-M * D-FINE HGNetV2-L * D-FINE HGNetV2-X * RT-DETRv2-S (r18vd) * RT-DETRv2-M (r34vd) * RT-DETRv2-M\* (r50vd_m) * RT-DETRv2-L (r50vd) * RT-DETRv2-X (r101vd) ## Prerequisites | Requirement | What you need | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GPU worker** | A worker with a GPU. | | **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). The node refuses to start if the datasets hold no annotation classes. | | **DEIM model** | A DEIM detection model in the workspace registry: a catalog architecture copied in from the **Model** picker, or a version from an earlier training run. | #### What the node builds ```text 📁 task working directory/ ├── 📁 dataset/ ← the COCO export │ ├── 📄 data.yaml │ ├── 📁 images/{train,val}/ │ └── 📁 annotations/{train,val}.json └── 📁 artifacts/ ← checkpoints, logs, the training config ``` Both directories are ephemeral: they live only for the duration of the task, and the checkpoints are uploaded to the model version before it ends. A rerun exports its datasets again. ## How it works Exports the train and validation datasets to COCO format in one pass, so both splits share the same class index space. Loads the starting weights: the picked version's own checkpoint, or the public COCO weights of its architecture for a catalog model. Builds the training config from the architecture, the class count, and your **Hyperparameters**. Trains with DEIM. 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 for the report, then uploads the final checkpoints and metrics and marks the version ready. ## FAQ #### Do I need a conversion node in front of this one? No. The node exports its datasets to COCO itself. Connect the datasets directly. DEIM trains on bounding boxes, so polygon and mask annotations are used through their bounding boxes. #### 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 continues from the previous run's result. #### Where do the trained files end up? On the new model version: the best and last checkpoints (not the periodic ones DEIM writes as it goes), the training config the weights need at prediction time, the training log, and your hyperparameters. The version also records the class list, both datasets, the version training started from, the training report, and the last epoch's mAP50, mAP50-95, and training loss. #### What happens if training fails partway through? The version receives the latest best and last checkpoints about every two minutes, so a run that fails keeps what it uploaded. Its version is marked failed and 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 if I leave the validation dataset empty? The export points validation at the training images, so the mAP the run reports is measured on data the model trained on and reads higher than it will score on new images. #### 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. The class list is also stored inside the checkpoints, so prediction names classes the same way. #### Which architecture should I start with? One of the small HGNetV2 variants when you need speed or an edge deployment, and a DINOv3 backbone when accuracy matters more than latency. The DINOv3 entries come with the DINOv3 License on top of Apache-2.0. #### Why does the run stop with an out-of-memory error? The architecture, `batch_size`, and `eval_spatial_size` together decide GPU memory. Lower the batch size first, then the input size, before moving to a smaller backbone. #### Why did the run fail right at the start? Usually the datasets, the model, or the config. The datasets have to carry annotation classes, the picked version has to name one of the DEIM architectures listed above, and **Hyperparameters** has to be YAML whose keys the trainer accepts. ## Inputs **`Train dataset`** `dataset` — required Dataset the model learns from. Its annotations define the classes the trained model will detect. Key: `TRAIN_DATASET`. --- **`Validation dataset`** `dataset` — required Dataset held back to measure accuracy after each epoch. Leave it empty and accuracy is measured on the training assets instead, which makes the reported mAP look better than it is. Key: `VAL_DATASET`. --- **`Model`** `model` — required Model to fine-tune. A version copied from the zoo starts from the public COCO weights of that architecture. One from an earlier run continues from its checkpoint. The run is registered as a new version of this model unless Destination Model names another one. Key: `MODEL`. --- **`Destination model`** `model` Model the new trained version is added to, when it should not go to the model you are training. Leave empty to add it to the Model above. Key: `DESTINATION_MODEL`. --- **`Hyperparameters`** `yaml` — required Training settings in YAML - how many epochs to run, batch size, learning-rate schedule and augmentation. Dataset paths and the number of classes are filled in for you. Key: `CONFIG`. --- ## Outputs **`Report Asset`** `report` ID of the asset containing the live DEIM 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, evaluate or export 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. A version copied from the catalog has no weights of its own, so the run downloads the public COCO weights of that architecture. One produced by an earlier run continues from its checkpoint. Either way the new version records the picked version as its starting point. 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 DEIM detection models of this workspace, and only their ready versions. **Hyperparameters** is the DEIM training config as YAML. The dataset paths and the class count are injected by the node from its own export, so leave those out and set what you want to change: `epoches` for run length, `batch_size` for memory, `eval_spatial_size` for input resolution. Nested keys merge into the architecture's base config rather than replacing whole sections. The defaults are a full training schedule, including the augmentation policy, the EMA settings, and the learning-rate curve. Removing a key restores the architecture's own default rather than disabling the feature. ## Report The report appears near the start of the run and updates as training produces results. It opens from the node. #### Report sections | Section | What it shows | | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Overview** | The model, parameter count, starting checkpoint, configured epochs, elapsed time, dataset sizes, and classes. | | **Predictions** | The best checkpoint applied to a fixed sample of up to eight validation images, added after training. | | **Evaluation metrics** | mAP50-95, AP50, AP75, and AR\@100 from the best validation epoch. | | **Training plots** | The loss, COCO metric, and learning-rate series recorded during the run. | | **TensorBoard** | The raw TensorBoard event stream. Empty until DEIM writes events. | | **Artifacts** | The checkpoints written so far, replaced by a checkpoint download panel once the run finishes. | | **Classes** | Each class with its model output index. | | **Hyperparameters** | The **Hyperparameters** YAML as the node read it. | | **How to use the trained model** | A short local example that loads the checkpoint and predicts an image. | ## Runtime The node runs in its own GPU container. Memory use follows the architecture, the input size, and the batch size, so a model that won't fit is the first thing to check when a run dies early. The first run takes longer while the worker pulls the image, and a catalog model downloads its pretrained weights on every run that starts from it. Every run exports its datasets before training starts, so a large dataset adds a download phase ahead of the first epoch. ## JSON config Machine-readable node interface for automation and advanced usage. #### Show JSON ```json { "name": "Train DEIM", "description": "Train a DEIM object detection model directly on OvalBee datasets.", "category": "Train", "namespace": "ovalbee", "templateKey": "models/deim/train_deim", "version": "v1", "inputs": [ { "key": "TRAIN_DATASET", "label": "Train dataset", "type": "dataset", "description": "Dataset the model learns from. Its annotations define the classes the trained model will detect.", "required": true, "default": null, "visibleWhen": null, "options": { "creatable": false } }, { "key": "VAL_DATASET", "label": "Validation dataset", "type": "dataset", "description": "Dataset held back to measure accuracy after each epoch. Leave it empty and accuracy is measured on the training assets instead, which makes the reported mAP look better than it is.", "required": true, "default": null, "visibleWhen": null, "options": { "creatable": false } }, { "key": "MODEL", "label": "Model", "type": "model", "description": "Model to fine-tune. A version copied from the zoo starts from the public COCO weights of that architecture. One from an earlier run continues from its checkpoint. The run 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": "deim", "task_type": "object_detection" } }, { "key": "DESTINATION_MODEL", "label": "Destination model", "type": "model", "description": "Model the new trained version is added to, when it should not go to the model you are training. Leave empty to add it to the Model above.\n", "required": false, "default": null, "visibleWhen": null, "options": { "scope": "my", "framework": "deim", "task_type": "object_detection" } }, { "key": "CONFIG", "label": "Hyperparameters", "type": "yaml", "description": "Training settings in YAML - how many epochs to run, batch size, learning-rate schedule and augmentation. Dataset paths and the number of classes are filled in for you.", "required": true, "default": "epoches: 58\nbatch_size: 8\neval_spatial_size: [640, 640]\ncheckpoint_freq: 5\nsave_optimizer: false\noptimizer:\n type: AdamW\nclip_max_norm: 0.2\nlrsheduler: flatcosine\nwarmup_iter: 200\nflat_epoch: 29\nno_aug_epoch: 8\nuse_ema: true\nema:\n type: ModelEMA\n decay: 0.9999\n warmups: 200\nuse_amp: true\ntrain_dataloader:\n dataset:\n transforms:\n policy:\n epoch: [4, 29, 50]\n mosaic_prob: 0.0\n collate_fn:\n stop_epoch: 50\n mixup_prob: 0.0\n mixup_epochs: [4, 29]\n copyblend_prob: 0.0\n copyblend_epochs: [4, 50]\nDEIMCriterion:\n matcher:\n matcher_change_epoch: 45\n", "visibleWhen": null } ], "outputs": [ { "key": "REPORT_ID", "label": "Report Asset", "type": "report", "description": "ID of the asset containing the live DEIM 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, evaluate or export 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-deim:0.0.24" }, "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 * [Predict DEIM](/node-library/nodes/models-deim-predict-deim) runs the trained model over a dataset. * [Export DEIM](/node-library/nodes/models-deim-export-deim) converts the trained checkpoint to deployment formats. * [DEIM](https://github.com/ShihuaHuang95/DEIM) is the upstream training framework.