AmlCompute class

Definition

Manages an Azure Machine Learning compute in Azure Machine Learning.

An Azure Machine Learning Compute (AmlCompute) is a managed-compute infrastructure that allows you to easily create a single or multi-node compute. The compute is created within your workspace region as a resource that can be shared with other users. For more information, see What are compute targets in Azure Machine Learning?

AmlCompute(workspace, name)
Inheritance
AmlCompute

Parameters

workspace
Workspace

The workspace object containing the AmlCompute object to retrieve.

name
str

The name of the of the AmlCompute object to retrieve.

Remarks

In the following example, a persistent compute target provisioned by AmlCompute is created. The provisioning_configuration parameter in this example is of type AmlComputeProvisioningConfiguration, which is a child class of ComputeTargetProvisioningConfiguration.


   from azureml.core.compute import ComputeTarget, AmlCompute
   from azureml.core.compute_target import ComputeTargetException

   # Choose a name for your CPU cluster
   cpu_cluster_name = "cpu-cluster"

   # Verify that cluster does not exist already
   try:
       cpu_cluster = ComputeTarget(workspace=ws, name=cpu_cluster_name)
       print('Found existing cluster, use it.')
   except ComputeTargetException:
       compute_config = AmlCompute.provisioning_configuration(vm_size='STANDARD_D2_V2',
                                                              max_nodes=4)
       cpu_cluster = ComputeTarget.create(ws, cpu_cluster_name, compute_config)

   cpu_cluster.wait_for_completion(show_output=True)

Full sample is available from https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/training/train-on-amlcompute/train-on-amlcompute.ipynb

Methods

delete()

Remove the AmlCompute object from its associated workspace.

deserialize(workspace, object_dict)

Convert a JSON object into an AmlCompute object.

detach()

Detach is not supported for AmlCompute object. Use delete() instead.

get()

Return compute object.

get_active_runs(type=None, tags=None, properties=None, status=None)

Return a generator of the runs for this compute.

get_status()

Retrieve the current detailed status for the AmlCompute cluster.

list_nodes()

Get the details (e.g., IP address, port, etc.) of all the compute nodes in the compute target.

list_quotas(workspace)

Get the currently assigned Workspace quotas based on VMFamily for given workspace and subscription.

list_usages(workspace, show_all=False)

Get the current usage information as well as limits for AML resources for given workspace and subscription.

provisioning_configuration(vm_size='', vm_priority='dedicated', min_nodes=0, max_nodes=None, idle_seconds_before_scaledown=None, admin_username=None, admin_user_password=None, admin_user_ssh_key=None, vnet_resourcegroup_name=None, vnet_name=None, subnet_name=None, tags=None, description=None, remote_login_port_public_access='NotSpecified')

Create a configuration object for provisioning an AmlCompute target.

refresh_state()

Perform an in-place update of the properties of the object.

This method updates the properties based on the current state of the corresponding cloud object. This is primarily used for manual polling of compute state.

serialize()

Convert this AmlCompute object into a JSON serialized dictionary.

supported_vmsizes(workspace, location=None)

List the supported VM sizes in a region.

update(min_nodes=None, max_nodes=None, idle_seconds_before_scaledown=None)

Update the ScaleSettings for this AmlCompute target.

update_quotas(workspace, vm_family, limit=None)

Update quota for a VM family in workspace.

wait_for_completion(show_output=False, min_node_count=None, timeout_in_minutes=20)

Wait for the AmlCompute cluster to finish provisioning.

This can be configured to wait for a minimum number of nodes, and to timeout after a set period of time.

delete()

Remove the AmlCompute object from its associated workspace.

delete()

Remarks

If this object was created through Azure Machine Learning, the corresponding cloud-based objects will also be deleted. If this object was created externally and only attached to the workspace, this method raises a ComputeTargetException and nothing is changed.

deserialize(workspace, object_dict)

Convert a JSON object into an AmlCompute object.

deserialize(workspace, object_dict)

Parameters

workspace
Workspace

The workspace object the AmlCompute object is associated with.

object_dict
dict

A JSON object to convert to an AmlCompute object.

Returns

The AmlCompute representation of the provided JSON object.

Return type

Exceptions

Remarks

Raises a ComputeTargetException if the provided workspace is not the workspace the Compute is associated with.

detach()

Detach is not supported for AmlCompute object. Use delete() instead.

detach()

get()

Return compute object.

get()

get_active_runs(type=None, tags=None, properties=None, status=None)

Return a generator of the runs for this compute.

get_active_runs(type=None, tags=None, properties=None, status=None)

Parameters

type
str
default value: None

Filter the returned generator of runs by the provided type. See add_type_provider(runtype, run_factory) for creating run types.

tags
str or dict
default value: None

Filter runs by "tag" or {"tag": "value"}

properties
str or dict
default value: None

Filter runs by "property" or {"property": "value"}

status
str
default value: None

Run status - either "Running" or "Queued"

Returns

a generator of ~_restclient.models.RunDto

Return type

builtin.generator

get_status()

Retrieve the current detailed status for the AmlCompute cluster.

get_status()

Returns

A detailed status object for the cluster

Return type

list_nodes()

Get the details (e.g., IP address, port, etc.) of all the compute nodes in the compute target.

list_nodes()

Returns

The details of all the compute nodes in the compute target.

Return type

list_quotas(workspace)

Get the currently assigned Workspace quotas based on VMFamily for given workspace and subscription.

list_quotas(workspace)

Parameters

workspace
Workspace

Returns

List of currently assigned Workspace Quotas based on VMFamily

Return type

list_usages(workspace, show_all=False)

Get the current usage information as well as limits for AML resources for given workspace and subscription.

list_usages(workspace, show_all=False)

Parameters

workspace
Workspace
show_all
default value: False

Specifies if detailed usages of child resources are required. Defaults to False

Returns

List of current usage information as well as limits for AML resources

Return type

provisioning_configuration(vm_size='', vm_priority='dedicated', min_nodes=0, max_nodes=None, idle_seconds_before_scaledown=None, admin_username=None, admin_user_password=None, admin_user_ssh_key=None, vnet_resourcegroup_name=None, vnet_name=None, subnet_name=None, tags=None, description=None, remote_login_port_public_access='NotSpecified')

Create a configuration object for provisioning an AmlCompute target.

provisioning_configuration(vm_size='', vm_priority='dedicated', min_nodes=0, max_nodes=None, idle_seconds_before_scaledown=None, admin_username=None, admin_user_password=None, admin_user_ssh_key=None, vnet_resourcegroup_name=None, vnet_name=None, subnet_name=None, tags=None, description=None, remote_login_port_public_access='NotSpecified')

Parameters

vm_size
str

The size of agent VMs. More details can be found here: https://aka.ms/azureml-vm-details. Note that not all sizes are available in all regions, as detailed in the previous link. If not specified, defaults to Standard_NC6.

vm_priority
str
default value: dedicated

The VM priority, dedicated or lowpriority.

min_nodes
int
default value: 0

The minimum number of nodes to use on the cluster. If not specified, defaults to 0.

max_nodes
int
default value: None

The maximum number of nodes to use on the cluster. If not specified, defaults to 4.

idle_seconds_before_scaledown
int
default value: None

Node idle time in seconds before scaling down the cluster. If not specified, defaults to 120.

admin_username
str
default value: None

The name of the administrator user account which can be used to SSH into nodes.

admin_user_password
str
default value: None

The password of the administrator user account.

admin_user_ssh_key
str
default value: None

The SSH public key of the administrator user account.

vnet_resourcegroup_name
str
default value: None

The name of the resource group where the virtual network is located.

vnet_name
str
default value: None

The name of the virtual network.

subnet_name
str
default value: None

The name of the subnet inside the VNet.

tags
dict[str, str]
default value: None

A dictionary of key value tags to provide to the compute object.

description
str
default value: None

A description to provide to the compute object.

remote_login_port_public_access
str
default value: NotSpecified

State of the public SSH port. Possible values are:

  • Disabled - Indicates that the public ssh port is closed on all nodes of the cluster.

  • Enabled - Indicates that the public ssh port is open on all nodes of the cluster.

  • NotSpecified - Indicates that the public ssh port is closed on all nodes of the cluster if VNet is defined, else is open all public nodes. It can be this default value only during cluster creation time. After creation, it will be either enabled or disabled.

Returns

A configuration object to be used when creating a Compute object.

Return type

Exceptions

refresh_state()

Perform an in-place update of the properties of the object.

This method updates the properties based on the current state of the corresponding cloud object. This is primarily used for manual polling of compute state.

refresh_state()

serialize()

Convert this AmlCompute object into a JSON serialized dictionary.

serialize()

Returns

The JSON representation of this AmlCompute object.

Return type

supported_vmsizes(workspace, location=None)

List the supported VM sizes in a region.

supported_vmsizes(workspace, location=None)

Parameters

workspace
Workspace
location
str
default value: None

The location of cluster. If not specified, will default to workspace location.

Returns

A list of supported VM sizes in a region with names of the VM, VCPUs, and RAM.

Return type

update(min_nodes=None, max_nodes=None, idle_seconds_before_scaledown=None)

Update the ScaleSettings for this AmlCompute target.

update(min_nodes=None, max_nodes=None, idle_seconds_before_scaledown=None)

Parameters

min_nodes
int
default value: None

The minimum number of nodes to use on the cluster.

max_nodes
int
default value: None

The maximum number of nodes to use on the cluster.

idle_seconds_before_scaledown
int
default value: None

The node idle time in seconds before scaling down the cluster.

update_quotas(workspace, vm_family, limit=None)

Update quota for a VM family in workspace.

update_quotas(workspace, vm_family, limit=None)

Parameters

workspace
Workspace
vm_family
str

VM family name

limit
int
default value: None

The maximum permitted quota of the resource

wait_for_completion(show_output=False, min_node_count=None, timeout_in_minutes=20)

Wait for the AmlCompute cluster to finish provisioning.

This can be configured to wait for a minimum number of nodes, and to timeout after a set period of time.

wait_for_completion(show_output=False, min_node_count=None, timeout_in_minutes=20)

Parameters

show_output
bool
default value: False

Boolean to provide more verbose output.

min_node_count
int
default value: None

Minimum number of nodes to wait for before considering provisioning to be complete. This doesn't have to equal the minimum number of nodes that the compute was provisioned with, however it should not be greater than that.

timeout_in_minutes
int
default value: 20

The duration in minutes to wait before considering provisioning to have failed.

Exceptions