sdk/python/jobs/pipelines/1c_pipeline_with_hyperparameter_sweep/pipeline_with_hyperparameter_sweep.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Build pipeline with sweep node\n",
    "\n",
    "**Requirements** - In order to benefit from this tutorial, you will need:\n",
    "- A basic understanding of Machine Learning\n",
    "- An Azure account with an active subscription - [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)\n",
    "- An Azure ML workspace with computer cluster - [Configure workspace](../../configuration.ipynb)\n",
    "- A python environment\n",
    "- Installed Azure Machine Learning Python SDK v2 - [install instructions](../../../README.md) - check the getting started section\n",
    "\n",
    "**Learning Objectives** - By the end of this tutorial, you should be able to:\n",
    "- Connect to your AML workspace from the Python SDK\n",
    "- Create sweep node with `sweep()`\n",
    "- Create `Pipeline` with sweep node\n",
    "\n",
    "**Motivations** - This notebook explains how to create a sweep node by using `sweep()` and use it in a pipeline. A sweep node can be used to enable hyperparameter tuning on a specified compute (either local or on the cloud) for a specific command component. You can define a `search_space` and an `objective` to search for the target output.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Connect to Azure Machine Learning Workspace\n",
    "\n",
    "The [workspace](https://docs.microsoft.com/en-us/azure/machine-learning/concept-workspace) is the top-level resource for Azure Machine Learning, providing a centralized place to work with all the artifacts you create when you use Azure Machine Learning. In this section we will connect to the workspace in which the job will be run.\n",
    "\n",
    "## 1.1 Import the required libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import required libraries\n",
    "from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential\n",
    "\n",
    "from azure.ai.ml import MLClient, Input\n",
    "from azure.ai.ml.dsl import pipeline\n",
    "from azure.ai.ml import load_component\n",
    "from azure.ai.ml.sweep import (\n",
    "    Choice,\n",
    "    Uniform,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.2 Configure credential\n",
    "\n",
    "We are using `DefaultAzureCredential` to get access to workspace. \n",
    "`DefaultAzureCredential` should be capable of handling most Azure SDK authentication scenarios. \n",
    "\n",
    "Reference for more available credentials if it does not work for you: [configure credential example](../../configuration.ipynb), [azure-identity reference doc](https://docs.microsoft.com/en-us/python/api/azure-identity/azure.identity?view=azure-python)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    credential = DefaultAzureCredential()\n",
    "    # Check if given credential can get token successfully.\n",
    "    credential.get_token(\"https://management.azure.com/.default\")\n",
    "except Exception as ex:\n",
    "    # Fall back to InteractiveBrowserCredential in case DefaultAzureCredential not work\n",
    "    credential = InteractiveBrowserCredential()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1.3 Get a handle to the workspace\n",
    "\n",
    "We use config file to connect to a workspace. The Azure ML workspace should be configured with computer cluster. [Check this notebook for configure a workspace](../../configuration.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a handle to workspace\n",
    "ml_client = MLClient.from_config(credential=credential)\n",
    "\n",
    "# Retrieve an already attached Azure Machine Learning Compute.\n",
    "cluster_name = \"cpu-cluster\"\n",
    "print(ml_client.compute.get(cluster_name))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. Pipeline job with hyperparameter sweep\n",
    "\n",
    "## 2.1 Build pipeline\n",
    "In pipeline definition, we define `search_space` for hyperparameter sweep in inputs of `train_model` and call `train_model.sweep()` to create a sweep node based on `train_model` with specific run settings. Run settings includes:\n",
    "- objective_primary_metric \n",
    "- objective_goal\n",
    "- sampling_algorithm\n",
    "- limits\n",
    "- early_termination_policy\n",
    "- compute\n",
    "\n",
    "Please check section **3. Run a sweep on this command** in [Run hyperparameter sweep on a Command or CommandComponent](../../single-step/lightgbm/iris/lightgbm-iris-sweep.ipynb) for detailed explanation for the above concepts and settings.\n",
    "\n",
    "Noted that the **primary metric** of sweep objective must be **LOGGED** in the definition of `train_model`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "name": "enable-sweep"
   },
   "outputs": [],
   "source": [
    "train_component_func = load_component(source=\"./train.yml\")\n",
    "score_component_func = load_component(source=\"./predict.yml\")\n",
    "\n",
    "# define a pipeline\n",
    "@pipeline()\n",
    "def pipeline_with_hyperparameter_sweep():\n",
    "    \"\"\"Tune hyperparameters using sample components.\"\"\"\n",
    "    train_model = train_component_func(\n",
    "        data=Input(\n",
    "            type=\"uri_file\",\n",
    "            path=\"wasbs://datasets@azuremlexamples.blob.core.windows.net/iris.csv\",\n",
    "        ),\n",
    "        c_value=Uniform(min_value=0.5, max_value=0.9),\n",
    "        kernel=Choice([\"rbf\", \"linear\", \"poly\"]),\n",
    "        coef0=Uniform(min_value=0.1, max_value=1),\n",
    "        degree=3,\n",
    "        gamma=\"scale\",\n",
    "        shrinking=False,\n",
    "        probability=False,\n",
    "        tol=0.001,\n",
    "        cache_size=1024,\n",
    "        verbose=False,\n",
    "        max_iter=-1,\n",
    "        decision_function_shape=\"ovr\",\n",
    "        break_ties=False,\n",
    "        random_state=42,\n",
    "    )\n",
    "    sweep_step = train_model.sweep(\n",
    "        primary_metric=\"training_f1_score\",\n",
    "        goal=\"minimize\",\n",
    "        sampling_algorithm=\"random\",\n",
    "        compute=\"cpu-cluster\",\n",
    "    )\n",
    "    sweep_step.set_limits(max_total_trials=20, max_concurrent_trials=10, timeout=7200)\n",
    "\n",
    "    score_data = score_component_func(\n",
    "        model=sweep_step.outputs.model_output, test_data=sweep_step.outputs.test_data\n",
    "    )\n",
    "\n",
    "\n",
    "pipeline_job = pipeline_with_hyperparameter_sweep()\n",
    "\n",
    "# set pipeline level compute\n",
    "pipeline_job.settings.default_compute = \"cpu-cluster\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.2 Submit pipeline job"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# submit job to workspace\n",
    "pipeline_job = ml_client.jobs.create_or_update(\n",
    "    pipeline_job, experiment_name=\"pipeline_samples\"\n",
    ")\n",
    "pipeline_job"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Wait until the job completes\n",
    "ml_client.jobs.stream(pipeline_job.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Next Steps\n",
    "You can see further examples of running a pipeline job [here](../)"
   ]
  }
 ],
 "metadata": {
  "description": {
   "description": "Use sweep (hyperdrive) in pipeline to train mnist model using tensorflow"
  },
  "interpreter": {
   "hash": "3e9e0e270b75c5e6da2e22113ba4f77b864d68f95da6601809c29e46c73ae6bb"
  },
  "kernelspec": {
   "display_name": "Python 3.10 - SDK V2",
   "language": "python",
   "name": "python310-sdkv2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}