Update copyright and add more links to docs

Author: Dan Choi

advanced_functionality/tensorflow_bring_your_own/container/Dockerfile

@@ -1,14 +1,30 @@
+# Copyright 2017-2018 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.
+
+# For more information on creating a Dockerfile
 # https://docs.docker.com/compose/gettingstarted/#step-2-create-a-dockerfile
 FROM tensorflow/tensorflow:1.8.0-py3
 
 RUN apt-get update && apt-get install -y --no-install-recommends nginx curl
 
 # Download tensorflow serving
+# https://www.tensorflow.org/serving/setup#installing_the_modelserver
 RUN echo "deb [arch=amd64] http://storage.googleapis.com/tensorflow-serving-apt stable tensorflow-model-server tensorflow-model-server-universal" | tee /etc/apt/sources.list.d/tensorflow-serving.list
 RUN curl https://storage.googleapis.com/tensorflow-serving-apt/tensorflow-serving.release.pub.gpg | apt-key add -
 RUN apt-get update && apt-get install tensorflow-model-server
 
 ENV PATH="/opt/ml/code:${PATH}"
 
+# /opt/ml and all subdirectories are utilized by SageMaker, we use the /code subdirectory to store our user code.
 COPY /cifar10 /opt/ml/code
-WORKDIR /opt/ml/code
+WORKDIR /opt/ml/code

advanced_functionality/tensorflow_bring_your_own/container/cifar10/cifar10.py

@@ -16,12 +16,12 @@
 
 import argparse
 import functools
-
 import os
 
-import resnet_model
 import tensorflow as tf
 
+import resnet_model
+
 INPUT_TENSOR_NAME = "inputs"
 SIGNATURE_NAME = "serving_default"
 
@@ -48,7 +48,10 @@
 
 
 def model_fn(features, labels, mode):
-    """Model function for CIFAR-10."""
+    """
+    Model function for CIFAR-10.
+    For more information: https://www.tensorflow.org/guide/custom_estimators#write_a_model_function
+    """
     inputs = features[INPUT_TENSOR_NAME]
     tf.summary.image('images', inputs, max_outputs=6)
 
@@ -113,6 +116,10 @@ def model_fn(features, labels, mode):
 
 
 def serving_input_fn():
+    """
+    Serving input function for CIFAR-10. Specifies the input format the caller of predict() will have to provide.
+    For more information: https://www.tensorflow.org/guide/saved_model#build_and_load_a_savedmodel
+    """
     inputs = {INPUT_TENSOR_NAME: tf.placeholder(tf.float32, [None, 32, 32, 3])}
     return tf.estimator.export.ServingInputReceiver(inputs, inputs)
 
@@ -187,23 +194,30 @@ def main(model_dir, data_dir, train_steps):
 
 if __name__ == '__main__':
     args_parser = argparse.ArgumentParser()
+    # For more information:
+    # https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo.html
     args_parser.add_argument(
         '--data-dir',
         default='/opt/ml/input/data/training',
         type=str,
-        # required=True,
-        help='The directory where the CIFAR-10 input data is stored.')
+        help='The directory where the CIFAR-10 input data is stored. Default: /opt/ml/input/data/training. This '
+             'directory corresponds to the SageMaker channel named \'training\', which was specified when creating '
+             'our training job on SageMaker')
+
+    # For more information:
+    # https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-inference-code.html
     args_parser.add_argument(
         '--model-dir',
         default='/opt/ml/model',
         type=str,
-        # required=True,
-        help='The directory where the model will be stored.')
+        help='The directory where the model will be stored. Default: /opt/ml/model. This directory should contain all '
+             'final model artifacts as Amazon SageMaker copies all data within this directory as a single object in '
+             'compressed tar format.')
+
     args_parser.add_argument(
         '--train-steps',
         type=int,
         default=100,
-        # required=True,
         help='The number of steps to use for training.')
     args = args_parser.parse_args()
     main(**vars(args))

advanced_functionality/tensorflow_bring_your_own/container/cifar10/nginx.conf

@@ -8,7 +8,8 @@ events {
 http {
   server {
     # configures the server to listen to the port 8080
-    # https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-inference-code.html#your-algorithms-inference-code-container-response
+    # Amazon SageMaker sends inference requests to port 8080.
+    # For more information: https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-inference-code.html#your-algorithms-inference-code-container-response
     listen 8080 deferred;
 
     # redirects requests from SageMaker to TF Serving

advanced_functionality/tensorflow_bring_your_own/container/cifar10/resnet_model.py

@@ -1,17 +1,19 @@
-# Copyright 2017 The TensorFlow Authors. All Rights Reserved.
+# Copyright 2017-2018 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.
-# You may obtain a copy of the License at
+# 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://www.apache.org/licenses/LICENSE-2.0
+#     http://aws.amazon.com/apache2.0/
 #
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License 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.
-# ==============================================================================
+# 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.
+
+# A sample training component that trains a simple scikit-learn decision tree model.
+# This implementation works in File mode and makes no assumptions about the input file names.
+# Input is specified as CSV with a data point in each row and the labels in the first column.
 """Contains definitions for the preactivation form of Residual Networks.
 
 Residual networks (ResNets) were originally proposed in:
@@ -30,6 +32,7 @@
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
+
 import tensorflow as tf
 
 _BATCH_NORM_DECAY = 0.997

advanced_functionality/tensorflow_bring_your_own/container/cifar10/serve

@@ -1,9 +1,19 @@
 #!/usr/bin/env python
 
-# This file implements the hosting solution, which just starts TensorFlow Model Serving.
-
-from __future__ import print_function
+# Copyright 2017-2018 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.
 
+# This file implements the hosting solution, which just starts TensorFlow Model Serving.
 import subprocess
 
 
@@ -14,7 +24,13 @@ def start_server():
     subprocess.check_call(['ln', '-sf', '/dev/stdout', '/var/log/nginx/access.log'])
     subprocess.check_call(['ln', '-sf', '/dev/stderr', '/var/log/nginx/error.log'])
 
+    # start nginx server
     nginx = subprocess.Popen(['nginx', '-c', '/opt/ml/code/nginx.conf'])
+
+    # start TensorFlow Serving
+    # https://www.tensorflow.org/serving/api_rest#start_modelserver_with_the_rest_api_endpoint
+    # SageMaker copies our model artifact from our Training Job into the /opt/ml/model.
+    # https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-inference-code.html#your-algorithms-inference-code-load-artifacts
     tf_model_server = subprocess.call(['tensorflow_model_server',
                                        '--rest_api_port=8501',
                                        '--model_name=cifar10_model',

advanced_functionality/tensorflow_bring_your_own/container/cifar10/train

@@ -1,5 +1,18 @@
 #!/usr/bin/env python
 
+# Copyright 2017-2018 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.
+
 # A sample training component that trains a simple scikit-learn decision tree model.
 # This implementation works in File mode and makes no assumptions about the input file names.
 # Input is specified as CSV with a data point in each row and the labels in the first column.
@@ -31,6 +44,7 @@ default_params = ['--model-dir', str(model_path)]
 
 # Execute your training algorithm.
 def _run(cmd):
+    """Invokes your training algorithm."""
     process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=os.environ)
     stdout, stderr = process.communicate()
 
@@ -41,6 +55,10 @@ def _run(cmd):
 
 
 def _hyperparameters_to_cmd_args(hyperparameters):
+    """
+    Converts our hyperparameters, in json format, into key-value pair suitable for passing to our training
+    algorithm.
+    """
     cmd_args_list = []
 
     for key, value in hyperparameters.items():
@@ -52,6 +70,9 @@ def _hyperparameters_to_cmd_args(hyperparameters):
 
 if __name__ == '__main__':
     try:
+        # Amazon SageMaker makes our specified hyperparameters available within the
+        # /opt/ml/input/config/hyperparameters.json.
+        # https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo.html#your-algorithms-training-algo-running-container
         with open(param_path, 'r') as tc:
             training_params = json.load(tc)
 

advanced_functionality/tensorflow_bring_your_own/utils/generate_cifar10_tfrecords.py

@@ -18,18 +18,16 @@
 python version of the CIFAR-10 dataset downloaded from
 https://www.cs.toronto.edu/~kriz/cifar.html.
 """
-
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 
 import argparse
 import os
+import shutil
 import sys
-
 import tarfile
 
-import shutil
 from six.moves import cPickle as pickle
 from six.moves import xrange  # pylint: disable=redefined-builtin
 import tensorflow as tf