az ml model

  • Reference

Note

This reference is part of the ml extension for the Azure CLI (version 2.15.0 or higher). The extension will automatically install the first time you run an az ml model command. Learn more about extensions.

Manage Azure ML models.

Azure ML models consist of the binary file(s) that represent a machine learning model and any corresponding metadata. These models can be used in endpoint deployments for real-time and batch inference.

Commands

Name Description Type Status
az ml model archive

Archive a model.

 Extension GA
az ml model create

Create a model.

 Extension GA
az ml model download

Download all model-related files.

 Extension GA
az ml model list

List models in a workspace/registry. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

 Extension GA
az ml model package

Package a model into an environment.

 Extension Preview
az ml model restore

Restore an archived model.

 Extension GA
az ml model share

Share a specific model from workspace to registry.

 Extension GA
az ml model show

Show details for a model in a workspace/registry. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

 Extension GA
az ml model update

Update a model in a workspace/registry.

 Extension GA

az ml model archive

Archive a model.

Archiving a model will hide it by default from list queries (az ml model list). You can still continue to reference and use an archived model in your workflows. You can archive either a model container or a specific model version. Archiving a model container will archive all versions of the model under that given name. You can restore an archived model using az ml model restore. If the entire model container is archived, you cannot restore individual versions of the model - you will need to restore the model container.

az ml model archive --name
                    [--label]
                    [--registry-name]
                    [--resource-group]
                    [--version]
                    [--workspace-name]

Examples

Archive a model container (archives all versions of that model)

az ml model archive --name my-model --resource-group my-resource-group --workspace-name my-workspace

Archive a specific model version

az ml model archive --name my-model --version 1 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the model.

Optional Parameters

--label -l

Label of the model.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model create

Create a model.

Models can be created from a local file, local directory, datastore or job outputs. The created model will be tracked in the workspace/registry under the specified name and version. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

az ml model create [--datastore]
                   [--description]
                   [--file]
                   [--name]
                   [--no-wait]
                   [--path]
                   [--registry-name]
                   [--resource-group]
                   [--set]
                   [--stage]
                   [--tags]
                   [--type]
                   [--version]
                   [--workspace-name]

Examples

Create a model from a YAML specification file

az ml model create --file model.yml --resource-group my-resource-group --workspace-name my-workspace

Create a model from a local folder using command options

az ml model create --name my-model --version 1 --path ./my-model --resource-group my-resource-group --workspace-name my-workspace

Create a model using mlflow run URI format 'runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>' and command options

az ml model create --name my-model --version 1 --path runs:/c42d2507-4953-4a7c-a4c1-2b5bfe0ac64e/model/ --type mlflow_model --resource-group my-resource-group --workspace-name my-workspace

Create a model from a named job output using azureml job URI format 'azureml://jobs/<job-name>/outputs/<named-output>/paths/<path-to-model-relative-to-the-named-output-location>' and command options. The default named output is artifacts

az ml model create --name my-model --version 1 --path azureml://jobs/c42d2507-4953-4a7c-a4c1-2b5bfe0ac64e/outputs/artifacts/paths/model/ --resource-group my-resource-group --workspace-name my-workspace

Create a model from a datastore 'azureml://datastores/<datastore-name>/paths/<path-to-model-relative-to-the-root-of-the-datastore-location>' using command options

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

Optional Parameters

--datastore

The datastore to upload the local artifact to.

--description

Description of the model.

--file -f

Local path to the YAML file containing the Azure ML model specification. The YAML reference docs for model can be found at: https://aka.ms/ml-cli-v2-model-yaml-reference.

--name -n

Name of the model.

--no-wait

Do not wait for the long-running operation to finish.

default value: False
--path -p

Path to the model file(s). This can be either a local or a remote location. If specified, --name/-n and --version/-v must also be provided.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--stage -s

Stage of the model.

--tags

Space-separated key-value pairs for the tags of the object.

--type -t

Type of the model, allowed values are custom_model, mlflow_model and triton_model. The default type is custom_model.

--version -v

Version of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model download

Download all model-related files.

The files will be downloaded into a folder named after the model's name. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

az ml model download --name
                     --version
                     [--download-path]
                     [--registry-name]
                     [--resource-group]
                     [--workspace-name]

Examples

Download a model with the specified name and version

az ml model download --name my-model --version 1 --resource-group my-resource-group --workspace-name my-workspace

Download a model with the specified name and version, into a specified local path

az ml model download --name my-model --version 1  --download-path local_path --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the model.

--version -v

Version of the model.

Optional Parameters

--download-path -p

Path to download the model files, defaults to the current working directory.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model list

List models in a workspace/registry. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

az ml model list [--archived-only]
                 [--include-archived]
                 [--max-results]
                 [--name]
                 [--registry-name]
                 [--resource-group]
                 [--stage]
                 [--workspace-name]

Examples

List all the models in a workspace

az ml model list --resource-group my-resource-group --workspace-name my-workspace

List all the model versions for the specified name in a workspace

az ml model list --name my-model --resource-group my-resource-group --workspace-name my-workspace

List all the models in a workspace using --query argument to execute a JMESPath query on the results of commands.

az ml model list --query "[].{Name:name}"  --output table --resource-group my-resource-group --workspace-name my-workspace

Optional Parameters

--archived-only

List archived models only.

default value: False
--include-archived

List archived models and active models.

default value: False
--max-results -r

Max number of results to return.

--name -n

Name of the model. If provided, all the model versions under this name will be returned.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--stage -s

Stage of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model package

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Package a model into an environment.

When a model is packaged, an environment with all the dependencies is created.

az ml model package --file
                    --name
                    --version
                    [--registry-name]
                    [--resource-group]
                    [--workspace-name]

Examples

Package a model with the specified name and version

az ml model package --name my-model --version my-version --resource-group my-resource-group --workspace-name my-workspace --file my-package.yml

Required Parameters

--file -f

Local path to the YAML file containing the model package definition.

--name -n

Name of the model.

--version -v

Version of the model.

Optional Parameters

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model restore

Restore an archived model.

When an archived model is restored, it will no longer be hidden from list queries (az ml model list). If an entire model container is archived, you can restore that archived container. This will restore all versions of the model under that given name. You cannot restore only a specific model version if the entire model container is archived - you will need to restore the entire container. If only an individual model version was archived, you can restore that specific version.

az ml model restore --name
                    [--label]
                    [--registry-name]
                    [--resource-group]
                    [--version]
                    [--workspace-name]

Examples

Restore an archived model container (restores all versions of that model)

az ml model restore --name my-model --resource-group my-resource-group --workspace-name my-workspace

Restore a specific archived model version

az ml model restore --name my-model --version 1 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the model.

Optional Parameters

--label -l

Label of the model.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model share

Share a specific model from workspace to registry.

Copy an existing model from a workspace to a registry for cross-workspace reuse.

az ml model share --name
                  --registry-name
                  --share-with-name
                  --share-with-version
                  --version
                  [--resource-group]
                  [--workspace-name]

Examples

Share an existing environment from workspace to registry

az ml model share --name my-model --version my-version --resource-group my-resource-group --workspace-name my-workspace --share-with-name new-name-in-registry --share-with-version new-version-in-registry --registry-name my-registry

Required Parameters

--name -n

Name of the model.

--registry-name

Destination registry.

--share-with-name

Name of the model to be created with.

--share-with-version

Version of the model to be created with.

--version -v

Version of the model.

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model show

Show details for a model in a workspace/registry. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

az ml model show --name
                 [--label]
                 [--registry-name]
                 [--resource-group]
                 [--version]
                 [--workspace-name]

Examples

Show details for a model with the specified name and version

az ml model show --name my-model --version 1 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the model.

Optional Parameters

--label -l

Label of the model.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml model update

Update a model in a workspace/registry.

The 'description', and 'tags' properties can be updated. If you are using a registry, replace --workspace-name my-workspace with the --registry-name <registry-name> option.

az ml model update --name
                   --resource-group
                   [--add]
                   [--force-string]
                   [--label]
                   [--registry-name]
                   [--remove]
                   [--set]
                   [--stage]
                   [--version]
                   [--workspace-name]

Examples

Update a model's flavors

az ml model update --name my-model --version 1 --set flavors.python_function.python_version=3.8 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the model.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

default value: []
--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

default value: False
--label -l

Label of the model.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--remove

Remove a property or an element from a list. Example: --remove property.list <indexToRemove> OR --remove propertyToRemove.

default value: []
--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

default value: []
--stage -s

Stage of the model.

--version -v

Version of the model.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.