Fixed all issues and increased verbosity

Author: Venkatesan

sagemaker-python-sdk/mxnet_mnist_byom/mxnet_mnist.ipynb

@@ -12,10 +12,13 @@
     "    2. [Data Setup](#Data-setup)\n",
     "3. [Training the network locally](#Training)\n",
     "4. [Set up hosting for the model](#Set-up-hosting-for-the-model)\n",
-    "    1. [Export from mxnet](#Export-the-model-from-mxnet)\n",
+    "    1. [Export from MXNet](#Export-the-model-from-mxnet)\n",
     "    2. [Import model into SageMaker](#Import-model-into-SageMaker)\n",
     "    3. [Create endpoint](#Create-endpoint) \n",
-    "5. [Validate the ebdpoint for use](#Validate-the-endpoint-for-use)"
+    "5. [Validate the endpoint for use](#Validate-the-endpoint-for-use)\n",
+    "\n",
+    "\n",
+    "__Note__: Compare this with the [tensorflow bring your own model example](../tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb)"
    ]
   },
   {
@@ -141,7 +144,7 @@
     "\n",
     "### Export the model from mxnet\n",
     "\n",
-    "In order to set up hosting, we have to import the model from training to hosting. We will begin by exporting the model from mxnet and saving it down. Analogous to the [tensorflow example](../tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb), some structure needs to be followed. The exported model has to be converted into a form that is readable by ``sagemaker.mxnet.model.MXNetModel``. The following code describes exporting the model in a form that does the same:"
+    "In order to set up hosting, we have to import the model from training to hosting. We will begin by exporting the model from MXNet and saving it down. Analogous to the [TensorFlow example](../tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb), some structure needs to be followed. The exported model has to be converted into a form that is readable by ``sagemaker.mxnet.model.MXNetModel``. The following code describes exporting the model in a form that does the same:"
    ]
   },
   {
@@ -276,8 +279,6 @@
    },
    "outputs": [],
    "source": [
-    "import sagemaker\n",
-    "\n",
     "sagemaker.Session().delete_endpoint(predictor.endpoint)"
    ]
   },

sagemaker-python-sdk/tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb

@@ -4,11 +4,38 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Bring your own Model - IRIS classifier example.\n",
+    "# TensorFlow BYOM: Train locally and deploy on SageMaker.\n",
     "\n",
-    "This notebook can be compared to [tensorflow_iris_dnn_classifier_using_estimators.ipynb](https://github.com/awslabs/sagemaker-examples/blob/master/sagemaker-python-sdk/tensorflow_iris_dnn_classifier_using_estimators/tensorflow_iris_dnn_classifier_using_estimators.ipynb). It seeks to solve the same problem, but instead of training by using Amazon SageMaker's distributed, managed training functionality, it relies on the user to train locally or bring a pre-trained model, and then setup a real-time hosted endpoint in SageMaker. To do that, we'll rely on the same set of functions for training. \n",
     "\n",
-    "Consider the following mdoel definition for IRIS classification. This mdoe uses the ``tensorflow.estimator.DNNClassifier`` which is a pre-defined enstimator module for its model definition. "
+    "1. [Introduction](#Introduction)\n",
+    "2. [Prerequisites and Preprocessing](#Prequisites-and-Preprocessing)\n",
+    "    1. [Permissions and environment variables](#Permissions-and-environment-variables)\n",
+    "    2. [Model definitions](#Model-definitions)\n",
+    "    3. [Data Setup](#Data-setup)\n",
+    "3. [Training the network locally](#Training)\n",
+    "4. [Set up hosting for the model](#Set-up-hosting-for-the-model)\n",
+    "    1. [Export from TensorFlow](#Export-the-model-from-tensorflow)\n",
+    "    2. [Import model into SageMaker](#Import-model-into-SageMaker)\n",
+    "    3. [Create endpoint](#Create-endpoint) \n",
+    "5. [Validate the endpoint for use](#Validate-the-endpoint-for-use)\n",
+    "\n",
+    "__Note__: Compare this with the [tensorflow bring your own model example](../tensorflow_iris_byom/tensorflow_BYOM_iris.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction \n",
+    "\n",
+    "This notebook can be compared to [Iris classification example notebook](../tensorflow_iris_dnn_classifier_using_estimators/tensorflow_iris_dnn_classifier_using_estimators.ipynb) in terms of its functionality. We will do the same classification task, but we will train the same network locally in the box from where this notebook is being run. We then setup a real-time hosted endpoint in SageMaker.\n",
+    "\n",
+    "Consider the following model definition for IRIS classification. This mdoe uses the ``tensorflow.estimator.DNNClassifier`` which is a pre-defined enstimator module for its model definition. The model definition is the same as the one used in the [Iris classification example notebook](../tensorflow_iris_dnn_classifier_using_estimators/tensorflow_iris_dnn_classifier_using_estimators.ipynb)\n",
+    "\n",
+    "## Prequisites and Preprocessing\n",
+    "### Permissions and environment variables\n",
+    "\n",
+    "Here we set up the linkage and authentication to AWS services. In this notebook we only need the roles used to give learning and hosting access to your data. The Sagemaker SDK will use S3 defualt buckets when needed. Supply the role in the variable below."
    ]
   },
   {
@@ -19,13 +46,24 @@
    },
    "outputs": [],
    "source": [
-    "role = <<Your_Sagemaker_Role>>"
+    "role = '<your SageMaker execution role here>'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Model Definitions\n",
+    "\n",
+    "We use the [``tensorflow.estimator.DNNClassifier``](https://www.tensorflow.org/api_docs/python/tf/estimator/DNNClassifier) estimator to set up our network. We also need to write some methods for serving inputs during hosting and training. These methods are all found below."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "import os\n",
@@ -81,7 +119,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "classifier = estimator_fn(run_config = None, params = None)"
@@ -91,7 +131,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Download and make the iris dataset from TensorFlow's repository."
+    "### Data setup\n",
+    "\n",
+    "Next, we need to pull the data from tensorflow repository and make them ready for training. The following will code block should do that."
    ]
   },
   {
@@ -127,7 +169,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Create the input streamer object."
+    "Create the data input streamer object."
    ]
   },
   {
@@ -145,7 +187,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Train using TensorFlow's ``tensorflow.Estimator.train`` method. The model is trained locally in the box."
+    "### Training\n",
+    "\n",
+    "It is time to train the network. Since we are training the network locally, we can make use of TensorFlow's ``tensorflow.Estimator.train`` method. The model is trained locally in the box."
    ]
   },
   {
@@ -163,6 +207,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "## Set up hosting for the model\n",
+    "\n",
+    "### Export the model from mxnet\n",
+    "\n",
+    "In order to set up hosting, we have to import the model from training to hosting. We will begin by exporting the model from TensorFlow and saving it down. Analogous to the [MXNet example](../mxnet_mnist_byom/mxnet_mnist.ipynb), some structure needs to be followed. The exported model has to be converted into a form that is readable by ``sagemaker.mxnet.model.MXNetModel``. The following code describes exporting the model in a form that does the same:\n",
+    "\n",
     "There is a small difference between a SageMaker model and a TensorFlow model. The conversion is easy and fairly trivial. Simply move the tensorflow exported model into a directory ``export\\Servo\\`` and tar the entire directory. SageMaker will recognize this as a loadable TensorFlow model."
    ]
   },
@@ -186,7 +236,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Open a new sagemaker session and upload the model into the default S3 bucket under the directory ``model``."
+    "### Import model into SageMaker\n",
+    "\n",
+    "Open a new sagemaker session and upload the model on to the default S3 bucket. We can use the ``sagemaker.Session.upload_data`` method to do this. We need the location of where we exported the model from MXNet and where in our default bucket we want to store the model(``/model``). The default S3 bucket can be found using the ``sagemaker.Session.default_bucket`` method."
    ]
   },
   {
@@ -207,7 +259,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Use the ``sagemaker.tensorflow.model.TensorflowModel`` class directly to setup a trained model in a sagemaker session."
+    "Use the ``sagemaker.mxnet.model.TensorFlowModel`` to import the model into SageMaker that can be deployed. We need the location of the S3 bucket where we have the model, the role for authentication and the entry_point where the model defintion is stored (``iris_dnn_classifier.py``). The import call is the following:"
    ]
   },
   {
@@ -228,13 +280,17 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Deploy the newly created SageMaker model to an endpoint."
+    "### Create endpoint\n",
+    "\n",
+    "Now the model is ready to be deployed at a SageMaker endpoint. We can use the ``sagemaker.mxnet.model.TensorFlowModel.deploy`` method to do this. Unless you have created or prefer other instances, we recommend using 1 ``'ml.c4.xlarge'`` instance for this training. These are supplied as arguments. "
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "collapsed": true
+   },
    "outputs": [],
    "source": [
     "%%time\n",
@@ -246,15 +302,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Run a sample prediction on a sample to ensure that it works. Expect result ``1`` for this particular sample."
+    "### Validate the endpoint for use\n",
+    "\n",
+    "We can now use this endpoint to classify. Run a sample prediction on a sample to ensure that it works. Expect result ``1`` for this particular sample."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "predict_samples = {}\n",
@@ -266,7 +322,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Delete all temporary directories so that we are not affecting the next run."
+    "Delete all temporary directories so that we are not affecting the next run. Also, optionally delete the end points."
    ]
   },
   {
@@ -279,7 +335,9 @@
    "source": [
     "os.remove('model.tar.gz')\n",
     "import shutil\n",
-    "shutil.rmtree('export')"
+    "shutil.rmtree('export')\n",
+    "\n",
+    "sagemaker.Session().delete_endpoint(predictor.endpoint)"
    ]
   }
  ],