{"id":7037,"library":"azureml-train-restclients-hyperdrive","title":"Azure ML HyperDrive REST Clients","description":"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.","status":"active","version":"1.62.0","language":"en","source_language":"en","source_url":"https://docs.microsoft.com/python/api/azureml-sdk-for-python/","tags":["azure","machine learning","hyperparameter tuning","hyperdrive","sdk","v1"],"install":[{"cmd":"pip install azureml-train-restclients-hyperdrive","lang":"bash","label":"Install specific client"},{"cmd":"pip install azureml-core[train]","lang":"bash","label":"Recommended for full functionality"}],"dependencies":[],"imports":[{"note":"User-facing classes like HyperDriveConfig are exposed via the higher-level `azureml.train.hyperdrive` module, not directly from this internal client package.","wrong":"from azureml.train.restclients.hyperdrive import HyperDriveConfig","symbol":"HyperDriveConfig","correct":"from azureml.train.hyperdrive import HyperDriveConfig"},{"note":"Similar to HyperDriveConfig, parameter sampling classes are part of the public `azureml.train.hyperdrive` interface.","wrong":"from azureml.train.restclients.hyperdrive import RandomParameterSampling","symbol":"RandomParameterSampling","correct":"from azureml.train.hyperdrive import RandomParameterSampling"}],"quickstart":{"code":"import os\nfrom azureml.core import Workspace, Experiment, Environment\nfrom azureml.core.compute import AmlCompute, ComputeTarget\nfrom azureml.core.script_run_config import ScriptRunConfig\nfrom azureml.train.hyperdrive import HyperDriveConfig, RandomParameterSampling, primary_metric_goal\nfrom azureml.core.conda_dependencies import CondaDependencies\n\n# NOTE: Replace with your actual workspace details or ensure config.json is present\n# For quickstart, using dummy values for environment variables if not set\nsubscription_id = os.environ.get('AZUREML_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')\nresource_group = os.environ.get('AZUREML_RESOURCE_GROUP', 'YOUR_RESOURCE_GROUP')\nworkspace_name = os.environ.get('AZUREML_WORKSPACE_NAME', 'YOUR_WORKSPACE_NAME')\n\n# Create a dummy train.py for the example if it doesn't exist\n# In a real scenario, this would be your actual training script\nwith open('train.py', 'w') as f:\n    f.write(\"\"\"\nimport argparse\nimport os\nfrom azureml.core import Run\n\nparser = argparse.ArgumentParser()\nparser.add_argument('--learning_rate', type=float, default=0.01, help='Learning rate for training')\nparser.add_argument('--momentum', type=float, default=0.9, help='Momentum for training')\nargs = parser.parse_args()\n\nrun = Run.get_context()\n\n# Simulate training and log a metric\naccuracy = 0.5 + args.learning_rate * 100 - args.momentum * 0.2 # Dummy calculation\nrun.log('accuracy', accuracy)\nprint(f\"Run finished with accuracy: {accuracy}\")\n\"\"\")\n\ntry:\n    ws = Workspace(subscription_id=subscription_id, resource_group=resource_group, workspace_name=workspace_name)\n    print(\"Workspace loaded successfully.\")\nexcept Exception as e:\n    print(f\"Could not load workspace. Please ensure your config.json is correct or environment variables are set. Error: {e}\")\n    print(\"Attempting to create a dummy workspace for demonstration purposes only (will fail without real creds).\")\n    # This part is illustrative, it won't actually create a workspace without proper authentication\n    ws = None # In a real scenario, you'd handle this or use Workspace.create()\n\nif ws:\n    # Create or get a compute target\n    cluster_name = 'cpu-cluster-hd'\n    try:\n        compute_target = ComputeTarget(workspace=ws, name=cluster_name)\n        print(f\"Found existing compute target: {cluster_name}\")\n    except Exception:\n        print(f\"Creating new compute target: {cluster_name}\")\n        compute_config = AmlCompute.provisioning_configuration(vm_size='STANDARD_DS3_V2', max_nodes=2)\n        compute_target = ComputeTarget.create(ws, cluster_name, compute_config)\n        compute_target.wait_for_completion(show_output=True)\n\n    # Define the environment\n    conda_dep = CondaDependencies()\n    conda_dep.add_pip_package('azureml-sdk') # Required for Run.get_context()\n    env = Environment(name='hyperdrive-env')\n    env.python.conda_dependencies = conda_dep\n    env.docker.enabled = True # Use a docker base image\n    env.register(workspace=ws)\n\n    # Create a ScriptRunConfig for the training script\n    src = ScriptRunConfig(source_directory='.', \n                          script='train.py', \n                          compute_target=compute_target, \n                          environment=env,\n                          arguments=['--learning_rate', 0.01, '--momentum', 0.9]) # Initial values\n\n    # Define hyperparameter sampling space\n    param_sampling = RandomParameterSampling({\n        '--learning_rate': [0.005, 0.01, 0.02, 0.05],\n        '--momentum': [0.8, 0.9, 0.99]\n    })\n\n    # Configure HyperDrive\n    hyperdrive_config = HyperDriveConfig(run_config=src,\n                                         hyperparameter_sampling=param_sampling,\n                                         primary_metric_name='accuracy',\n                                         primary_metric_goal=primary_metric_goal.MAXIMIZE,\n                                         max_total_runs=5,\n                                         max_concurrent_runs=2)\n\n    # Submit the HyperDrive run\n    experiment = Experiment(workspace=ws, name='hyperdrive-example-run')\n    hyperdrive_run = experiment.submit(hyperdrive_config)\n\n    print(f\"Submitted HyperDrive run: {hyperdrive_run.get_portal_url()}\")\n    hyperdrive_run.wait_for_completion(show_output=True)\n    best_run = hyperdrive_run.get_best_run_by_primary_metric()\n    print(f\"Best run ID: {best_run.id}, Metrics: {best_run.get_metrics()}\")\nelse:\n    print(\"Skipping HyperDrive run submission due to failed workspace setup.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always install `pip install azureml-core[train]` and import from `azureml.train.hyperdrive` for user-facing HyperDrive functionality.","message":"The `azureml-train-restclients-hyperdrive` package is primarily an internal dependency of the Azure ML SDK. End-users typically install `azureml-core` or `azureml-sdk` and import HyperDrive-related classes (like `HyperDriveConfig`) from `azureml.train.hyperdrive`. Direct imports from `azureml.train.restclients.hyperdrive` are uncommon and may lead to missing functionality or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For new projects, consider migrating to the V2 SDK (`azure.ai.ml`) and using `MLClient.sweep()` for hyperparameter tuning. Existing V1 projects can continue to use `azureml.train.hyperdrive` but should plan for eventual migration.","message":"The V1 SDK (`azureml.*`) approach for HyperDrive, which this package supports, is being superseded by the V2 SDK (`azure.ai.ml`). While V1 is still supported, Microsoft encourages using V2 for new projects, which leverages `MLClient.sweep()` for hyperparameter tuning workflows.","severity":"deprecated","affected_versions":"All versions (future V1 deprecation)"},{"fix":"Carefully review the migration guide from V1 to V2 if you plan to upgrade your Azure ML SDK usage. Ensure consistency in using either V1 (`azureml.train.hyperdrive`) or V2 (`azure.ai.ml.sweep`) components within your application.","message":"There are significant API differences between Azure ML SDK V1 (`azureml.*`) and V2 (`azure.ai.ml`). Code written for V1 is not directly compatible with V2, requiring a migration path. This specific `azureml-train-restclients-hyperdrive` package is part of the V1 SDK.","severity":"breaking","affected_versions":"Transition from V1 to V2 SDK"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the complete Azure ML SDK training components: `pip install azureml-core[train]` or `pip install azureml-sdk`.","cause":"You have installed `azureml-train-restclients-hyperdrive` but not the full `azureml-core` or `azureml-sdk` package which exposes the `azureml.train.hyperdrive` module.","error":"ModuleNotFoundError: No module named 'azureml.train.hyperdrive'"},{"fix":"Change your import statement to `from azureml.train.hyperdrive import HyperDriveConfig` after ensuring `azureml-core[train]` is installed.","cause":"You are attempting to import a user-facing class like `HyperDriveConfig` directly from the internal `azureml.train.restclients.hyperdrive` module instead of its public entry point.","error":"AttributeError: module 'azureml.train.restclients.hyperdrive' has no attribute 'HyperDriveConfig'"},{"fix":"Ensure you are consistently using either the V1 SDK (e.g., `Experiment.submit(HyperDriveConfig)`) or the V2 SDK (e.g., `MLClient.sweep(sweep_job)`) components. Do not mix V1 configuration objects with V2 client submission methods.","cause":"This error can occur if you're trying to pass a V1 `HyperDriveConfig` object to a function expecting a V2 SDK sweep job definition, or vice-versa.","error":"TypeError: 'HyperDriveConfig' object is not iterable"}]}