model.OutputModel¶
-
class
clearml.model.
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.Note
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.
-
property
comment
¶ The comment for the model. Also, use for a model description.
- Returns
The model comment / description.
-
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.- Returns
The configuration.
-
property
config_text
¶ Get the configuration as a string. For example, prototxt, an ini file, or Python code to evaluate.
- Returns
The configuration.
-
connect
(task)¶ 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.
-
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.
- Returns
The locally stored file.
-
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.
- Returns
The model weights, or a list of the locally stored filenames.
-
property
id
¶ The Id (system UUID) of the model.
- Returns
The model ID.
-
property
labels
¶ Get the label enumeration as a dictionary of string (label) to integer (value) pairs.
For example:
{ 'background': 0, 'person': 1 }
- Returns
The label enumeration.
-
property
name
¶ The name of the model.
- Returns
The model name.
-
publish
()¶ Set the model to the status
published
and for public use. If the model’s status is alreadypublished
, then this method is a no-op.
-
property
published
¶ Get the published state of this model.
- Returns
-
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.
Note
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.
A list of system tags describing the model.
- Returns
The list of tags.
A list of tags describing the model.
- Returns
The list of tags.
-
property
task
¶ Return the creating task object
- Returns
The Task object.
-
update_design
(config_text=None, config_dict=None)¶ Update the model configuration. Store a blob of text for custom usage.
Note
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
orconfig_dict
, but not both.config_dict (dict) – The configuration as a dictionary. Specify
config_text
orconfig_dict
, but not both.
- Returns
True, update successful. False, update not successful.
-
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 }
- Returns
-
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.
Note
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
orregister_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
orweights_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.
- Returns
The uploaded URI.
-
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.
Note
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
, orweights_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
orweights_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.
- Returns
The uploaded URI for the weights package.
-
property
url
¶ Return the url of the model file (or archived files)
- Returns
The model file URL.
-
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).
-
property