aws_sagemaker_studio/frameworks/keras_pipe_mode_horovod/keras_pipe_mode_horovod_cifar10.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Train and Host a Keras Model with Pipe Mode and Horovod on Amazon SageMaker\n",
    "\n",
    "Amazon SageMaker is a fully-managed service that provides developers and data scientists with the ability to build, train, and deploy machine learning (ML) models quickly. Amazon SageMaker removes the heavy lifting from each step of the machine learning process to make it easier to develop high-quality models. The SageMaker Python SDK makes it easy to train and deploy models in Amazon SageMaker with several different machine learning and deep learning frameworks, including TensorFlow and Keras.\n",
    "\n",
    "In this notebook, we train and host a [Keras Sequential model](https://keras.io/getting-started/sequential-model-guide) on SageMaker. The model used for this notebook is a simple deep convolutional neural network (CNN) that was extracted from [the Keras examples](https://github.com/keras-team/keras/blob/master/examples/cifar10_cnn.py).\n",
    "\n",
    "For training our model, we also demonstrate distributed training with [Horovod](https://horovod.readthedocs.io) and Pipe Mode. Amazon SageMaker's Pipe Mode streams your dataset directly to your training instances instead of being downloaded first, which translates to training jobs that start sooner, finish quicker, and need less disk space.    \n",
    "<br>\n",
    "<br>\n",
    "<b> Instance Type and Pricing:  </b>\n",
    "\n",
    "This notebook was trained using the <b>Python 3 (TensorFlow CPU Optimized)</b> kernel using the <b>ml.p3.2xlarge</b> compute instance type in the <b>us-west-2 region</b>. Training time is approximately 70 minutes with the aforementioned hardware specifications.\n",
    "\n",
    "Price per hour depends on your region and instance type. You can reference prices on the [SageMaker pricing page](https://aws.amazon.com/sagemaker/pricing/).  \n",
    "\n",
    "---\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "First, we define a few variables that are be needed later in the example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sagemaker\n",
    "from sagemaker import get_execution_role\n",
    "\n",
    "sagemaker_session = sagemaker.Session()\n",
    "\n",
    "role = get_execution_role()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We also install a couple libraries we need for visualizing our model's prediction results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install matplotlib seaborn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The CIFAR-10 dataset\n",
    "\n",
    "The [CIFAR-10 dataset](https://www.cs.toronto.edu/~kriz/cifar.html) is one of the most popular machine learning datasets. It consists of 60,000 32x32 images belonging to 10 different classes (6,000 images per class). Here are the classes in the dataset, as well as 10 random images from each:\n",
    "\n",
    "![cifar10](https://maet3608.github.io/nuts-ml/_images/cifar10.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prepare the dataset for training\n",
    "\n",
    "To use the CIFAR-10 dataset, we first download it and convert it to TFRecords. This step takes around 5 minutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python generate_cifar10_tfrecords.py --data-dir ./data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we upload the data to Amazon S3:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sagemaker.s3 import S3Uploader\n",
    "\n",
    "bucket = sagemaker_session.default_bucket()\n",
    "dataset_uri = S3Uploader.upload('data', 's3://{}/tf-cifar10-example/data'.format(bucket))\n",
    "\n",
    "display(dataset_uri)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Train the model\n",
    "\n",
    "In this tutorial, we train a deep CNN to learn a classification task with the CIFAR-10 dataset. We compare three different training jobs: a baseline training job, training with Pipe Mode, and distributed training with Horovod."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Configure metrics\n",
    "\n",
    "In addition to running the training job, Amazon SageMaker can retrieve training metrics directly from the logs and send them to CloudWatch metrics. Here, we define metrics we would like to observe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "metric_definitions = [\n",
    "    {'Name': 'train:loss', 'Regex': '.*loss: ([0-9\\\\.]+) - accuracy: [0-9\\\\.]+.*'},\n",
    "    {'Name': 'train:accuracy', 'Regex': '.*loss: [0-9\\\\.]+ - accuracy: ([0-9\\\\.]+).*'},\n",
    "    {'Name': 'validation:accuracy', 'Regex': '.*step - loss: [0-9\\\\.]+ - accuracy: [0-9\\\\.]+ - val_loss: [0-9\\\\.]+ - val_accuracy: ([0-9\\\\.]+).*'},\n",
    "    {'Name': 'validation:loss', 'Regex': '.*step - loss: [0-9\\\\.]+ - accuracy: [0-9\\\\.]+ - val_loss: ([0-9\\\\.]+) - val_accuracy: [0-9\\\\.]+.*'},\n",
    "    {'Name': 'sec/steps', 'Regex': '.* - \\d+s (\\d+)[mu]s/step - loss: [0-9\\\\.]+ - accuracy: [0-9\\\\.]+ - val_loss: [0-9\\\\.]+ - val_accuracy: [0-9\\\\.]+'}\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run a baseline training job on SageMaker\n",
    "\n",
    "The SageMaker Python SDK's `sagemaker.tensorflow.TensorFlow` estimator class makes it easy for us to interact with SageMaker. Here, we create one to configure a training job. Some parameters worth noting:\n",
    "\n",
    "* `entry_point`: our training script (adapted from [this Keras example](https://github.com/keras-team/keras/blob/master/examples/cifar10_cnn.py)).\n",
    "* `metric_definitions`: the metrics (defined above) that we want sent to CloudWatch.\n",
    "* `train_instance_count`: the number of training instances. Here, we set it to 1 for our baseline training job.\n",
    "\n",
    "For more details about the TensorFlow estimator class, see the [API documentation](https://sagemaker.readthedocs.io/en/stable/sagemaker.tensorflow.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sagemaker.tensorflow import TensorFlow\n",
    "\n",
    "hyperparameters = {'epochs': 10, 'batch-size': 256}\n",
    "tags = [{'Key': 'Project', 'Value': 'cifar10'}]\n",
    "\n",
    "estimator = TensorFlow(entry_point='keras_cifar10.py',\n",
    "                       source_dir='source',\n",
    "                       metric_definitions=metric_definitions,\n",
    "                       hyperparameters=hyperparameters,\n",
    "                       role=role,\n",
    "                       framework_version='1.15.2',\n",
    "                       py_version='py3',\n",
    "                       train_instance_count=1,\n",
    "                       train_instance_type='ml.p3.2xlarge',\n",
    "                       base_job_name='cifar10-tf',\n",
    "                       tags=tags)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once we have our estimator, we call `fit()` to start the SageMaker training job and pass the inputs that we uploaded to Amazon S3 earlier. We pass the inputs as a dictionary to define different data channels for training."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "inputs = {\n",
    "    'train': '{}/train'.format(dataset_uri),\n",
    "    'validation': '{}/validation'.format(dataset_uri),\n",
    "    'eval': '{}/eval'.format(dataset_uri),\n",
    "}\n",
    "\n",
    "estimator.fit(inputs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### View the job training metrics\n",
    "\n",
    "We can now view the metrics from the training job directly in the SageMaker console.  \n",
    "\n",
    "Log into the [SageMaker console](https://console.aws.amazon.com/sagemaker/home), choose the latest training job, and scroll down to the monitor section. Alternatively, the code below uses the region and training job name to generate a URL to CloudWatch metrics.\n",
    "\n",
    "Using CloudWatch metrics, you can change the period and configure the statistics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from urllib import parse\n",
    "\n",
    "from IPython.core.display import Markdown\n",
    "\n",
    "region = sagemaker_session.boto_region_name\n",
    "cw_url = parse.urlunparse((\n",
    "    'https',\n",
    "    '{}.console.aws.amazon.com'.format(region),\n",
    "    '/cloudwatch/home',\n",
    "    '',\n",
    "    'region={}'.format(region),\n",
    "    'metricsV2:namespace=/aws/sagemaker/TrainingJobs;dimensions=TrainingJobName;search={}'.format(estimator.latest_training_job.name),\n",
    "))\n",
    "\n",
    "display(Markdown('CloudWatch metrics: [link]({}). After you choose a metric, '\n",
    "                 'change the period to 1 Minute (Graphed Metrics -> Period).'.format(cw_url)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Train on SageMaker with Pipe Mode\n",
    "\n",
    "Here we train our model using Pipe Mode. With Pipe Mode, SageMaker uses [Linux named pipes](https://www.linuxjournal.com/article/2156) to stream the training data directly from S3 instead of downloading the data first.\n",
    "\n",
    "In our script, we enable Pipe Mode using the following code:\n",
    "\n",
    "```python\n",
    "from sagemaker_tensorflow import PipeModeDataset\n",
    "\n",
    "dataset = PipeModeDataset(channel=channel_name, record_format='TFRecord')\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we create our estimator, the only difference from before is that we also specify `input_mode='Pipe'`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipe_mode_estimator = TensorFlow(entry_point='keras_cifar10.py',\n",
    "                                 source_dir='source',\n",
    "                                 metric_definitions=metric_definitions,\n",
    "                                 hyperparameters=hyperparameters,\n",
    "                                 role=role,\n",
    "                                 framework_version='1.15.2',\n",
    "                                 py_version='py3',\n",
    "                                 train_instance_count=1,\n",
    "                                 train_instance_type='ml.p3.2xlarge',\n",
    "                                 input_mode='Pipe',\n",
    "                                 base_job_name='cifar10-tf-pipe',\n",
    "                                 tags=tags)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipe_mode_estimator.fit(inputs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Distributed training with Horovod\n",
    "\n",
    "[Horovod](https://horovod.readthedocs.io) is a distributed training framework based on MPI. To use Horovod, we make the following changes to our training script:\n",
    "\n",
    "1. Enable Horovod:\n",
    "\n",
    "```python\n",
    "import horovod.keras as hvd\n",
    "\n",
    "hvd.init()\n",
    "config = tf.ConfigProto()\n",
    "config.gpu_options.allow_growth = True\n",
    "config.gpu_options.visible_device_list = str(hvd.local_rank())\n",
    "K.set_session(tf.Session(config=config))\n",
    "```\n",
    "\n",
    "2. Add these callbacks:\n",
    "\n",
    "```python\n",
    "hvd.callbacks.BroadcastGlobalVariablesCallback(0)\n",
    "hvd.callbacks.MetricAverageCallback()\n",
    "```\n",
    "\n",
    "3. Configure the optimizer:\n",
    "\n",
    "```python\n",
    "opt = Adam(lr=learning_rate * size, decay=weight_decay)\n",
    "opt = hvd.DistributedOptimizer(opt)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To configure the training job, we specify the following for the distribution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "distribution = {\n",
    "    'mpi': {\n",
    "        'enabled': True,\n",
    "        'processes_per_host': 1,  # Number of Horovod processes per host\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is then passed to our estimator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dist_estimator = TensorFlow(entry_point='keras_cifar10.py',\n",
    "                            source_dir='source',\n",
    "                            metric_definitions=metric_definitions,\n",
    "                            hyperparameters=hyperparameters,\n",
    "                            distributions=distribution,\n",
    "                            role=role,\n",
    "                            framework_version='1.15.2',\n",
    "                            py_version='py3',\n",
    "                            train_instance_count=2,\n",
    "                            train_instance_type='ml.p3.2xlarge',\n",
    "                            base_job_name='cifar10-tf-dist',\n",
    "                            tags=tags)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dist_estimator.fit(inputs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deploy the trained model\n",
    "\n",
    "After we train our model, we can deploy it to a SageMaker Endpoint, which serves prediction requests in real-time. To do so, we simply call `deploy()` on our estimator, passing in the desired number of instances and instance type for the endpoint.\n",
    "\n",
    "Because we're using TensorFlow Serving for deployment, our training script saves the model in TensorFlow's SavedModel format.  \n",
    "\n",
    "We don't need accelerated computing power for inference, so let's switch over to a <b>ml.m4.xlarge</b> instance type. \n",
    "\n",
    "For more information about deploying Keras and TensorFlow models in SageMaker, see [this blog post](https://aws.amazon.com/blogs/machine-learning/deploy-trained-keras-or-tensorflow-models-using-amazon-sagemaker)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "predictor = estimator.deploy(initial_instance_count=1, instance_type='ml.m4.xlarge')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Invoke the endpoint\n",
    "\n",
    "To verify the that the endpoint is in service, we generate some random data in the correct shape and get a prediction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "data = np.random.randn(1, 32, 32, 3)\n",
    "print('Predicted class: {}'.format(np.argmax(predictor.predict(data)['predictions'])))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's use the test dataset for predictions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from keras.datasets import cifar10\n",
    "\n",
    "(x_train, y_train), (x_test, y_test) = cifar10.load_data()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the data loaded, we can use it for predictions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from keras.preprocessing.image import ImageDataGenerator\n",
    "\n",
    "def predict(data):\n",
    "    predictions = predictor.predict(data)['predictions']\n",
    "    return predictions\n",
    "\n",
    "\n",
    "predicted = []\n",
    "actual = []\n",
    "batches = 0\n",
    "batch_size = 128\n",
    "\n",
    "datagen = ImageDataGenerator()\n",
    "for data in datagen.flow(x_test, y_test, batch_size=batch_size):\n",
    "    for i, prediction in enumerate(predict(data[0])):\n",
    "        predicted.append(np.argmax(prediction))\n",
    "        actual.append(data[1][i][0])\n",
    "\n",
    "    batches += 1\n",
    "    if batches >= len(x_test) / batch_size:\n",
    "        break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the predictions, we calculate our model accuracy and create a confusion matrix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sklearn.metrics import accuracy_score\n",
    "\n",
    "accuracy = accuracy_score(y_pred=predicted, y_true=actual)\n",
    "display('Average accuracy: {}%'.format(round(accuracy*100, 2)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd\n",
    "import seaborn as sn\n",
    "from sklearn.metrics import confusion_matrix\n",
    "\n",
    "cm = confusion_matrix(y_pred=predicted, y_true=actual)\n",
    "cm = cm.astype('float') / cm.sum(axis=1)[:, np.newaxis]\n",
    "sn.set(rc={'figure.figsize':(11.7,8.27)})\n",
    "sn.set(font_scale=1.4)  # for label size\n",
    "sn.heatmap(cm, annot=True, annot_kws={\"size\": 10})  # font size"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Aided by the colors of the heatmap, we can use this confusion matrix to understand how well the model performed for each label."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cleanup\n",
    "\n",
    "To avoid incurring extra charges to your AWS account, let's delete the endpoint we created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predictor.delete_endpoint()"
   ]
  }
 ],
 "metadata": {
  "instance_type": "ml.t3.medium",
  "kernelspec": {
   "display_name": "Python 3 (TensorFlow CPU Optimized)",
   "language": "python",
   "name": "python3__SAGEMAKER_INTERNAL__arn:aws:sagemaker:us-west-2:236514542706:image/tensorflow-1.15-cpu-py36"
  },
  "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.6.3"
  },
  "notice": "Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the \"License\"). You may not use this file except in compliance with the License. A copy of the License is located at http://aws.amazon.com/apache2.0/ or in the \"license\" file accompanying this file. This file is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.",
  "pycharm": {
   "stem_cell": {
    "cell_type": "raw",
    "metadata": {
     "collapsed": false
    },
    "source": []
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}