Use the CLI extension for Azure Machine Learning

The Azure Machine Learning CLI is an extension to the Azure CLI, a cross-platform command-line interface for the Azure platform. This extension provides commands for working with Azure Machine Learning. It allows you to automate your machine learning activities. The following list provides some example actions that you can do with the CLI extension:

  • Run experiments to create machine learning models

  • Register machine learning models for customer usage

  • Package, deploy, and track the lifecycle of your machine learning models

The CLI is not a replacement for the Azure Machine Learning SDK. It is a complementary tool that is optimized to handle highly parameterized tasks which suit themselves well to automation.

Prerequisites

Full reference docs

Find the full reference docs for the azure-cli-ml extension of Azure CLI.

Install the extension

To install the Machine Learning CLI extension, use the following command:

az extension add -n azure-cli-ml

Tip

Example files you can use with the commands below can be found here.

When prompted, select y to install the extension.

To verify that the extension has been installed, use the following command to display a list of ML-specific subcommands:

az ml -h

Update the extension

To update the Machine Learning CLI extension, use the following command:

az extension update -n azure-cli-ml

Remove the extension

To remove the CLI extension, use the following command:

az extension remove -n azure-cli-ml

Resource management

The following commands demonstrate how to use the CLI to manage resources used by Azure Machine Learning.

  • If you do not already have one, create a resource group:

    az group create -n myresourcegroup -l westus2
    
  • Create an Azure Machine Learning workspace:

    az ml workspace create -w myworkspace -g myresourcegroup
    

    For more information, see az ml workspace create.

  • Attach a workspace configuration to a folder to enable CLI contextual awareness.

    az ml folder attach -w myworkspace -g myresourcegroup
    

    This command creates a .azureml subdirectory that contains example runconfig and conda environment files. It also contains a config.json file that is used to communicate with your Azure Machine Learning workspace.

    For more information, see az ml folder attach.

  • Attach an Azure blob container as a Datastore.

    az ml datastore attach-blob  -n datastorename -a accountname -c containername
    

    For more information, see az ml datastore attach-blob.

  • Upload files to a Datastore.

    az ml datastore upload  -n datastorename -p sourcepath
    

    For more information, see az ml datastore upload.

  • Attach an AKS cluster as a Compute Target.

    az ml computetarget attach aks -n myaks -i myaksresourceid -g myresourcegroup -w myworkspace
    

    For more information, see az ml computetarget attach aks

  • Create a new AMLcompute target.

    az ml computetarget create amlcompute -n cpu --min-nodes 1 --max-nodes 1 -s STANDARD_D3_V2
    

    For more information, see az ml computetarget create amlcompute.

Run experiments

  • Start a run of your experiment. When using this command, specify the name of the runconfig file (the text before *.runconfig if you are looking at your file system) against the -c parameter.

    az ml run submit-script -c sklearn -e testexperiment train.py
    

    Tip

    The az ml folder attach command creates a .azureml subdirectory, which contains two example runconfig files.

    If you have a Python script that creates a run configuration object programmatically, you can use RunConfig.save() to save it as a runconfig file.

    For more example runconfig files, see https://github.com/MicrosoftDocs/pipelines-azureml/tree/master/.azureml.

    For more information, see az ml run submit-script.

  • View a list of experiments:

    az ml experiment list
    

    For more information, see az ml experiment list.

Environment management

The following commands demonstrate how to create, register, and list Azure Machine Learning environments for your workspace:

  • Create scaffolding files for an environment:

    az ml environment scaffold -n myenv -d myenvdirectory
    

    For more information, see az ml environment scaffold.

  • Register an environment:

    az ml environment register -d myenvdirectory
    

    For more information, see az ml environment register.

  • List registered environments:

    az ml environment list
    

    For more information, see az ml environment list.

  • Download a registered environment:

    az ml environment download -n myenv -d downloaddirectory
    

    For more information, see az ml environment download.

Model registration, profiling, deployment

The following commands demonstrate how to register a trained model, and then deploy it as a production service:

  • Register a model with Azure Machine Learning:

    az ml model register -n mymodel -p sklearn_regression_model.pkl
    

    For more information, see az ml model register.

  • OPTIONAL Profile your model to get optimal CPU and memory values for deployment.

    az ml model profile -n myprofile -m mymodel:1 --ic inferenceconfig.json -d "{\"data\": [[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]]}" -t myprofileresult.json
    

    For more information, see az ml model profile.

  • Deploy your model to AKS

    az ml model deploy -n myservice -m mymodel:1 --ic inferenceconfig.json --dc deploymentconfig.json --ct akscomputetarget
    

    For more information on the inference configuration file schema, see Inference configuration schema.

    For more information on the deployment configuration file schema, see Deployment configuration schema.

    For more information, see az ml model deploy.

Inference configuration schema

The entries in the inferenceconfig.json document map to the parameters for the InferenceConfig class. The following table describes the mapping between entities in the JSON document and the parameters for the method:

JSON entity Method parameter Description
entryScript entry_script Path to a local file that contains the code to run for the image.
runtime runtime Which runtime to use for the image. Current supported runtimes are spark-py and python.
condaFile conda_file Optional. Path to a local file that contains a Conda environment definition to use for the image.
extraDockerFileSteps extra_docker_file_steps Optional. Path to a local file that contains additional Docker steps to run when setting up the image.
sourceDirectory source_directory Optional. Path to folders that contain all files to create the image.
enableGpu enable_gpu Optional. Whether to enable GPU support in the image. The GPU image must be used on an Azure service, like Azure Container Instances, Azure Machine Learning Compute, Azure Virtual Machines, and Azure Kubernetes Service. The default is False.
baseImage base_image Optional. Custom image to be used as a base image. If no base image is provided, the image will be based on the provided runtime parameter.
baseImageRegistry base_image_registry Optional. Image registry that contains the base image.
cudaVersion cuda_version Optional. Version of CUDA to install for images that need GPU support. The GPU image must be used on an Azure service, like Azure Container Instances, Azure Machine Learning Compute, Azure Virtual Machines, and Azure Kubernetes Service. Supported versions are 9.0, 9.1, and 10.0. If enable_gpu is set, the default is 9.1.
description description A description for the image.

The following JSON is an example inference configuration for use with the CLI:

{
    "entryScript": "score.py",
    "runtime": "python",
    "condaFile": "myenv.yml",
    "extraDockerfileSteps": null,
    "sourceDirectory": null,
    "enableGpu": false,
    "baseImage": null,
    "baseImageRegistry": null
}

Deployment configuration schema

Local deployment configuration schema

The entries in the deploymentconfig.json document map to the parameters for LocalWebservice.deploy_configuration. The following table describes the mapping between the entities in the JSON document and the parameters for the method:

JSON entity Method parameter Description
computeType NA The compute target. For local targets, the value must be local.
port port The local port on which to expose the service's HTTP endpoint.

This JSON is an example deployment configuration for use with the CLI:

{
    "computeType": "local",
    "port": 32267
}

Azure Container Instance deployment configuration schema

The entries in the deploymentconfig.json document map to the parameters for AciWebservice.deploy_configuration. The following table describes the mapping between the entities in the JSON document and the parameters for the method:

JSON entity Method parameter Description
computeType NA The compute target. For ACI, the value must be ACI.
containerResourceRequirements NA Container for the CPU and memory entities.
  cpu cpu_cores The number of CPU cores to allocate. Defaults, 0.1
  memoryInGB memory_gb The amount of memory (in GB) to allocate for this web service. Default, 0.5
location location The Azure region to deploy this Webservice to. If not specified the Workspace location will be used. More details on available regions can be found here: ACI Regions
authEnabled auth_enabled Whether to enable auth for this Webservice. Defaults to False
sslEnabled ssl_enabled Whether to enable SSL for this Webservice. Defaults to False.
appInsightsEnabled enable_app_insights Whether to enable AppInsights for this Webservice. Defaults to False
sslCertificate ssl_cert_pem_file The cert file needed if SSL is enabled
sslKey ssl_key_pem_file The key file needed if SSL is enabled
cname ssl_cname The cname for if SSL is enabled
dnsNameLabel dns_name_label The dns name label for the scoring endpoint. If not specified a unique dns name label will be generated for the scoring endpoint.

The following JSON is an example deployment configuration for use with the CLI:

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Azure Kubernetes Service deployment configuration schema

The entries in the deploymentconfig.json document map to the parameters for AksWebservice.deploy_configuration. The following table describes the mapping between the entities in the JSON document and the parameters for the method:

JSON entity Method parameter Description
computeType NA The compute target. For AKS, the value must be aks.
autoScaler NA Contains configuration elements for autoscale. See the autoscaler table.
  autoscaleEnabled autoscale_enabled Whether to enable autoscaling for the web service. If numReplicas = 0, True; otherwise, False.
  minReplicas autoscale_min_replicas The minimum number of containers to use when autoscaling this web service. Default, 1.
  maxReplicas autoscale_max_replicas The maximum number of containers to use when autoscaling this web service. Default, 10.
  refreshPeriodInSeconds autoscale_refresh_seconds How often the autoscaler attempts to scale this web service. Default, 1.
  targetUtilization autoscale_target_utilization The target utilization (in percent out of 100) that the autoscaler should attempt to maintain for this web service. Default, 70.
dataCollection NA Contains configuration elements for data collection.
  storageEnabled collect_model_data Whether to enable model data collection for the web service. Default, False.
authEnabled auth_enabled Whether or not to enable key authentication for the web service. Both tokenAuthEnabled and authEnabled cannot be True. Default, True.
tokenAuthEnabled token_auth_enabled Whether or not to enable token authentication for the web service. Both tokenAuthEnabled and authEnabled cannot be True. Default, False.
containerResourceRequirements NA Container for the CPU and memory entities.
  cpu cpu_cores The number of CPU cores to allocate for this web service. Defaults, 0.1
  memoryInGB memory_gb The amount of memory (in GB) to allocate for this web service. Default, 0.5
appInsightsEnabled enable_app_insights Whether to enable Application Insights logging for the web service. Default, False.
scoringTimeoutMs scoring_timeout_ms A timeout to enforce for scoring calls to the web service. Default, 60000.
maxConcurrentRequestsPerContainer replica_max_concurrent_requests The maximum concurrent requests per node for this web service. Default, 1.
maxQueueWaitMs max_request_wait_time The maximum time a request will stay in thee queue (in milliseconds) before a 503 error is returned. Default, 500.
numReplicas num_replicas The number of containers to allocate for this web service. No default value. If this parameter is not set, the autoscaler is enabled by default.
keys NA Contains configuration elements for keys.
  primaryKey primary_key A primary auth key to use for this Webservice
  secondaryKey secondary_key A secondary auth key to use for this Webservice
gpuCores gpu_cores The number of GPU cores to allocate for this Webservice. Default is 1. Only supports whole number values.
livenessProbeRequirements NA Contains configuration elements for liveness probe requirements.
  periodSeconds period_seconds How often (in seconds) to perform the liveness probe. Default to 10 seconds. Minimum value is 1.
  initialDelaySeconds initial_delay_seconds Number of seconds after the container has started before liveness probes are initiated. Defaults to 310
  timeoutSeconds timeout_seconds Number of seconds after which the liveness probe times out. Defaults to 2 seconds. Minimum value is 1
  successThreshold success_threshold Minimum consecutive successes for the liveness probe to be considered successful after having failed. Defaults to 1. Minimum value is 1.
  failureThreshold failure_threshold When a Pod starts and the liveness probe fails, Kubernetes will try failureThreshold times before giving up. Defaults to 3. Minimum value is 1.
namespace namespace The Kubernetes namespace that the webservice is deployed into. Up to 63 lowercase alphanumeric ('a'-'z', '0'-'9') and hyphen ('-') characters. The first and last characters can't be hyphens.

The following JSON is an example deployment configuration for use with the CLI:

{
    "computeType": "aks",
    "autoScaler":
    {
        "autoscaleEnabled": true,
        "minReplicas": 1,
        "maxReplicas": 3,
        "refreshPeriodInSeconds": 1,
        "targetUtilization": 70
    },
    "dataCollection":
    {
        "storageEnabled": true
    },
    "authEnabled": true,
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    }
}

Next steps