Skip to main content

InputModel

class InputModel()#

Load an existing model in the system, search by model id. The Model will be read-only and can be used to pre initialize a network We can connect the model to a task as input model, then when running remotely override it with the UI.

Load a model from the Model artifactory, based on model_id (uuid) or a model name/projects/tags combination.

  • Parameters

    • model_id (Optional[str]) – The ClearML Id (system UUID) of the input model whose metadata the ClearML Server (backend) stores. If provided all other arguments are ignored

    • name (Optional[str]) – Model name to search and load

    • project (Optional[str]) – Model project name to search model in

    • tags (Optional[Sequence[str]]) – Model tags list to filter by

    • only_published (bool) – If True filter out non-published (draft) models


comment#

property comment

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

  • Return type

    str

  • Returns

    The model comment / description.


config_dict#

property config_dict

The configuration as a dictionary, parsed from the design text. This usually represents the model configuration. For example, prototxt, an ini file, or Python code to evaluate.

  • Return type

    dict

  • Returns

    The configuration.


config_text#

property config_text

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 preexisting. Preexisting models include:

  • Imported models (InputModel objects created using the Logger.import_model method).

  • Models whose metadata is already in the ClearML platform, meaning the InputModel object is instantiated from the InputModel class specifying the the model’s ClearML Id as an argument.

  • Models whose origin is not ClearML that are used to create an InputModel object. For example, models created using TensorFlow models.

When the experiment is executed remotely in a worker, the input model already specified in the experiment is used.

info

The ClearML Web-App allows you to switch one input model for another and then enqueue the experiment to execute in a worker.

  • Parameters

    • task (object ) – A Task object.

    • name (str ) – The model name to be stored on the Task (default the filename, of the model weights, without the file extension)

  • Return type

    None


InputModel.empty#

classmethod empty(config_text=None, config_dict=None, label_enumeration=None)

Create an empty model object. Later, you can assign a model to the empty model object.

  • Parameters

    • config_text (unconstrained text string ) – The model 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 model configuration as a dictionary. Specify config_text or config_dict, but not both.

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

      For example:

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

    InputModel

  • Returns

    An empty model object.


get_local_copy#

get_local_copy(extract_archive=True, raise_on_error=False)

Retrieve a valid link to the model file(s). If the model URL is a file system link, it will be returned directly. If the model URL is points to a remote location (http/s3/gs etc.), it will download the file(s) and return the temporary location of the downloaded model.

  • Parameters

    • extract_archive (bool ) – If True and the model is of type ‘packaged’ (e.g. TensorFlow compressed folder) The returned path will be a temporary folder containing the archive content

    • 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

    A local path to the model (or a downloaded copy of it).


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.


InputModel.import_model#

classmethod import_model(weights_url, config_text=None, config_dict=None, label_enumeration=None, name=None, tags=None, comment=None, is_package=False, create_as_published=False, framework=None)

Create an InputModel object from a pre-trained model by specifying the URL of an initial weight files. Optionally, input a configuration, label enumeration, name for the model, tags describing the model, comment as a description of the model, indicate whether the model is a package, specify the model’s framework, and indicate whether to immediately set the model’s status to Published. The model is read-only.

The ClearML Server (backend) may already store the model’s URL. If the input model’s URL is not stored, meaning the model is new, then it is imported and ClearML stores its metadata. If the URL is already stored, the import process stops, ClearML issues a warning message, and ClearML reuses the model.

In your Python experiment script, after importing the model, you can connect it to the main execution Task as an input model using InputModel.connect or Task.connect. That initializes the network.

info

Using the ClearML Web-App (user interface), you can reuse imported models and switch models in experiments.

  • Parameters

    • weights_url (str ) – A valid URL for the initial weights file. If the ClearML Web-App (backend) already stores the metadata of a model with the same URL, that existing model is returned and ClearML ignores all other parameters.

      For example:

      * `https://domain.com/file.bin`
      * `s3://bucket/file.bin`
      * `file:///home/user/file.bin`
    • 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.

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

      For example:

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

    • tags (list ( str ) ) – The list of tags which describe the model. (Optional)

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

    • is_package (bool ) – Is the imported weights file is a package (Optional)

      • True - Is a package. Add a package tag to the model.

      • False - Is not a package. Do not add a package tag. (Default)

    • create_as_published (bool ) – Set the model’s status to Published (Optional)

      • True - Set the status to Published.

      • False - Do not set the status to Published. The status will be Draft. (Default)

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

  • Return type

    InputModel

  • Returns

    The imported model or existing model (see above).


labels#

property labels

The label enumeration of string (label) to integer (value) pairs.

  • Return type

    Dict[str, int]

  • Returns

    A dictionary containing labels enumeration, where the keys are labels and the values as integers.


InputModel.load_model#

classmethod load_model(weights_url, load_archived=False)

Load an already registered model based on a pre-existing model file (link must be valid). If the url to the weights file already exists, the returned object is a Model representing the loaded Model. If no registered model with the specified url is found, None is returned.

  • Parameters

    • weights_url (str) – The valid url for the weights file (string).

      Examples:

      "https://domain.com/file.bin" or "s3://bucket/file.bin" or "file:///home/user/file.bin".
      info

      If a model with the exact same URL exists, it will be used, and all other arguments will be ignored.

    • load_archived (bool ) – Load archived models

      • True - Load the registered Model, if it is archived.

      • False - Ignore archive models.

  • Return type

    InputModel

  • Returns

    The InputModel object, or None if no model could be found.


name#

property name

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

    ()


InputModel.query_models#

classmethod query_models(project_name=None, model_name=None, tags=None, only_published=False, include_archived=False, max_results=None)

Return Model objects from the project artifactory. Filter based on project-name / model-name / tags. List is always returned sorted by descending last update time (i.e. latest model is the first in the list)

  • Parameters

    • project_name (Optional[str]) – Optional, filter based project name string, if not given query models from all projects

    • model_name (Optional[str]) – Optional Model name as shown in the model artifactory

    • tags (Optional[Sequence[str]]) – Optional filter models based on list of tags, example: [‘production’, ‘verified’, ‘-qa’] Notice use ‘-‘ prefix to filter out tags.

    • only_published (bool) – If True only return published models.

    • include_archived (bool) – If True return archived models.

    • max_results (Optional[int]) – Optional return the last X models, sorted by last update time (from the most recent to the least).

  • Return type

    List[Model]

  • Returns

    ModeList of Models objects


system_tags#

property system_tags

A list of system tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.


tags#

property tags

A list of tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.


task#

property task

Return the creating task ID

  • Return type

    str

  • Returns

    The Task ID (str)


url#

property url

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

  • Return type

    str

  • Returns

    The model file URL.