--- updatedAt: 2026-10-07T12:47:22.000Z agentTools: projectIndex: https://documentation.picsellia.com/llms.txt --- # Create a ModelVersion manually There are two ways to create a new `ModelVersion` on Picsellia: * Automatically by exporting an `Experiment` as explained [here](https://documentation.picsellia.com/docs/experiment-export-as-a-model#a-new-model) * Manually in the *Private Model Registry* This page will focus on the manual creation of a `ModelVersion` directly from the *Private Model Registry* of your *Organization*. ## 1. Access a `Model` First of all, you need to access the `Model` under which you want to create a `ModelVersion`. From your *Private Model Registry*, click on this `Model`.

The list of existing `ModelVersion` will then be displayed. From this *ModelVersion list*, the creation of a new `ModelVersion` can be initialized by clicking on *+ New Version*.

## 2. *ModelVersion creation form* The *ModelVersion creation form* will then open. This form allows you to define the main characteristics of your `ModelVersion`. You will be requested to fill in the following fields: * *Name* * *Description* (optional) * Picture (optional) * *Type* * *Framework* (optional) * `LabelMap` (optional) * *Parameters* (optional) * *Docker* information: Image, Tag, Flags, and Environment variables (optional)

### The blue _+_ button Please note that while filling out this form, when adding a new `Label`, _Parameter_, _Flag_ or _Environment variable_, you need to click on the blue _+_ button after having typed the value in the related text holder, to ensure this new value is well taken into account. Once the form is filled, click on *Create* and you will land on the *ModelVersion overview* of the freshly created `ModelVersion`. ### No _Source Experiment_ As the `ModelVersion` has been created manually from scratch in your _Private Model Registry_, the _Source Experiment_ section will remain empty. This placeholder displays the `Experiment` the current `ModelVersion` has been exported from, but this `ModelVersion` has not been exported from a Picsellia `Experiment`. More details about the elements that composed a `ModelVersion` are detailed in this [page](https://documentation.picsellia.com/docs/registry-model-version). ## 3. How a `ModelVersion` is used A `ModelVersion` is more than a set of files. It can be used in two ways, which are not exclusive: as a model in its own right, ready to be deployed, and as the starting point of a future training. Understanding these mechanics tells you what to fill in the *ModelVersion creation form*, and what must be consistent for the `ModelVersion` to work as expected. ### A. As a model, ready to be deployed A `ModelVersion` is, first of all, a model: a performant model that you can deploy and use to make predictions, thanks to its *Model files* (weights, configuration, and so on). Depending on where you want it to run, you can deploy it: * On the *Picsellia Serving* engine, where Picsellia handles the whole deployment workflow for you. * On your own infrastructure, whether it runs at the edge or in the cloud, by downloading the *Model files* and serving the model yourself. In both cases, you can connect the deployed model to a `Deployment` to monitor it and visualize its predictions. The two options are detailed in [Deploy a ModelVersion](https://documentation.picsellia.com/docs/registry-deploy-a-model). ### B. As *Base architecture* of a next training A `ModelVersion` can also be selected as the *Base architecture* of a new `Experiment`, to train a new `ModelVersion` from it. In that case, Picsellia relies on several of its elements to prepare and run the training: #### a. The *Docker image*: where the *training script* lives The *Docker image* associated with a `ModelVersion` contains the *training script*. When the `ModelVersion` is used as *Base architecture* and the training is launched from the `Experiment` (on the *Picsellia training engine*, through a *Compute Connector*, or on your own resources, as detailed [here](https://documentation.picsellia.com/docs/experiment-launch-training)), this is the image that Picsellia runs, with the *Tag*, *Flags*, and *Environment variables* you defined. The *Docker image* is therefore what makes a `ModelVersion` trainable from Picsellia. It is optional if you only want to store or deploy the `ModelVersion`, but it must be filled in, and accessible from the computing resource that runs the training, for the `ModelVersion` to be trained through an `Experiment`. #### b. *Parameters*: the inputs your *training script* expects The *Parameters* of a `ModelVersion` are the list of training parameters, each with its value, that Picsellia exposes to the user when the `ModelVersion` is used as *Base architecture*: they are pre-filled as editable *Hyperparameters* in the *Experiment creation form*, as detailed [here](https://documentation.picsellia.com/docs/experiments-creation#b-hyperparameters). The values you enter on the `ModelVersion` are the **default values**. The user of the `ModelVersion` can modify them when creating the `Experiment`. Whatever the values are, Picsellia provides these parameters to the *training script* when the image is executed. The script must therefore expect them and handle them properly: the list of *Parameters* you define should match exactly the parameters your script reads, with default values that make it work. A missing or unexpected parameter can make the training fail or behave unexpectedly. #### c. The `LabelMap`: a starting point, updated with the `DatasetVersion` The `LabelMap` of a `ModelVersion` is the `Label` (and their indexes) the model was built around. When the `ModelVersion` is used as *Base architecture*, it is inherited by the `Experiment`, then updated with the `LabelMap` of the `DatasetVersion` attached to the `Experiment`. Your *training script* must therefore be able to work with a `LabelMap` that differs from the one of the `ModelVersion`, for instance with a different number of classes. The `ModelVersion` later exported from the `Experiment` carries the updated `LabelMap`, which is why it matches the `DatasetVersion` used for its training. #### d. *Dataset Constraints*: securing the `DatasetVersion` given to the script A *training script* usually expects a precise set of `DatasetVersion`: for instance one aliased *train* and one aliased *eval*. *Dataset Constraints* let you declare this expectation on the `ModelVersion`: each constraint defines the number of `DatasetVersion` and the alias of each one. When the `ModelVersion` is used as *Base architecture*, these constraints ensure that the number and the aliases of the `DatasetVersion` provided to the `Experiment` conform to what the script expects, which reduces errors at execution time. In the *Experiment creation form*, selecting a constraint pre-fills the aliases to attach, as detailed [here](https://documentation.picsellia.com/docs/experiments-creation#a-dataset-constraints). *Dataset Constraints* are not part of the *ModelVersion creation form*: you define them once the `ModelVersion` is created, from the *Constraints* tab of its *Settings*, as detailed [here](https://documentation.picsellia.com/docs/registry-model-version#b-constraints). ### A checklist before using a `ModelVersion` as _Base architecture_ - The _Docker image_ contains your _training script_ and is accessible from where the training runs. - The _Parameters_ match the ones your script reads, with sensible default values. - Your script works with a `LabelMap` coming from another `DatasetVersion`. - The _Dataset Constraints_ reflect the `DatasetVersion` your script expects. ## 4. Add *Model files* Attaching *Model files* such as weight, configuration file, or checkpoint file to your `ModelVersion` can be done once the `ModelVersion` has been initialized as explained just before. To do so, click on the pen icon next to *Files* in the *ModelVersion overview*.

A modal will then open allowing you to select the *Model file* and give it a *Name*.

Once uploaded, the *Model file* will be related to the `ModelVersion` and physically stored through the *Storage Connector* defined as default for the current *Organization*. Further details on *Model Files* are available [here](https://documentation.picsellia.com/docs/registry-model-version#6-files). ## 5. Modify a `ModelVersion` Once created you can still modify some elements of a `ModelVersion`. * The *Name* and the *Description* can be modified in the *Settings tab*. * The `LabelMap`, *Parameters*, *Docker image* and *Model files* can be modified directly from the *ModelVersion overview* using the pen icon next to each section. * The *Framework* and *Type* can be modified using the [SDK](https://documentation.picsellia.com/reference/modelversion#update) **Other elements can not be modified as they are automatically generated by Picsellia, so modifying them could endanger the consistency of the `ModelVersion`.** However more globally, if the `ModelVersion` is already used in a `Deployment` or somewhere else, modifying it could put at risk the consistency of your workspace or create issues later in your project. This is why you should be really careful when performing such modifications. **A good practice that would avoid such risks would be to create a new `ModelVersion` that will carry those modifications**. This way, you keep track of your work and you avoid endangering the consistency of your workspace.