revise mxnet_mnist example (#58)

Author: jesterhazy

sagemaker-python-sdk/mxnet_mnist/mxnet_mnist.ipynb

@@ -4,43 +4,81 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Mxnet MNIST Single Machine SageMaker Training Example\n",
+    "# Training and hosting SageMaker Models using the Apache MXNet Module API\n",
     "\n",
-    "MNIST is a widely used dataset for handwritten digit classification. It consists of 70,000 labeled 28x28 pixel grayscale images of hand-written digits. The dataset is split into 60,000 training images and 10,000 test images. There are 10 classes (one for each of the 10 digits). The task at hand is to train a model using the 60,000 training images and subsequently test its classification accuracy on the 10,000 test images.\n",
-    "\n"
+    "The **SageMaker Python SDK** makes it easy to train and deploy MXNet models. In this example, we train a simple neural network using the Apache MXNet [Module API](https://mxnet.incubator.apache.org/api/python/module.html) and the MNIST dataset. The MNIST dataset is widely used for handwritten digit classification, and consists of 70,000 labeled 28x28 pixel grayscale images of hand-written digits. The dataset is split into 60,000 training images and 10,000 test images. There are 10 classes (one for each of the 10 digits). The task at hand is to train a model using the 60,000 training images and subsequently test its classification accuracy on the 10,000 test images.\n",
+    "\n",
+    "### Setup\n",
+    "\n",
+    "First we need to define a few variables that will be needed later in the example."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
+    "collapsed": true,
     "isConfigCell": true
    },
    "outputs": [],
    "source": [
     "from sagemaker import get_execution_role\n",
     "\n",
     "#Bucket location to save your custom code in tar.gz format.\n",
-    "custom_code_upload_location = 's3://<bucket-name>/customcode/mxnet_mnist'\n",
+    "custom_code_upload_location = 's3://<bucket-name>/customcode/tensorflow_iris'\n",
+    "\n",
     "#Bucket location where results of model training are saved.\n",
     "model_artifacts_location = 's3://<bucket-name>/artifacts'\n",
     "\n",
+    "#IAM execution role that gives SageMaker access to resources in your AWS account.\n",
+    "#We can use the SageMaker Python SDK to get the role from our notebook environment. \n",
     "role = get_execution_role()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The ```MXNet``` class allows us to run single machine, multi-machine, and GPU mxnet training on SageMaker. Below we create an MXNet object to run our mnist training, passing in an IAMRole name to allow SageMaker to access our AWS resources. We run SageMaker mxnet training on a single ```m4.xlarge```.\n",
+    "### The training script\n",
     "\n",
-    "Please see the ```mnist.py``` script to learn more about how training is performed. The script is an adaptation of the mxnet MNIST tutorial, found here: https://mxnet.incubator.apache.org/tutorials/python/mnist.html"
+    "The ``mnist.py`` script provides all the code we need for training and hosting a SageMaker model. The script we will use is adaptated from Apache MXNet [MNIST tutorial (https://mxnet.incubator.apache.org/tutorials/python/mnist.html)."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "!cat mnist.py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### SageMaker's MXNet estimator class"
+   ]
+  },
+  {
+   "cell_type": "markdown",
    "metadata": {},
+   "source": [
+    "The SageMaker ```MXNet``` estimator allows us to run single machine or distributed training in SageMaker, using CPU or GPU-based instances.\n",
+    "\n",
+    "When we create the estimator, we pass in the filename of our training script, the name of our IAM execution role, and the S3 locations we defined in the setup section. We also provide the a few other parameters. ``train_instance_count`` and ``train_instance_type`` determine the number and type of SageMaker instances that will be used for the training job. The ``hyperparameters`` parameter is a ``dict`` of values that will be passed to your training script -- you can see how to access these values in the ``mnist.py`` script above.\n",
+    "\n",
+    "For this example, we will choose one ``ml.m4.xlarge`` instance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "from sagemaker.mxnet import MXNet\n",
@@ -51,24 +89,30 @@
     "                        code_location=custom_code_upload_location,\n",
     "                        train_instance_count=1, \n",
     "                        train_instance_type='ml.m4.xlarge',\n",
-    "                        hyperparameters={'learning_rate': 0.11})"
+    "                        hyperparameters={'learning_rate': 0.1})"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "- TODO: Make the ECR images this is using public\n",
-    "\n",
-    "After we've constructed our MXNet object, we can fit it using data stored in S3. Below we run SageMaker training on two input channels: train and test.\n",
+    "### Running the Training Job"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "After we've constructed our MXNet object, we can fit it using data stored in S3. Below we run SageMaker training on two input channels: **train** and **test**.\n",
     "\n",
-    "During training, SageMaker makes this data stored in S3 available in the local filesystem where the mnist script is running. The ```mnist.py``` script simply loads the train and test data from disk.\n"
+    "During training, SageMaker makes this data stored in S3 available in the local filesystem where the mnist script is running. The ```mnist.py``` script simply loads the train and test data from disk."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
+    "collapsed": true,
     "scrolled": true
    },
    "outputs": [],
@@ -87,15 +131,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "After training, we use the MXNet object to build and deploy an MXNetPredictor object. This creates an sagemaker-hosted prediction service that we can use to perform inference. \n",
+    "### Creating an inference Endpoint\n",
+    "\n",
+    "After training, we use the ``MXNet estimator`` object to build and deploy an ``MXNetPredictor``. This creates a Sagemaker **Endpoint** -- a hosted prediction service that we can use to perform inference. \n",
     "\n",
-    "This allows us to perform inference on json encoded multi-dimensional arrays. "
+    "The arguments to the ``deploy`` function allow us to set the number and type of instances that will be used for the Endpoint. These do not need to be the same as the values we used for the training job. For example, you can train a model on a set of GPU-based instances, and then deploy the Endpoint to a fleet of CPU-based instances. Here we will deploy the model to a single ``ml.c4.xlarge`` instance."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "%%time\n",
@@ -108,23 +156,41 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can now use this predictor to classify hand-written digits. Drawing into the image box loads the pixel data into a 'data' variable in this notebook, which we can then pass to the mxnet predictor. "
+    "The request handling behavior of the Endpoint is determined by the ``mnist.py`` script. In this case, the script doesn't include any request handling functions, so the Endpoint will use the default handlers provided by SageMaker. These default handlers allow us to perform inference on input data encoded as a multi-dimensional JSON array.\n",
+    "\n",
+    "### Making an inference request\n",
+    "\n",
+    "Now that our Endpoint is deployed and we have a ``predictor`` object, we can use it to classify handwritten digits.\n",
+    "\n",
+    "To see inference in action, draw a digit in the image box below. The pixel data from your drawing will be loaded into a ``data`` variable in this notebook. \n",
+    "\n",
+    "*Note: after drawing the image, you'll need to move to the next notebook cell.*"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "from IPython.display import HTML\n",
     "HTML(open(\"input.html\").read())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can use the ``predictor`` object to classify the handwritten digit:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
+    "collapsed": true,
     "scrolled": true
    },
    "outputs": [],
@@ -147,22 +213,28 @@
     "collapsed": true
    },
    "source": [
-    "# (Optional) Delete the Endpoint"
+    "# (Optional) Delete the Endpoint\n",
+    "\n",
+    "After you have finished with this example, remember to delete the prediction endpoint to release the instance(s) associated with it."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
-    "print(predictor.endpoint)"
+    "print(\"Endpoint name: \" + predictor.endpoint)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "import sagemaker\n",
@@ -173,7 +245,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": []
   }