Model class
Definition
Represents the result of machine learning training.
A model is the result of a Azure Machine learning training Run or some other model training process outside of Azure. Regardless of how the model is produced, it can be registered in a workspace, where it is represented by a name and a version. With the Model class, you can package models for use with Docker and deploy them as an inference endpoint.
For an end-to-end tutorial showing how models are created, managed, and consumed, see Train image classification model with MNIST data and scikit-learn using Azure Machine Learning.
Model(workspace, name=None, id=None, tags=None, properties=None, version=None, run_id=None, model_framework=None)- Inheritance
-
builtins.objectModel
Parameters
- workspace
- Workspace
The workspace object containing the model to retrieve.
- name
- str
The name of the model to retrieve. The latest model with the specified name is returned, if it exists.
- id
- str
The ID of the model to retrieve. The model with the specified ID is returned, if it exists.
- tags
- list
An optional list of tags used to filter returned results. Results are filtered based on the provided list, searching by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']]
- properties
- list
An optional list of properties used to filter returned results. Results are filtered based on the provided list, searching by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']]
- version
- int
The model version to return. When provided along with name, the specific
version of the specified named model is returned, if it exists.
- run_id
- str
Optional ID used to filter returned results.
- model_framework
- str
Optional framework name used to filter returned results. If specified, results are returned for the models matching the specified framework. See Framework for allowed values.
Remarks
The Model constructor is used to retrieve a cloud representation of a Model object associated with the specified workspace. At least the name or ID must be provided to retrieve models, but there are also other options for filtering including by tags, properties, run ID, and framework.
from azureml.core.model import Model
model = Model(ws, 'my_model_name')
For example, if you have a model that is stored in multiple files, you can register them as a single model in your Azure Machine Learning workspace. After registration, you can then download or deploy the registered model and receive all the files that were registered.
Registering a model creates a logical container for the one or more files that make up your model. In addition to the content of the model file itself, a registered model also stores model metadata, including model description, tags, and framework information, that is useful when managing and deploying the model in your workspace. For example, with tags you can categorize your models and apply filters when listing models in your workspace. After registration, you can then download or deploy the registered model and receive all the files and metadata that were registered.
The following sample shows how to register a model specifying tags and a description.
from azureml.core.model import Model
model = Model.register(model_path="sklearn_regression_model.pkl",
model_name="sklearn_regression_model_local_adv",
tags={'area': "diabetes", 'type': "regression"},
description="Ridge regression model to predict diabetes",
workspace=ws)
Full sample is available from https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/deployment/deploy-to-local/register-model-deploy-local-advanced.ipynb
The following sample shows how to register a model specifying framework, input and output datasets, and resource configuration.
from azureml.core import Model
from azureml.core.resource_configuration import ResourceConfiguration
model = Model.register(workspace=ws,
model_name='my-sklearn-model', # Name of the registered model in your workspace.
model_path='./sklearn_regression_model.pkl', # Local file to upload and register as a model.
model_framework=Model.Framework.SCIKITLEARN, # Framework used to create the model.
model_framework_version='0.19.1', # Version of scikit-learn used to create the model.
sample_input_dataset=input_dataset,
sample_output_dataset=output_dataset,
resource_configuration=ResourceConfiguration(cpu=1, memory_in_gb=0.5),
description='Ridge regression model to predict diabetes progression.',
tags={'area': 'diabetes', 'type': 'regression'})
print('Name:', model.name)
print('Version:', model.version)
Full sample is available from https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/deployment/deploy-to-cloud/model-register-and-deploy.ipynb
Methods
| add_dataset_references(datasets) |
Associate the provided datasets with this Model. |
| add_properties(properties) |
Add key value pairs to properties dictionary of this model. |
| add_tags(tags) |
Add key value pairs to the tags dictionary of this model. |
| delete() |
Delete this model from its associated workspace. |
| deploy(workspace, name, models, inference_config=None, deployment_config=None, deployment_target=None, overwrite=False) |
Deploy a Webservice from zero or more model objects. This function is similar to the |
| deserialize(workspace, model_payload) |
Convert a JSON object into a model object. Conversion fails if the specified workspace is not the workspace the model is registered with. |
| download(target_dir='.', exist_ok=False, exists_ok=None) |
Download model to target directory of the local file system. |
| get_model_path(model_name, version=None, _workspace=None) |
Return path to model. The function will search for the model in the following locations. If
If
|
| get_sas_urls() |
Return a dictionary of key value pairs containing filenames and corresponding SAS URLs. |
| list(workspace, name=None, tags=None, properties=None, run_id=None, latest=False) |
Retrieve a list of all models associated with the provided workspace, with optional filters. |
| package(workspace, models, inference_config=None, generate_dockerfile=False) |
Create a model package in the form of a Docker image or Dockerfile build context. |
| profile(workspace, profile_name, models, inference_config, input_data) |
Profiles this model to get resource configuration recommendations. |
| register(workspace, model_path, model_name, tags=None, properties=None, description=None, datasets=None, model_framework=None, model_framework_version=None, child_paths=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None) |
Register a model with the provided workspace. |
| remove_tags(tags) |
Remove the specified keys from tags dictionary of this model. |
| serialize() |
Convert this Model into a json serialized dictionary. |
| update(tags=None, description=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None) |
Perform an in-place update of the model. Existing values of specified parameters are replaced. |
| update_tags_properties(add_tags=None, remove_tags=None, add_properties=None) |
Perform an update of the tags and properties of the model. |
add_dataset_references(datasets)
Associate the provided datasets with this Model.
add_dataset_references(datasets)Parameters
- datasets
- list[tuple({str : (Dataset or DatasetSnapshot)})]
A list of tuples representing a pairing of dataset purpose to Dataset object.
add_properties(properties)
Add key value pairs to properties dictionary of this model.
add_properties(properties)Parameters
- properties
- dict({str : str})
The dictionary of properties to add.
add_tags(tags)
Add key value pairs to the tags dictionary of this model.
add_tags(tags)Parameters
- tags
- dict({str : str})
The dictionary of tags to add.
Exceptions
delete()
Delete this model from its associated workspace.
delete()deploy(workspace, name, models, inference_config=None, deployment_config=None, deployment_target=None, overwrite=False)
Deploy a Webservice from zero or more model objects.
This function is similar to the deploy function of the Webservice class, but does
not register the models. Use this function if you have model objects that are
already registered.
deploy(workspace, name, models, inference_config=None, deployment_config=None, deployment_target=None, overwrite=False)Parameters
- workspace
- Workspace
A Workspace object to associate the Webservice with.
- name
- str
The name to give the deployed service. Must be unique to the workspace, only consist of lowercase letters, numbers, or dashes, start with a letter, and be between 3 and 32 characters long.
- inference_config
- InferenceConfig
An InferenceConfig object used to determine required model properties.
- deployment_config
- WebserviceDeploymentConfiguration
A WebserviceDeploymentConfiguration used to configure the webservice. If one is not provided, an empty configuration object will be used based on the desired target.
- deployment_target
- ComputeTarget
A ComputeTarget to deploy the Webservice to. As Azure Container Instances has no associated ComputeTarget, leave this parameter as None to deploy to Azure Container Instances.
- overwrite
- bool
Indicates whether to overwrite the existing service if a service with the specified name already exists.
Returns
A Webservice object corresponding to the deployed webservice.
Return type
Exceptions
deserialize(workspace, model_payload)
Convert a JSON object into a model object.
Conversion fails if the specified workspace is not the workspace the model is registered with.
deserialize(workspace, model_payload)Parameters
- workspace
- Workspace
The workspace object the model is registered with.
- model_payload
- dict
A JSON object to convert to a Model object.
Returns
The Model representation of the provided JSON object.
Return type
download(target_dir='.', exist_ok=False, exists_ok=None)
Download model to target directory of the local file system.
download(target_dir='.', exist_ok=False, exists_ok=None)Parameters
- target_dir
- str
The path to a directory in which to download the model. Defaults to "."
- exist_ok
- bool
Indicates whether to replace downloaded dir/files if they exist. Defaults to False.
Returns
The path to file or folder of the model.
Return type
get_model_path(model_name, version=None, _workspace=None)
Return path to model.
The function will search for the model in the following locations.
If version is None:
- Download from remote to cache
- Load from cache azureml-models/$MODEL_NAME/$LATEST_VERSION/
- ./$MODEL_NAME
If version is not None:
- Load from cache azureml-models/$MODEL_NAME/$LATEST_VERSION/
- Download from remote to cache
get_model_path(model_name, version=None, _workspace=None)Parameters
- model_name
- str
The name of the model to retrieve.
- version
- int
The version of the model to retrieve. Defaults to the latest version.
- _workspace
- Workspace
The workspace to retrieve a model from. Can't use remotely.
Returns
The path on disk to the model.
Return type
Exceptions
get_sas_urls()
Return a dictionary of key value pairs containing filenames and corresponding SAS URLs.
get_sas_urls()Returns
Dictionary of K,V pairs containing filenames and corresponding SAS URLs
Return type
list(workspace, name=None, tags=None, properties=None, run_id=None, latest=False)
Retrieve a list of all models associated with the provided workspace, with optional filters.
list(workspace, name=None, tags=None, properties=None, run_id=None, latest=False)Parameters
- workspace
- Workspace
The workspace object to retrieve models from.
- tags
- list
Will filter based on the provided list, by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']]
- properties
- list
Will filter based on the provided list, by either 'key' or '[key, value]'. Ex. ['key', ['key2', 'key2 value']]
Returns
A list of models, optionally filtered.
Return type
Exceptions
package(workspace, models, inference_config=None, generate_dockerfile=False)
Create a model package in the form of a Docker image or Dockerfile build context.
package(workspace, models, inference_config=None, generate_dockerfile=False)Parameters
- workspace
- Workspace
The workspace in which to create the package.
- inference_config
- InferenceConfig
An InferenceConfig object to configure the operation of the models. This must include an Environment object.
- generate_dockerfile
- bool
Whether to create a Dockerfile that can be run locally instead of building an image.
Returns
A ModelPackage object.
Return type
profile(workspace, profile_name, models, inference_config, input_data)
Profiles this model to get resource configuration recommendations.
profile(workspace, profile_name, models, inference_config, input_data)Parameters
- workspace
- Workspace
A Workspace object in which to profile the model
- profile_name
- str
The name of the profiling run
- inference_config
- InferenceConfig
An InferenceConfig object used to determine required model properties.
- input_data
- str
The input data for profiling
Return type
register(workspace, model_path, model_name, tags=None, properties=None, description=None, datasets=None, model_framework=None, model_framework_version=None, child_paths=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)
Register a model with the provided workspace.
register(workspace, model_path, model_name, tags=None, properties=None, description=None, datasets=None, model_framework=None, model_framework_version=None, child_paths=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)Parameters
- workspace
- Workspace
The workspace to register the model with.
- model_path
- str
The path on the local file system where the model assets are
located. This can be a direct pointer to a single file or folder. If pointing to a folder, the
child_paths parameter can be used to specify individual files to bundle together as the Model object,
as opposed to using the entire contents of the folder.
- model_name
- str
The name to register the model with.
- tags
- dict({str : str})
An optional dictionary of key value tags to assign to the model.
- properties
- dict({str : str})
An optional dictionary of key value properties to assign to the model. These properties can't be changed after model creation, however new key value pairs can be added.
- datasets
- list[(str, AbstractDataset)]
A list of tuples where the first element describes the dataset-model relationship and the second element is the dataset.
- model_framework
- str
The framework of the registered model. Using the system-supported constants from the Framework class allows for simplified deployment for some popular frameworks.
If provided in conjunction with a model_path to a folder, only the specified
files will be bundled into the Model object.
- sample_input_dataset
- AbstractDataset
Sample input dataset for the registered model.
- sample_output_dataset
- AbstractDataset
Sample output dataset for the registered model.
- resource_configuration
- ResourceConfiguration
A resource configuration to run the registered model.
Returns
The registered model object.
Return type
Remarks
In addition to the content of the model file itself, a registered model also stores model metadata, including model description, tags, and framework information, that is useful when managing and deploying the model in your workspace. For example, with tags you can categorize your models and apply filters when listing models in your workspace.
The following sample shows how to register a model specifying tags and a description.
from azureml.core.model import Model
model = Model.register(model_path="sklearn_regression_model.pkl",
model_name="sklearn_regression_model_local_adv",
tags={'area': "diabetes", 'type': "regression"},
description="Ridge regression model to predict diabetes",
workspace=ws)
Full sample is available from https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/deployment/deploy-to-local/register-model-deploy-local-advanced.ipynb
remove_tags(tags)
Remove the specified keys from tags dictionary of this model.
remove_tags(tags)Parameters
serialize()
Convert this Model into a json serialized dictionary.
serialize()Returns
The json representation of this Model
Return type
update(tags=None, description=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)
Perform an in-place update of the model.
Existing values of specified parameters are replaced.
update(tags=None, description=None, sample_input_dataset=None, sample_output_dataset=None, resource_configuration=None)Parameters
- tags
- dict({str : str})
A dictionary of tags to update the model with. These tags replace existing tags for the model.
- description
- str
The new description to use for the model. This name replaces the existing name.
- sample_input_dataset
- AbstractDataset
The sample input dataset to use for the registered model. This sample input dataset replaces the existing dataset.
- sample_output_dataset
- AbstractDataset
The sample output dataset to use for the registered model. This sample output dataset replaces the existing dataset.
- resource_configuration
- ResourceConfiguration
The resource configuration to use to run the registered model.
Exceptions
update_tags_properties(add_tags=None, remove_tags=None, add_properties=None)
Perform an update of the tags and properties of the model.
update_tags_properties(add_tags=None, remove_tags=None, add_properties=None)Parameters
Exceptions
Feedback
Loading feedback...