Register and work with models - Azure Machine Learning (original) (raw)

APPLIES TO: Azure CLI ml extension v2 (current) Python SDK azure-ai-ml v2 (current)

In this article, you learn to register and work with models in Azure Machine Learning by using:

You learn how to:

Model registration

Model registration lets you store and version your models in your workspace in the Azure cloud. The model registry helps you organize and keep track of your trained models. You can register models as assets in Azure Machine Learning by using the Azure CLI, the Python SDK, or the Machine Learning studio UI.

Supported paths

To register a model, specify a path that points to the data or job location. The following table shows the various data locations Azure Machine Learning supports, and the syntax for the path parameter:

Location Syntax
Local computer /
Azure Machine Learning datastore azureml://datastores//paths/<path_on_datastore>
Azure Machine Learning job azureml://jobs//outputs//paths/
MLflow job runs://
Model asset in a Machine Learning workspace azureml::
Model asset in a Machine Learning registry azureml://registries//models//versions/

Supported modes

When you use models for inputs or outputs, specify one of the following modes. For example, specify whether the model should be read-only mounted or downloaded to the compute target.

The following table shows the available mode options for different model type inputs and outputs.

Type upload download ro_mount rw_mount direct
custom file input
custom folder input ✓ ✓ ✓
mlflow input ✓ ✓
custom file output ✓ ✓ ✓
custom folder output ✓ ✓ ✓
mlflow output ✓ ✓ ✓

Prerequisites

To run the code samples in this article and work with the Azure Machine Learning V2 CLI or Python Azure Machine Learning V2 SDK, you also need:

az extension add -n ml

Note

V2 provides full backward compatibility. You can still use model assets from the v1 SDK or CLI. All models registered with the v1 CLI or SDK are assigned the type custom.

Register a model by using the studio UI

To register a model by using the Azure Machine Learning studio UI:

  1. In your workspace in the studio, select Models from the left navigation.
  2. On the Model List page, select Register, and select one of the following locations from the dropdown list:
    • From local files
    • From a job output
    • From datastore
    • From local files (based on framework)
  3. On the first Register model screen:
    1. Navigate to the local file, datastore, or job output for your model.
    2. Select the input model type: MLflow, Triton, or Unspecified type.
  4. On the Model settings screen, provide a name and other optional settings for your registered model, and select Next.
  5. On the Review screen, review the configuration and then select Register.

Screenshot of the UI to register a model.

Register a model by using the Azure CLI or Python SDK

The following code snippets show how to register a model as an asset in Azure Machine Learning by using the Azure CLI or Python SDK. These snippets use custom and mlflow model types.

Tip

You can follow along with the Python versions of the following samples by running the model.ipynb notebook in the azureml-examples repository.

Connect to your workspace

The workspace is the top-level resource for Azure Machine Learning. It provides a centralized place to work with all the artifacts you create when you use Azure Machine Learning. In this section, you connect to your Azure Machine Learning workspace to create the registered model.

  1. Sign in to Azure by running az login and following the prompts.
  2. In the following commands, replace <subscription-id>, <workspace-name>, <resource-group>, and <location> placeholders with the values for your environment.
az account set --subscription <subscription-id>  
az configure --defaults workspace=<workspace-name> group=<resource-group> location=<location>

Create the registered model

You can create a registered model from a model that's:

Local file or folder

  1. Create a YAML file .yml. In the file, provide a name for your registered model, a path to the local model file, and a description. For example:
$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json  
name: local-file-example  
path: mlflow-model/model.pkl  
description: Model created from local file.
  1. Run the following command, using the name of your YAML file:
az ml model create -f <file-name>.yml

For a complete example, see the model YAML.

Datastore

You can create a model from a cloud path by using any of the supported URI formats.

The following example uses the shorthand azureml scheme for pointing to a path on the datastore by using the syntax azureml://datastores/<datastore-name>/paths/<path_on_datastore>.

az ml model create --name my-model --version 1 --path azureml://datastores/myblobstore/paths/models/cifar10/cifar.pt

For a complete example, see the CLI reference.

Job output

If your model data comes from a job output, you have two options for specifying the model path. You can use the MLflow runs: URI format or the azureml://jobs URI format.

Note

The artifacts reserved keyword represents output from the default artifact location.

az ml model create --name my-registered-model --version 1 --path runs:/my_run_0000000000/model/ --type mlflow_model  
az ml model create --name run-model-example --version 1 --path azureml://jobs/my_run_0000000000/outputs/artifacts/paths/model/

For a complete example, see the CLI reference.

Use models for training

The v2 Azure CLI and Python SDK also let you use models as inputs or outputs in training jobs.

Use a model as input in a training job

  1. Create a job specification YAML file, .yml. In the inputs section of the job, specify:
    • The model type, which can be mlflow_model, custom_model, or triton_model.
    • The path where your model is located. You can use any of the paths listed in the comment of the following example.
$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json  
# Possible Paths for models:  
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>  
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>  
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>  
# Model Asset: azureml:<my_model>:<version>  
command: |  
  ls ${{inputs.my_model}}  
inputs:  
  my_model:  
    type: mlflow_model # List of all model types here: https://learn.microsoft.com/azure/machine-learning/reference-yaml-model#yaml-syntax  
    path: ../../assets/model/mlflow-model  
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest
  1. Run the following command, substituting your YAML filename.
az ml job create -f <file-name>.yml

For a complete example, see the model GitHub repo.

Write a model as output for a job

Your job can write a model to your cloud-based storage by using outputs.

  1. Create a job specification YAML file .yml. Fill in the outputs section with the output model type and path.
$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json  
# Possible Paths for Model:  
# Local path: mlflow-model/model.pkl  
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>  
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>  
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>  
# Model Asset: azureml:<my_model>:<version>  
code: src  
command: >-  
  python hello-model-as-output.py  
  --input_model ${{inputs.input_model}}  
  --custom_model_output ${{outputs.output_folder}}  
inputs:  
  input_model:  
    type: mlflow_model # mlflow_model,custom_model, triton_model  
    path: ../../assets/model/mlflow-model  
outputs:  
  output_folder:  
    type: custom_model # mlflow_model,custom_model, triton_model  
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest
  1. Create a job by using the CLI:
az ml job create --file <file-name>.yml

For a complete example, see the model GitHub repo.

Manage models

You can use the Azure CLI and Python SDK to manage the lifecycle of your Azure Machine Learning model assets.

List

List all the models in your workspace:

az ml model list

List all the model versions under a given name:

az ml model list --name run-model-example

Show

Get the details of a specific model:

az ml model show --name run-model-example --version 1

Update

Update mutable properties of a specific model:

Important

For models, you can only update the description and tags properties. All other properties are immutable. To change these properties, create a new version of the model.

az ml model update --name  run-model-example --version 1 --set description="This is an updated description." --set tags.stage="Prod"

Archive

Archiving a model hides it from list queries like az ml model list by default. You can continue to reference and use an archived model in your workflows.

You can archive all versions or only specific versions of a model. If you don't specify a version, the command archives all versions of the model. If you create a new model version under an archived model container, the new version is also automatically set as archived.

Archive a specific model version:

az ml model archive --name run-model-example --version 1

Related content