Skip to main content

OutputModel

class OutputModel()#

Create an output model for a Task (experiment) to store the training results.

The OutputModel object is always connected to a Task object, because it is instantiated with a Task object as an argument. It is, therefore, automatically registered as the Task’s (experiment’s) output model.

The OutputModel object is read-write.

A common use case is to reuse the OutputModel object, and override the weights after storing a model snapshot. Another use case is to create multiple OutputModel objects for a Task (experiment), and after a new high score is found, store a model snapshot.

If the model configuration and / or the model’s label enumeration are None, then the output model is initialized with the values from the Task object’s input model.

info

When executing a Task (experiment) remotely in a worker, you can modify the model configuration and / or model’s label enumeration using the ClearML Web-App.

Create a new model and immediately connect it to a task.

We do not allow for Model creation without a task, so we always keep track on how we created the models In remote execution, Model parameters can be overridden by the Task (such as model configuration & label enumerator)

  • Parameters

    • task (Task ) – The Task object with which the OutputModel object is associated.

    • config_text (unconstrained text string ) – The configuration as a string. This is usually the content of a configuration dictionary file. Specify config_text or config_dict, but not both.

    • config_dict (dict ) – The configuration as a dictionary. Specify config_dict or config_text, but not both.

    • label_enumeration (dict ) – The label enumeration dictionary of string (label) to integer (value) pairs. (Optional)

      For example:

      {
      'background': 0,
      'person': 1
      }
    • name (str ) – The name for the newly created model. (Optional)

    • tags (list ( str ) ) – A list of strings which are tags for the model. (Optional)

    • comment (str ) – A comment / description for the model. (Optional)

    • framework (str or Framework object ) – The framework of the model or a Framework object. (Optional)

    • base_model_id – optional, model id to be reused


comment#

property comment: str

The comment for the model. Also, use for a model description.

  • Return type

    str

  • Returns

    The model comment / description.


config_dict#

property config_dict

Get the configuration as a dictionary parsed from the config_text text. This usually represents the model configuration. For example, from prototxt to ini file or python code to evaluate.

  • Return type

    dict

  • Returns

    The configuration.


config_text#

property config_text

Get the configuration as a string. For example, prototxt, an ini file, or Python code to evaluate.

  • Return type

    str

  • Returns

    The configuration.


connect#

connect(task, name=None)

Connect the current model to a Task object, if the model is a preexisting model. Preexisting models include:

  • Imported models.

  • Models whose metadata the ClearML Server (backend) is already storing.

  • Models from another source, such as frameworks like TensorFlow.

  • Parameters

    • task (object ) – A Task object.

    • name (str ) – The model name as it would appear on the Task object. The model object itself can have a different name, this is designed to support multiple models used/created by a single Task. Use examples would be GANs or model ensemble

  • Return type

    None


get_weights#

get_weights(raise_on_error=False)

Download the base model and return the locally stored filename.

  • Parameters

    raise_on_error (bool ) – If True and the artifact could not be downloaded, raise ValueError, otherwise return None on failure and output log warning.

  • Return type

    str

  • Returns

    The locally stored file.


get_weights_package#

get_weights_package(return_path=False, raise_on_error=False)

Download the base model package into a temporary directory (extract the files), or return a list of the locally stored filenames.

  • Parameters

    • return_path (bool ) – Return the model weights or a list of filenames (Optional)

      • True - Download the model weights into a temporary directory, and return the temporary directory path.

      • False - Return a list of the locally stored filenames. (Default)

    • raise_on_error (bool ) – If True and the artifact could not be downloaded, raise ValueError, otherwise return None on failure and output log warning.

  • Return type

    Union[str, List[Path]]

  • Returns

    The model weights, or a list of the locally stored filenames.


id#

property id

The Id (system UUID) of the model.

  • Return type

    str

  • Returns

    The model ID.


labels#

property labels

Get the label enumeration as a dictionary of string (label) to integer (value) pairs.

For example:

{
'background': 0,
'person': 1
}
  • Return type

    Dict[str, int]

  • Returns

    The label enumeration.


name#

property name: str

The name of the model.

  • Return type

    str

  • Returns

    The model name.


publish#

publish()

Set the model to the status published and for public use. If the model’s status is already published, then this method is a no-op.

  • Return type

    ()


published#

property published

Get the published state of this model.

  • Return type

    bool

  • Returns


OutputModel.set_default_upload_uri#

classmethod set_default_upload_uri(output_uri)

Set the default upload uri for all OutputModels

  • Parameters

    output_uri (Optional[str]) – URL for uploading models. examples: https://demofiles.demo.clear.ml, s3://bucket/, gs://bucket/, azure://bucket/, file:///mnt/shared/nfs

  • Return type

    None


set_upload_destination#

set_upload_destination(uri)

Set the URI of the storage destination for uploaded model weight files. Supported storage destinations include S3, Google Cloud Storage), and file locations.

Using this method, files uploads are separate and then a link to each is stored in the model object.

info

For storage requiring credentials, the credentials are stored in the ClearML configuration file, ~/clearml.conf.

  • Parameters

    uri (str ) – The URI of the upload storage destination.

    For example:

    • s3://bucket/directory/

    • file:///tmp/debug/

  • Return bool

    The status of whether the storage destination schema is supported.

    • True - The storage destination scheme is supported.

    • False - The storage destination scheme is not supported.

  • Return type

    None


system_tags#

property system_tags: List[str]

A list of system tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.


tags#

property tags: List[str]

A list of tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.


task#

property task: str

Return the creating task ID

  • Return type

    str

  • Returns

    The Task ID (str)


update_design#

update_design(config_text=None, config_dict=None)

Update the model configuration. Store a blob of text for custom usage.

info

This method’s behavior is lazy. The design update is only forced when the weights are updated.

  • Parameters

    • config_text (unconstrained text string ) – The configuration as a string. This is usually the content of a configuration dictionary file. Specify config_text or config_dict, but not both.

    • config_dict (dict ) – The configuration as a dictionary. Specify config_text or config_dict, but not both.

  • Return type

    bool

  • Returns

    True, update successful. False, update not successful.


update_labels#

update_labels(labels)

Update the label enumeration.

  • Parameters

    labels (dict ) – The label enumeration dictionary of string (label) to integer (value) pairs.

    For example:

    {
    'background': 0,
    'person': 1
    }
  • Return type

    Optional[Waitable]

  • Returns


update_weights#

update_weights(weights_filename=None, upload_uri=None, target_filename=None, auto_delete_file=True, register_uri=None, iteration=None, update_comment=True, is_package=False)

Update the model weights from a locally stored model filename.

info

Uploading the model is a background process. A call to this method returns immediately.

  • Parameters

    • weights_filename (str ) – The name of the locally stored weights file to upload. Specify weights_filename or register_uri, but not both.

    • upload_uri (str ) – The URI of the storage destination for model weights upload. The default value is the previously used URI. (Optional)

    • target_filename (str ) – The newly created filename in the storage destination location. The default value is the weights_filename value. (Optional)

    • auto_delete_file (bool ) – Delete the temporary file after uploading (Optional)

      • True - Delete (Default)

      • False - Do not delete

    • register_uri (str ) – The URI of an already uploaded weights file. The URI must be valid. Specify register_uri or weights_filename, but not both.

    • iteration (int ) – The iteration number.

    • update_comment (bool ) – Update the model comment with the local weights file name (to maintain provenance) (Optional)

      * `True` - Update model comment (Default)
      * `False` - Do not update
    • is_package (bool ) – Mark the weights file as compressed package, usually a zip file.

  • Return type

    str

  • Returns

    The uploaded URI.


update_weights_package#

update_weights_package(weights_filenames=None, weights_path=None, upload_uri=None, target_filename=None, auto_delete_file=True, iteration=None)

Update the model weights from locally stored model files, or from directory containing multiple files.

info

Uploading the model weights is a background process. A call to this method returns immediately.

  • Parameters

    • weights_filenames (list ( str ) ) – The file names of the locally stored model files. Specify weights_filenames, or weights_path, but not both.

    • weights_path (str ) – The directory path to a package. All the files in the directory will be uploaded. Specify weights_path or weights_filenames, but not both.

    • upload_uri (str ) – The URI of the storage destination for the model weights upload. The default is the previously used URI. (Optional)

    • target_filename (str ) – The newly created filename in the storage destination URI location. The default is the value specified in the weights_filename parameter. (Optional)

    • auto_delete_file (bool ) – Delete temporary file after uploading (Optional)

      • True - Delete (Default)

      • False - Do not delete

    • iteration (int ) – The iteration number.

  • Return type

    str

  • Returns

    The uploaded URI for the weights package.


url#

property url: str

Return the url of the model file (or archived files)

  • Return type

    str

  • Returns

    The model file URL.


OutputModel.wait_for_uploads#

classmethod wait_for_uploads(timeout=None, max_num_uploads=None)

Wait for any pending or in-progress model uploads to complete. If no uploads are pending or in-progress, then the wait_for_uploads returns immediately.

  • Parameters

    • timeout (float ) – The timeout interval to wait for uploads (seconds). (Optional).

    • max_num_uploads (int ) – The maximum number of uploads to wait for. (Optional).

  • Return type

    None