core Package

  • Reference

Contains core packages, modules, and classes for Azure Machine Learning.

Main areas include managing compute targets, creating/managing workspaces and experiments, and submitting/accessing model runs and run output/logging.

Packages

compute

This package contains classes used to manage compute targets in Azure Machine Learning.

For more information about choosing compute targets for training and deployment, see What are compute targets in Azure Machine Learning?
image

Contains functionality for managing images that are deployed as web service endpoints in Azure Machine Learning.

This class is DEPRECATED. Use the Environment class instead.

An Image is used to deploy a Model, script, and associated files as a web service endpoint or IoT Edge device. The endpoint handles incoming scoring requests and return predictions. This package's key classes are the Image class, the parent class of Azure Machine Learning images, and the derived ContainerImage class for Docker Images as well as preview Images like FPGA.

Unless you have a workflow that specifically requires using images, you should instead use the Environment class to define your image. Then you can use the Environment object with the Model deploy() method to deploy the model as a web service. You can also use the Model package() method to create an image that can be downloaded to your local Docker install as an image or as a Dockerfile.

For information on using the Model class, see Deploy models with Azure Machine Learning.

For information on using custom images, see Deploy a model using a custom Docker base image.
webservice

Contains functionality for deploying machine learning models as web service endpoints in Azure Machine Learning.

Deploying an Azure Machine Learning model as a web service creates an endpoint and a REST API. You can send data to this API and receive the prediction returned by the model.

You create a web service when you deploy a Model or Image to Azure Container Instances (aci module), Azure Kubernetes Service (aks module) and Azure Kubernetes Endpoint (AksEndpoint), or field-programmable gate arrays (FPGA). Deployment using a model is recommended for most use cases, while deployment using an image is recommended for advanced use cases. Both types of deployment are supported in the classes in this module.

Modules

authentication

Contains functionality for managing different types of authentication in Azure Machine Learning.

Types of supported authentication:

  • Interactive Login - The default mode when using Azure Machine Learning SDK. Uses an interactive dialog.
  • Azure CLI - For use with the azure-cli package.
  • Service Principal - For use with automated machine learning workflows.
  • MSI - For use with Managed Service Identity-enabled assets such as with an Azure Virtual Machine.
  • Azure ML Token - Used for acquiring Azure ML tokens for submitted runs only.

To learn more about these authentication mechanisms, see https://aka.ms/aml-notebook-auth.
compute_target

Contains functionality for compute targets not managed by Azure Machine Learning.

Compute targets define your training compute environment, and can be either local, or remote resources in the cloud. Remote resources allow you to easily scale up or scale out your machine learning experimentation by taking advantage of accelerated CPU and GPU processing capabilities.

For information on compute targets managed by Azure Machine Learning, see the ComputeTarget class. For more information, see What are compute targets in Azure Machine Learning?
conda_dependencies

Contains functionality for managing conda environment dependencies.

Use the CondaDependencies class to load existing conda environment files and configure and manage new environments where experiments execute.
container_registry

Contains functionality for managing an Azure Container Registry.
databricks

Contains functionality for managing Databricks environments in Azure Machine Learning.

For more information on working with Databricks in Azure Machine Learning, see Configure a development environment for Azure Machine Learning.
dataset

Manages the interaction with Azure Machine Learning Datasets.

This module provides functionality for consuming raw data, managing data, and performing actions on data in Azure Machine Learning. Use the Dataset class in this module to create datasets along with the functionality in the data package, which contains the supporting classes FileDataset and TabularDataset.

To get started with datasets, see the article Add & register datasets.
datastore

Contains functionality for managing Datastores in Azure Machine Learning.
environment

Contains functionality for creating and managing reproducible environments in Azure Machine Learning.

Environments provide a way to manage software dependency so that controlled environments are reproducible with minimal manual configuration as you move between local and distributed cloud development environments. An environment encapsulates Python packages, environment variables, software settings for training and scoring scripts, and run times on either Python, Spark, or Docker. For more information about using environments for training and deployment with Azure Machine Learning, see Create and manage reusable environments.
experiment

Contains functionality used to submit experiments and manage experiment history in Azure Machine Learning.
keyvault

Contains functionality for managing secrets in the Key Vault associated with an Azure Machine Learning workspace.

This module contains convenience methods for adding, retrieving, deleting and listing secrets from the Azure Key Vault associated with a workspace.
linked_service

Contains functionality for creating and managing linked service in AML workspace.
model

Contains functionality for managing machine learning models in Azure Machine Learning.

With the Model class, you can accomplish the following main tasks:

  • register your model with a workspace
  • profile your model to understand deployment requirements
  • package your model for use with Docker
  • deploy your model to an inference endpoint as a web service

For more information on how models are used, see How Azure Machine Learning works: Architecture and concepts.
private_endpoint

Contains functionality for defining and configuring Azure Private EndPoints.
profile

Contains functionality for profiling models in Azure Machine Learning.
resource_configuration

Contains functionality for managing resources configuration for Azure Machine Learning entities.
run

Contains functionality for managing experiment metrics and artifacts in Azure Machine Learning.
runconfig

Contains functionality for managing the configuration of experiment runs in Azure Machine Learning.

The key class in this module is RunConfiguration, which encapsulates information necessary to submit a training run on a specified compute target. The configuration includes a wide set of behavior definitions, such as whether to use an existing Python environment or to use a Conda environment that's built from a specification.

Other configuration classes in the module are accessed through RunConfiguration.
script_run

Contains functionality for managing submitted training runs in Azure Machine Learning.
script_run_config

Contains functionality to manage configuration for submitting training runs in Azure Machine Learning.
util

Contains class for specifying logging detail level.
workspace

Contains functionality for managing a workspace, the top-level resource in Azure Machine Learning.

This module contains the Workspace class and its methods and attributes that allows you to manage machine learning artifacts like compute targets, environments, data stores, experiments, and models. A workspace is tied to an Azure subscription and resource group, and is the primary means for billing. Workspaces support Azure Resource Manager role-based access control (RBAC) and region affinity for all machine learning data saved within the workspace.

Classes

ComputeTarget

Abstract parent class for all compute targets managed by Azure Machine Learning.

A compute target is a designated compute resource/environment where you run your training script or host your service deployment. This location may be your local machine or a cloud-based compute resource. For more information, see What are compute targets in Azure Machine Learning?

Class ComputeTarget constructor.

Retrieve a cloud representation of a Compute object associated with the provided workspace. Returns an instance of a child class corresponding to the specific type of the retrieved Compute object.
ContainerRegistry

Defines a connection to an Azure Container Registry.

Class ContainerRegistry constructor.
Dataset

Represents a resource for exploring, transforming, and managing data in Azure Machine Learning.

A Dataset is a reference to data in a Datastore or behind public web urls.

For methods deprecated in this class, please check AbstractDataset class for the improved APIs.

The following Datasets types are supported:

  • TabularDataset represents data in a tabular format created by parsing the provided file or list of files.

  • FileDataset references single or multiple files in datastores or from public URLs.

To get started with datasets, see the article Add & register datasets, or see the notebooks https://aka.ms/tabulardataset-samplenotebook and https://aka.ms/filedataset-samplenotebook.

Initialize the Dataset object.

To obtain a Dataset that has already been registered with the workspace, use the get method.
Datastore

Represents a storage abstraction over an Azure Machine Learning storage account.

Datastores are attached to workspaces and are used to store connection information to Azure storage services so you can refer to them by name and don't need to remember the connection information and secret used to connect to the storage services.

Examples of supported Azure storage services that can be registered as datastores are:

  • Azure Blob Container

  • Azure File Share

  • Azure Data Lake

  • Azure Data Lake Gen2

  • Azure SQL Database

  • Azure Database for PostgreSQL

  • Databricks File System

  • Azure Database for MySQL

Use this class to perform management operations, including register, list, get, and remove datastores. Datastores for each service are created with the register* methods of this class. When using a datastore to access data, you must have permission to access that data, which depends on the credentials registered with the datastore.

For more information on datastores and how they can be used in machine learning see the following articles:

Get a datastore by name. This call will make a request to the datastore service.
Environment

Configures a reproducible Python environment for machine learning experiments.

An Environment defines Python packages, environment variables, and Docker settings that are used in machine learning experiments, including in data preparation, training, and deployment to a web service. An Environment is managed and versioned in an Azure Machine Learning Workspace. You can update an existing environment and retrieve a version to reuse. Environments are exclusive to the workspace they are created in and can't be used across different workspaces.

For more information about environments, see Create and manage reusable environments.

Class Environment constructor.
Experiment

Represents the main entry point for creating and working with experiments in Azure Machine Learning.

An Experiment is a container of trials that represent multiple model runs.

Experiment constructor.
Image

Defines the abstract parent class for Azure Machine Learning Images.

This class is DEPRECATED. Use the Environment class instead.

Image constructor.

This class is DEPRECATED. Use the Environment class instead.

Image constructor is used to retrieve a cloud representation of a Image object associated with the provided workspace. Will return an instance of a child class corresponding to the specific type of the retrieved Image object.
Keyvault

Manages secrets stored in the Azure Key Vault associated with an Azure Machine Learning workspace.

Each Azure Machine Learning workspace has an associated Azure Key Vault. The Keyvault class is a simplified wrapper of the Azure Key Vault that allows you to manage secrets in the key vault including setting, retrieving, deleting, and listing secrets. Use the Keyvault class to pass secrets to remote runs securely without exposing sensitive information in cleartext.

For more information, see Using secrets in training runs.

Class Keyvault constructor.
LinkedService

Note

This is an experimental class, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

Defines an Resource for managing linking between AML workspace with other services on Azure.

Initialize LinkedService object.
Model

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 a real-time endpoint that can be used for inference requests.

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 constructor.

The Model constructor is used to retrieve a cloud representation of a Model object associated with the provided workspace. Must provide either name or ID.
PrivateEndPoint

Defines a private endpoint for managing private endpoint connections associated with an Azure ML workspace.

Initialize PrivateEndPoint.
PrivateEndPointConfig

Defines configuration for an Azure Private EndPoint.

Azure Private Endpoint is a network interface that connects you privately and securely to a Azure ML workspace with Private Link.

Initialize PrivateEndPointConfig.
Run

Defines the base class for all Azure Machine Learning experiment runs.

A run represents a single trial of an experiment. Runs are used to monitor the asynchronous execution of a trial, log metrics and store output of the trial, and to analyze results and access artifacts generated by the trial.

Run objects are created when you submit a script to train a model in many different scenarios in Azure Machine Learning, including HyperDrive runs, Pipeline runs, and AutoML runs. A Run object is also created when you submit or start_logging with the Experiment class.

To get started with experiments and runs, see

Initialize the Run object.
RunConfiguration

Represents configuration for experiment runs targeting different compute targets in Azure Machine Learning.

The RunConfiguration object encapsulates the information necessary to submit a training run in an experiment. Typically, you will not create a RunConfiguration object directly but get one from a method that returns it, such as the submit method of the Experiment class.

RunConfiguration is a base environment configuration that is also used in other types of configuration steps that depend on what kind of run you are triggering. For example, when setting up a PythonScriptStep, you can access the step's RunConfiguration object and configure Conda dependencies or access the environment properties for the run.

For examples of run configurations, see Select and use a compute target to train your model.

Initialize a RunConfiguration with the default settings.
ScriptRun

Provides programmatic access for managing submitted training runs.

A run submitted with ScriptRunConfig represents a single trial in an experiment. Submitting the run returns a ScriptRun object, which can be used to monitor the asynchronous execution of the run, log metrics and store output of the run, and analyze results and access artifacts generated by the run.

To get started with experiments and ScriptRunConf, see

Class ScriptRun constructor.
ScriptRunConfig

Represents configuration information for submitting a training run in Azure Machine Learning.

A ScriptRunConfig packages together the configuration information needed to submit a run in Azure ML, including the script, compute target, environment, and any distributed job-specific configs.

Once a script run is configured and submitted with the submit, a ScriptRun is returned.

Class ScriptRunConfig constructor.
SynapseWorkspaceLinkedServiceConfiguration

Note

This is an experimental class, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

Defines a linked service configuration for linking synapse workspace.

Initialize SynapseWorkspaceLinkedServiceConfiguration object.
Webservice

Defines base functionality for deploying models as web service endpoints in Azure Machine Learning.

Webservice constructor is used to retrieve a cloud representation of a Webservice object associated with the provided Workspace. Returns an instance of a child class corresponding to the specific type of the retrieved Webservice object. The Webservice class allows for deploying machine learning models from either a Model or Image object.

For more information about working with Webservice, see Deploy models with Azure Machine Learning.

Initialize the Webservice instance.

The Webservice constructor retrieves a cloud representation of a Webservice object associated with the provided workspace. It will return an instance of a child class corresponding to the specific type of the retrieved Webservice object.
Workspace

Defines an Azure Machine Learning resource for managing training and deployment artifacts.

A Workspace is a fundamental resource for machine learning in Azure Machine Learning. You use a workspace to experiment, train, and deploy machine learning models. Each workspace is tied to an Azure subscription and resource group, and has an associated SKU.

For more information about workspaces, see:

Class Workspace constructor to load an existing Azure Machine Learning Workspace.
diagnostic_log

Directs debug logs to a specified file.

Functions

attach_legacy_compute_target

Attaches a compute target to this project.

attach_legacy_compute_target(experiment, source_directory, compute_target)

Parameters

experiment
Experiment
Required
source_directory
str
Required
compute_target
str
Required

A compute target object to attach.

Returns

None if the attach is successful, otherwise throws an exception.

get_run

Get the run for this experiment with its run ID.

get_run(experiment, run_id, rehydrate=True, clean_up=True)

Parameters

experiment
Experiment
Required

The containing experiment.

run_id
string
Required

The run ID.

rehydrate
<xref:boolean>
default value: True

Indicates whether the original run object is returned or just a base run object. If True, this function returns the original run object type. For example, for an AutoML run, an AutoMLRun object is returned, while for a HyperDrive run, a HyperDriveRun object is returned.

If False, the function returns a Run object.

clean_up
bool
default value: True

If true, call _register_kill_handler from run_base

Returns

The submitted run.

Return type

Run

is_compute_target_prepared

Check compute target is prepared.

Checks whether the compute target, specified in run_config, is already prepared or not for the specified run configuration.

is_compute_target_prepared(experiment, source_directory, run_config)

Parameters

experiment
Experiment
Required
source_directory
str
Required
run_config
str or RunConfiguration
Required

The run configuration. This can be a run configuration name, as string, or a azureml.core.runconfig.RunConfiguration object.

Returns

True, if the compute target is prepared.

Return type

bool

prepare_compute_target

Prepare the compute target.

Installs all the required packages for an experiment run based on run_config and custom_run_config.

prepare_compute_target(experiment, source_directory, run_config)

Parameters

experiment
Experiment
Required
source_directory
str
Required
run_config
str or RunConfiguration
Required

The run configuration. This can be a run configuration name, as string, or a azureml.core.runconfig.RunConfiguration object.

Returns

A run object

Return type

ScriptRun

remove_legacy_compute_target

Remove a compute target from the project.

remove_legacy_compute_target(experiment, source_directory, compute_target_name)

Parameters

experiment
Experiment
Required
source_directory
str
Required
compute_target_name
str
Required

Returns

None if the removal of the compute target is successful, otherwise throws an exception.

Return type

None