> 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. # Upload model > Upload a local .pt or .pth checkpoint and register it as a new version in the workspace model registry. ## Overview Registers a PyTorch checkpoint from your machine as a new version in the workspace model registry. Drop a `.pt` or `.pth` file onto the node, say what the model does, and the run turns it into a registered model version that the predict, train, and export nodes of its framework can pick. ```mermaid flowchart LR n1["Checkpoint file"] --> n2["Upload model"] --> n3["Model version"] ``` ## Prerequisites | Requirement | What you need | | ------------------- | ----------------------------------------------------- | | **Checkpoint file** | A PyTorch `.pt` or `.pth` file on your local machine. | ## How it works Stages the checkpoint you drop onto the node in workspace storage. Scans that location and keeps every `.pt` and `.pth` file it finds. Marks which checkpoint to load later and stores the files as the model's weights. Registers them as a new version under the task type, classes, and **Model info** fields you gave, so the model pickers can find it, and returns the version on **Model**. ## FAQ #### Which model does the new version belong to? The one named by `model_name` in **Model info**, or by the checkpoint's filename when that is empty. If the workspace already has a model with that name, the upload is added to it as its next version, otherwise a new model is created. Every run registers a new version, even when you upload the same file again. #### Why did the run fail with 'No checkpoint uploaded'? The node was started before any file was dropped onto it. Drop a `.pt` or `.pth` file on the node: the upload starts the run by itself. #### Task type is marked optional, so why does the run fail without it? The field is optional in the interface but the run rejects an empty value. Downstream nodes match a model by its task, so a model registered without one cannot be picked. #### Which checkpoint gets marked as the best one? A single uploaded file is always the best one. Upload several and the ones whose filename contains `best` are marked instead. When several files are uploaded and none matches, no checkpoint is marked and the run logs a warning. #### Why did the run fail with no checkpoint found? The uploaded folder holds no `.pt` or `.pth` file. Other formats, including ONNX and TensorRT exports, are not accepted here. #### How should I fill Classes? Pick the ontology whose classes the model predicts, and tick a subset only when the model predicts just those. Picking the ontology without ticking anything takes all of its classes. They are stored in the ontology's order, which has to match the order the model outputs them in, because predictions are named by position. A classification model's classes are stored as tags, every other task's as object classes. #### What can I put in Model info? A YAML mapping. `model_name`, `framework`, `baseline_model`, and `img_size` are recognized: `model_name` names the model in the registry, and `baseline_model` is the upstream architecture the checkpoint was fine-tuned from (`yolo11m`), which is what the predict and train nodes rebuild it with. Any other key is kept with the files as extra info, verbatim. Content that is not valid YAML is ignored, and the run then fails because `framework` is missing. #### Why does Framework matter? The model pickers of the predict, train, and export nodes filter on it, so a model without the right framework can't be picked anywhere. Leave it empty and the run fails, so fill it with the framework the checkpoint was trained with, such as `yolo` or `deim`. What you type is turned into that key: `YOLOv8` and `Grounding DINO` are registered as `yolo` and `grounding_dino`. #### Which frameworks work with an uploaded checkpoint? A YOLO checkpoint carries everything [Predict YOLO](/node-library/nodes/models-yolo-predict-yolo) and [Train YOLO](/node-library/nodes/models-yolo-train-yolo) need. DEIM and EdgeCrafter prediction also read the training config stored with a trained version, which an upload doesn't include, so use such a checkpoint as a starting point for training. For those frameworks, `baseline_model` must name the architecture exactly as the train node knows it, e.g. `deim_dfine_l` or `ecdet_s`. ## Inputs **`Classes`** `ontology` Classes the uploaded model predicts, stored with it in the registry. Key: `CLASSES`. --- **`Task type`** `select` Task the model performs. Upload fails without it, since the nodes that take a model select by task. Key: `TASK_TYPE`. Options: * Object Detection (`object_detection`) * Classification (`classification`) * Semantic Segmentation (`semantic_segmentation`) * Instance Segmentation (`instance_segmentation`) --- **`Model info`** `yaml` Details of the uploaded model in YAML. Framework is required - predict, train and export nodes filter on it, so a model without one cannot be picked anywhere. Key: `MODEL_INFO`. --- ## Outputs **`Storage path`** `string` Internal storage prefix of the staged checkpoint, written by the drag-and-drop widget. Hidden from the flow editor. Key: `STORAGE_PATH`. --- **`Model`** `model` Reference to the registry version created for the uploaded checkpoint, as `<model id>@<version id>`. It wires into the Model input of a predict, train, export or evaluate node and pins it to exactly these weights. Shown as an artifact. Key: `MODEL`. --- ## JSON config Machine-readable node interface for automation and advanced usage. #### Show JSON ```json { "name": "Upload model", "description": "Upload a local .pt or .pth checkpoint and register it as a new version in the workspace model registry.", "category": "Models", "namespace": "ovalbee", "templateKey": "models/general/upload_model", "version": "v1", "inputs": [ { "key": "CLASSES", "label": "Classes", "type": "ontology", "description": "Classes the uploaded model predicts, stored with it in the registry.", "required": false, "default": null, "visibleWhen": null, "options": { "selectable": true } }, { "key": "TASK_TYPE", "label": "Task type", "type": "select", "description": "Task the model performs. Upload fails without it, since the nodes that take a model select by task.", "required": false, "default": null, "visibleWhen": null, "options": { "options": [ { "label": "Object Detection", "value": "object_detection" }, { "label": "Classification", "value": "classification" }, { "label": "Semantic Segmentation", "value": "semantic_segmentation" }, { "label": "Instance Segmentation", "value": "instance_segmentation" } ] } }, { "key": "MODEL_INFO", "label": "Model info", "type": "yaml", "description": "Details of the uploaded model in YAML. Framework is required - predict, train and export nodes filter on it, so a model without one cannot be picked anywhere.", "required": false, "default": "model_name: # names the model in the registry; the checkpoint filename if empty\nframework: # e.g. yolo, deim, timm\nbaseline_model: # e.g. yolo11m\nimg_size: # input image size, e.g. 640", "visibleWhen": null } ], "outputs": [ { "key": "STORAGE_PATH", "label": "Storage path", "type": "string", "description": "Internal storage prefix of the staged checkpoint, written by the drag-and-drop widget.", "artifact": false, "badge": false, "badgeOpens": null, "hidden": true }, { "key": "MODEL", "label": "Model", "type": "model", "description": "Reference to the registry version created for the uploaded checkpoint, as `@`. It wires into the Model input of a predict, train, export or evaluate node and pins it to exactly these weights.\n", "artifact": true, "badge": false, "badgeOpens": null, "hidden": false } ], "runtime": { "type": "python", "devices": [ "cpu" ], "dockerImage": null }, "widgets": { "widget": { "id": "import-drag-drop", "settings": {} } } } ```