Node LibraryTrain

Train EdgeCrafter

GPU Dockerfile
First run can take longer while the worker pulls the configured Docker image.

Overview

Fine-tunes an EdgeCrafter detector or instance segmenter from your workspace registry on OvalBee datasets, and registers the result as a new version of that model. The node converts the datasets to COCO itself, so nothing has to prepare a directory for it first.

The model you pick decides the task: an ECDet architecture trains detection on boxes, an ECSeg one instance segmentation on masks. The architectures target edge deployment, where a smaller model that keeps up with the camera beats a larger one that does not. All EdgeCrafter checkpoints are under EdgeCrafter’s own license: free for research, while commercial use needs a separate grant.

During training the node publishes a live report with training status, loss and metric charts, class information, checkpoints, TensorBoard data, and a prediction gallery. The Best mAP badge shows the best validation mAP50-95 reached: box mAP for detection, mask mAP for segmentation.

Dataset Train/validation split Train EdgeCrafter Model version
  • EdgeCrafter ECDet-S
  • EdgeCrafter ECDet-M
  • EdgeCrafter ECDet-L
  • EdgeCrafter ECDet-X
  • EdgeCrafter ECSeg-S
  • EdgeCrafter ECSeg-M
  • EdgeCrafter ECSeg-L
  • EdgeCrafter ECSeg-X

Prerequisites

RequirementWhat you need
GPU workerA worker with a GPU.
Annotated datasetsA train and a validation dataset with objects labelled with the classes you want the model to learn, holding different images, e.g. the outputs of Train/validation split. Instance segmentation needs mask or polygon annotations, not just boxes.
EdgeCrafter modelAn EdgeCrafter model in the workspace registry: a catalog architecture copied in from the Model picker, or a version from an earlier training run.
📁 dataset/
├── 📄 data.yaml
├── 📁 images/
│   ├── 📁 train/
│   └── 📁 val/
└── 📁 annotations/
    ├── 📄 train.json
    └── 📄 val.json

Both datasets are converted in one pass so the two splits share a class index space. The tree lives in the task’s own storage and is rebuilt on every run.

How it works

1

Downloads both datasets and converts them to COCO, with instance masks when the picked model is a segmentation one.

2

Loads the starting weights: the picked version’s own checkpoint, or the public COCO weights of its architecture for a catalog model.

3

Checks and prepares the annotations, then builds the training config from the architecture, the class count, and your Hyperparameters.

4

Trains with EdgeCrafter. The new version is created as training starts and receives checkpoints while the run goes, and the live report updates beside it.

5

Predicts on up to eight validation images for the report, then uploads the final checkpoints and metrics and marks the version ready.

FAQ

No. Point Train dataset at the dataset you want to train on and the node handles the conversion.

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.

On the new model version: the best and last checkpoints, each carrying the class list, plus the training config, 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 metrics: mAP50 and mAP50-95 for detection, mask mAP50 and mask mAP50-95 for segmentation.

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.

Detection predicts boxes and segmentation predicts per-instance masks, which needs mask annotations in the datasets and costs more to train and to evaluate. The task follows the picked architecture, so switching task means picking an ECSeg model instead of an ECDet one, or the other way round.

Evaluate every N epochs defaults to 5, because segmentation evaluation upsamples every predicted mask to full resolution and can cost more than the epoch it follows. The final epoch is always evaluated. Set it to 1 to evaluate after every epoch.

Usually the datasets, the model, or the config. The datasets have to carry annotations with class names, and a segmentation model needs masks, not only boxes. The picked version has to name one of the EdgeCrafter architectures listed above, and Hyperparameters has to be YAML whose keys the trainer accepts.

Inputs

Train dataset
datasetRequired

Dataset to train on. The node converts it to COCO format itself, so no conversion step is needed upstream. Key: TRAIN_DATASET.

Validation dataset
datasetRequired

Dataset to evaluate on after every epoch. Exported in the same pass as the training one, so both splits share one class index space. Key: VAL_DATASET.

Model
modelRequired

Model to fine-tune, and with it the task: an ECDet version trains detection, an ECSeg one instance segmentation. 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

Where the trained version is registered, when it should not go to the model being trained. Leave empty to add the version to the Model above. Key: DESTINATION_MODEL.

Evaluate every N epochs
integerDefaults to 5Required

How often validation runs. Segmentation evaluation upsamples every predicted mask to the full image resolution, so on large images one pass can cost far more than the training epoch it follows. The final epoch is always evaluated, so the run’s reported metrics are unaffected. Set to 1 to evaluate after every epoch. Minimum: 1. Key: EVAL_INTERVAL.

Hyperparameters
yamlRequired

Training hyperparameters in YAML - how long the run trains, at what batch size and resolution, and which optimizer settings it uses. Your datasets and their classes are filled in for you. Key: CONFIG.

Outputs

Report Asset
report

ID of the asset containing the live EdgeCrafter 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 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 mAP
string

Best validation mAP (IoU 0.5:0.95) reached during the run, box mAP for detection and mask mAP for segmentation (shown as a badge). Shown on the node as a badge. Key: BEST_MAP.

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 EdgeCrafter models of this workspace, and only their ready versions.

Hyperparameters holds the training settings as YAML. Dataset paths and the class count are injected by the node, so set only what you want to change.

Report

The report appears near the start of the run and updates as training produces results. It opens from the node.

SectionWhat it shows
OverviewThe model, parameter count, starting checkpoint, configured epochs, elapsed time, dataset sizes, and classes.
PredictionsThe best checkpoint applied to a fixed sample of up to eight validation images, added after training.
Evaluation metricsBox mAP50-95, AP50, AP75, and AR@100 for detection, or mask mAP50-95, AP50, and AP75 for segmentation, from the best validation epoch.
Training plotsThe loss, metric, and learning-rate series recorded during the run.
TensorBoardThe raw TensorBoard event stream.
ArtifactsThe checkpoints written so far, replaced by a checkpoint download panel once the run finishes.
ClassesThe class names the run trained on.
HyperparametersThe Hyperparameters YAML as the node read it, with the evaluation interval added.
How to use the trained modelA 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.

JSON config

Machine-readable node interface for automation and advanced usage.

{
  "name": "Train EdgeCrafter",
  "description": "Train an EdgeCrafter object detection or instance segmentation model directly from OvalBee datasets.",
  "category": "Train",
  "namespace": "ovalbee",
  "templateKey": "models/edgecrafter/train_edgecrafter",
  "version": "v1",
  "inputs": [
    {
      "key": "TRAIN_DATASET",
      "label": "Train dataset",
      "type": "dataset",
      "description": "Dataset to train on. The node converts it to COCO format itself, so no conversion step is needed upstream.",
      "required": true,
      "default": null,
      "visibleWhen": null,
      "options": {
        "creatable": false
      }
    },
    {
      "key": "VAL_DATASET",
      "label": "Validation dataset",
      "type": "dataset",
      "description": "Dataset to evaluate on after every epoch. Exported in the same pass as the training one, so both splits share one class index space.",
      "required": true,
      "default": null,
      "visibleWhen": null,
      "options": {
        "creatable": false
      }
    },
    {
      "key": "MODEL",
      "label": "Model",
      "type": "model",
      "description": "Model to fine-tune, and with it the task: an ECDet version trains detection, an ECSeg one instance segmentation. 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": "edgecrafter"
      }
    },
    {
      "key": "DESTINATION_MODEL",
      "label": "Destination model",
      "type": "model",
      "description": "Where the trained version is registered, when it should not go to the model being trained. Leave empty to add the version to the Model above.\n",
      "required": false,
      "default": null,
      "visibleWhen": null,
      "options": {
        "scope": "my",
        "framework": "edgecrafter"
      }
    },
    {
      "key": "EVAL_INTERVAL",
      "label": "Evaluate every N epochs",
      "type": "number",
      "description": "How often validation runs. Segmentation evaluation upsamples every predicted mask to the full image resolution, so on large images one pass can cost far more than the training epoch it follows. The final epoch is always evaluated, so the run's reported metrics are unaffected. Set to 1 to evaluate after every epoch.",
      "required": true,
      "default": 5,
      "visibleWhen": null,
      "options": {
        "type": "integer",
        "min": 1
      }
    },
    {
      "key": "CONFIG",
      "label": "Hyperparameters",
      "type": "yaml",
      "description": "Training hyperparameters in YAML - how long the run trains, at what batch size and resolution, and which optimizer settings it uses. Your datasets and their classes are filled in for you.\n",
      "required": true,
      "default": "epochs: 74\nbatch_size: 8\neval_spatial_size: [640, 640]\nwarmup_iter: 2000\nuse_amp: true\noptimizer:\n  type: AdamW\n  lr: 0.0005\n  weight_decay: 0.0001\n",
      "visibleWhen": null
    }
  ],
  "outputs": [
    {
      "key": "REPORT_ID",
      "label": "Report Asset",
      "type": "report",
      "description": "ID of the asset containing the live EdgeCrafter 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 `<model id>@<version id>`. It wires into the Model input of a predict 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_MAP",
      "label": "Best mAP",
      "type": "string",
      "description": "Best validation mAP (IoU 0.5:0.95) reached during the run, box mAP for detection and mask mAP for segmentation (shown as a badge).",
      "artifact": false,
      "badge": true,
      "badgeOpens": null,
      "hidden": false
    }
  ],
  "runtime": {
    "type": "docker",
    "requiresGpu": true,
    "dockerImage": "cr.internal.supervisely.com/ovalbee-internal/nodes/edgecrafter:0.0.14"
  },
  "widgets": {
    "widget": {
      "id": "report-preview",
      "settings": {
        "reportAsset": {
          "type": "variable",
          "value": "self.outputs.REPORT_ID"
        },
        "name": {
          "type": "input",
          "value": "Open training report"
        }
      }
    }
  }
}

References