Azure AI ML Client Library

1.32.0 · active · verified Fri Apr 10

The Microsoft Azure Machine Learning Client Library for Python (also known as the 'v2 SDK') is the primary Python interface for interacting with Azure Machine Learning. It enables developers to build, train, and deploy machine learning models, manage workspaces, compute resources, data, environments, and jobs programmatically. It's actively developed, with frequent releases, often on a monthly cadence, aligning with Azure service updates. The current version is 1.32.0.

Warnings

breaking Migration from Azure ML SDK v1 (`azureml-sdk`) to v2 (`azure-ai-ml`) involves significant breaking changes. The API surface is largely different, with new classes and methods for defining resources and submitting jobs. Projects built on v1 are not directly compatible with v2.
Fix: Rewrite code to use the new v2 SDK paradigms. Refer to the official Azure ML v1 to v2 migration guide.
gotcha Authentication issues are common. `DefaultAzureCredential` attempts multiple authentication flows (e.g., Azure CLI, Managed Identity, Environment Variables, VS Code). If it fails, ensure you are logged in via `az login` or have relevant environment variables (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) correctly set.
Fix: Verify Azure CLI login (`az account show`), check permissions for your user/service principal on the ML workspace, and ensure required environment variables are correctly configured for programmatic access.
gotcha YAML schema for defining Azure ML resources (jobs, components, environments) can be strict and evolve. Subtle errors in YAML structure or parameter names can lead to validation failures or unexpected behavior.
Fix: Always refer to the latest Azure ML documentation for the correct YAML schema. Use `ml_client.jobs.validate()` (or similar for other entities) to proactively check your YAML definitions before submission. Ensure correct indentation and field names.

Install

pip install azure-ai-ml Install core library
pip install azure-ai-ml azure-identity Install with authentication

Imports

MLClient
```
from azure.ai.ml import MLClient
```
MLClient is the entry point for the v2 SDK, replacing Workspace from the v1 SDK (azureml-sdk).
DefaultAzureCredential
```
from azure.identity import DefaultAzureCredential
```
Authentication credentials are provided by the separate azure-identity library.
CommandJob
```
from azure.ai.ml.entities import CommandJob
```
Job-related entities and other assets are typically found under azure.ai.ml.entities.
Environment
```
from azure.ai.ml.entities import Environment
```
Similar to jobs, resource definitions like Environment are under azure.ai.ml.entities.

Quickstart

This quickstart demonstrates how to connect to an Azure Machine Learning workspace using the `MLClient` and `DefaultAzureCredential`. It retrieves workspace details from environment variables (or placeholders) and then lists the custom environments registered in the workspace. Ensure `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, and `AZURE_ML_WORKSPACE_NAME` environment variables are set, or replace placeholders with your actual values. Also, authenticate via Azure CLI (`az login`) or other methods for `DefaultAzureCredential` to work.

import os
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

# Configure Azure credentials and workspace details
subscription_id = os.environ.get('AZURE_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')
resource_group = os.environ.get('AZURE_RESOURCE_GROUP', 'YOUR_RESOURCE_GROUP')
workspace_name = os.environ.get('AZURE_ML_WORKSPACE_NAME', 'YOUR_WORKSPACE_NAME')

# Instantiate DefaultAzureCredential
try:
    credential = DefaultAzureCredential()
    # Check if credential works by getting a token (optional, but good for early validation)
    _ = credential.get_token('https://management.azure.com/.default')
except Exception as e:
    print(f"Authentication failed: {e}")
    print("Please ensure you are logged in to Azure CLI, VS Code, or have appropriate environment variables set.")
    exit(1)

# Create an MLClient instance
ml_client = MLClient(
    credential=credential,
    subscription_id=subscription_id,
    resource_group_name=resource_group,
    workspace_name=workspace_name
)

print(f"Connected to Azure ML workspace: {ml_client.workspace_name}")

# Example: List existing environments in the workspace
print("Listing existing environments...")
environments = ml_client.environments.list()
for env in environments:
    print(f"- {env.name} (version: {env.version})")

view raw JSON →