Azure ML HyperDrive REST Clients

1.62.0 · active · verified Thu Apr 16

This package contains internal classes and REST clients crucial for creating and managing HyperDriveRuns within the Azure Machine Learning SDK. It acts as an underlying dependency for the `azureml-core` package, specifically enabling the HyperDrive functionality for hyperparameter tuning. The current version is 1.62.0, and its release cadence follows the broader Azure ML SDK updates.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to set up and submit a HyperDrive experiment for hyperparameter tuning using the Azure Machine Learning V1 SDK. It includes workspace loading, compute target creation, environment definition, script configuration, hyperparameter sampling, and the HyperDrive configuration itself. Note that a `train.py` script is generated on the fly for demonstration purposes.

import os
from azureml.core import Workspace, Experiment, Environment
from azureml.core.compute import AmlCompute, ComputeTarget
from azureml.core.script_run_config import ScriptRunConfig
from azureml.train.hyperdrive import HyperDriveConfig, RandomParameterSampling, primary_metric_goal
from azureml.core.conda_dependencies import CondaDependencies

# NOTE: Replace with your actual workspace details or ensure config.json is present
# For quickstart, using dummy values for environment variables if not set
subscription_id = os.environ.get('AZUREML_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')
resource_group = os.environ.get('AZUREML_RESOURCE_GROUP', 'YOUR_RESOURCE_GROUP')
workspace_name = os.environ.get('AZUREML_WORKSPACE_NAME', 'YOUR_WORKSPACE_NAME')

# Create a dummy train.py for the example if it doesn't exist
# In a real scenario, this would be your actual training script
with open('train.py', 'w') as f:
    f.write("""
import argparse
import os
from azureml.core import Run

parser = argparse.ArgumentParser()
parser.add_argument('--learning_rate', type=float, default=0.01, help='Learning rate for training')
parser.add_argument('--momentum', type=float, default=0.9, help='Momentum for training')
args = parser.parse_args()

run = Run.get_context()

# Simulate training and log a metric
accuracy = 0.5 + args.learning_rate * 100 - args.momentum * 0.2 # Dummy calculation
run.log('accuracy', accuracy)
print(f"Run finished with accuracy: {accuracy}")
""")

try:
    ws = Workspace(subscription_id=subscription_id, resource_group=resource_group, workspace_name=workspace_name)
    print("Workspace loaded successfully.")
except Exception as e:
    print(f"Could not load workspace. Please ensure your config.json is correct or environment variables are set. Error: {e}")
    print("Attempting to create a dummy workspace for demonstration purposes only (will fail without real creds).")
    # This part is illustrative, it won't actually create a workspace without proper authentication
    ws = None # In a real scenario, you'd handle this or use Workspace.create()

if ws:
    # Create or get a compute target
    cluster_name = 'cpu-cluster-hd'
    try:
        compute_target = ComputeTarget(workspace=ws, name=cluster_name)
        print(f"Found existing compute target: {cluster_name}")
    except Exception:
        print(f"Creating new compute target: {cluster_name}")
        compute_config = AmlCompute.provisioning_configuration(vm_size='STANDARD_DS3_V2', max_nodes=2)
        compute_target = ComputeTarget.create(ws, cluster_name, compute_config)
        compute_target.wait_for_completion(show_output=True)

    # Define the environment
    conda_dep = CondaDependencies()
    conda_dep.add_pip_package('azureml-sdk') # Required for Run.get_context()
    env = Environment(name='hyperdrive-env')
    env.python.conda_dependencies = conda_dep
    env.docker.enabled = True # Use a docker base image
    env.register(workspace=ws)

    # Create a ScriptRunConfig for the training script
    src = ScriptRunConfig(source_directory='.', 
                          script='train.py', 
                          compute_target=compute_target, 
                          environment=env,
                          arguments=['--learning_rate', 0.01, '--momentum', 0.9]) # Initial values

    # Define hyperparameter sampling space
    param_sampling = RandomParameterSampling({
        '--learning_rate': [0.005, 0.01, 0.02, 0.05],
        '--momentum': [0.8, 0.9, 0.99]
    })

    # Configure HyperDrive
    hyperdrive_config = HyperDriveConfig(run_config=src,
                                         hyperparameter_sampling=param_sampling,
                                         primary_metric_name='accuracy',
                                         primary_metric_goal=primary_metric_goal.MAXIMIZE,
                                         max_total_runs=5,
                                         max_concurrent_runs=2)

    # Submit the HyperDrive run
    experiment = Experiment(workspace=ws, name='hyperdrive-example-run')
    hyperdrive_run = experiment.submit(hyperdrive_config)

    print(f"Submitted HyperDrive run: {hyperdrive_run.get_portal_url()}")
    hyperdrive_run.wait_for_completion(show_output=True)
    best_run = hyperdrive_run.get_best_run_by_primary_metric()
    print(f"Best run ID: {best_run.id}, Metrics: {best_run.get_metrics()}")
else:
    print("Skipping HyperDrive run submission due to failed workspace setup.")

view raw JSON →