documentation: documentation for heterogeneous cluster

Author: mchoi8739

doc/api/utility/instance_group.rst

@@ -0,0 +1,8 @@
+Instance Group
+--------------
+
+.. automodule:: sagemaker.instance_group
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :private-members:

src/sagemaker/estimator.py

@@ -160,7 +160,7 @@ def __init__(
             instance_count (int): Number of Amazon EC2 instances to use
                 for training. Required if instance_groups is not set.
             instance_type (str): Type of EC2 instance to use for training,
-                for example, 'ml.c4.xlarge'. Required if instance_groups is
+                for example, ``'ml.c4.xlarge'``. Required if instance_groups is
                 not set.
             volume_size (int): Size in GB of the EBS volume to use for
                 storing input data during training (default: 30). Must be large
@@ -235,7 +235,6 @@ def __init__(
             use_spot_instances (bool): Specifies whether to use SageMaker
                 Managed Spot instances for training. If enabled then the
                 ``max_wait`` arg should also be set.
-
                 More information:
                 https://docs.aws.amazon.com/sagemaker/latest/dg/model-managed-spot-training.html
                 (default: ``False``).
@@ -313,40 +312,38 @@ def __init__(
                 when training on Amazon SageMaker. If 'git_config' is provided,
                 'source_dir' should be a relative location to a directory in the Git
                 repo.
+                With the following GitHub repo directory structure:
 
-                .. admonition:: Example
-
-                    With the following GitHub repo directory structure:
+                .. code::
 
-                    >>> |----- README.md
-                    >>> |----- src
-                    >>>         |----- train.py
-                    >>>         |----- test.py
+                    |----- README.md
+                    |----- src
+                             |----- train.py
+                             |----- test.py
 
-                    if you need 'train.py' as the entry point and 'test.py' as
-                    the training source code, you can assign
-                    entry_point='train.py' and source_dir='src'.
+                if you need 'train.py' as the entry point and 'test.py' as
+                the training source code, you can assign
+                entry_point='train.py' and source_dir='src'.
             git_config (dict[str, str]): Git configurations used for cloning
                 files, including ``repo``, ``branch``, ``commit``,
                 ``2FA_enabled``, ``username``, ``password``, and ``token``. The
                 ``repo`` field is required. All other fields are optional.
                 ``repo`` specifies the Git repository where your training script
                 is stored. If you don't provide ``branch``, the default value
                 'master' is used. If you don't provide ``commit``, the latest
-                commit in the specified branch is used.
+                commit in the specified branch is used. For example, the following config:
 
-                .. admonition:: Example
-
-                    The following config:
-
-                    >>> git_config = {'repo': 'https://github.com/aws/sagemaker-python-sdk.git',
-                    >>>               'branch': 'test-branch-git-config',
-                    >>>               'commit': '329bfcf884482002c05ff7f44f62599ebc9f445a'}
+                .. code:: python
 
-                    results in cloning the repo specified in 'repo', then
-                    checking out the 'master' branch, and checking out the specified
-                    commit.
+                    git_config = {
+                        'repo': 'https://github.com/aws/sagemaker-python-sdk.git',
+                        'branch': 'test-branch-git-config',
+                        'commit': '329bfcf884482002c05ff7f44f62599ebc9f445a'
+                    }
 
+                results in cloning the repo specified in 'repo', then
+                checking out the 'master' branch, and checking out the specified
+                commit.
                 ``2FA_enabled``, ``username``, ``password``, and ``token`` are
                 used for authentication. For GitHub (or other Git) accounts, set
                 ``2FA_enabled`` to 'True' if two-factor authentication is
@@ -427,10 +424,25 @@ def __init__(
                     >>>     |------ virtual-env
 
                 This is not supported with "local code" in Local Mode.
-            instance_groups (list[InstanceGroup]): Optional. List of InstanceGroup
-                for specifying different instance groups for heterogeneous cluster.
-                For example: [sagemaker.InstanceGroup('worker','ml.p3dn.24xlarge',64),
-                sagemaker.InstanceGroup('server','ml.c5n.18xlarge',64)]
+            instance_groups (list[:class:`sagemaker.instance_group.InstanceGroup`]):
+                Optional. A list of ``InstanceGroup`` objects
+                for launching a training job with a heterogeneous cluster.
+                For example:
+
+                .. code:: python
+
+                    instance_groups=[
+                        sagemaker.InstanceGroup(
+                            'instance_group_name_1', 'ml.p3dn.24xlarge', 64),
+                        sagemaker.InstanceGroup(
+                            'instance_group_name_2', 'ml.c5n.18xlarge', 64)]
+
+                For instructions on how to use ``InstanceGroup`` objects
+                to configure a heterogeneous cluster
+                through the SageMaker generic and framework estimator classes, see
+                `Train Using a Heterogeneous Cluster
+                <https://docs.aws.amazon.com/sagemaker/latest/dg/train-heterogeneous-cluster.html>`_
+                in the *Amazon SageMaker developer guide*.
         """
         instance_count = renamed_kwargs(
             "train_instance_count", "instance_count", instance_count, kwargs
@@ -2418,10 +2430,25 @@ def __init__(
                     >>>     |------ virtual-env
 
                 This is not supported with "local code" in Local Mode.
-            instance_groups (list[InstanceGroup]): Optional. List of InstanceGroup
-                for specifying different instance groups for heterogeneous cluster.
-                For example: [sagemaker.InstanceGroup('worker','ml.p3dn.24xlarge',64),
-                sagemaker.InstanceGroup('server','ml.c5n.18xlarge',64)]
+            instance_groups (list[:class:`sagemaker.instance_group.InstanceGroup`]):
+                Optional. A list of ``InstanceGroup`` objects
+                for launching a training job with a heterogeneous cluster.
+                For example:
+
+                .. code:: python
+
+                    instance_groups=[
+                        sagemaker.InstanceGroup(
+                            'instance_group_name_1', 'ml.p3dn.24xlarge', 64),
+                        sagemaker.InstanceGroup(
+                            'instance_group_name_2', 'ml.c5n.18xlarge', 64)]
+
+                For instructions on how to use ``InstanceGroup`` objects
+                to configure a heterogeneous cluster
+                through the SageMaker generic and framework estimator classes, see
+                `Train Using a Heterogeneous Cluster
+                <https://docs.aws.amazon.com/sagemaker/latest/dg/train-heterogeneous-cluster.html>`_
+                in the *Amazon SageMaker developer guide*.
         """
         self.image_uri = image_uri
         self._hyperparameters = hyperparameters.copy() if hyperparameters else {}

src/sagemaker/inputs.py

@@ -41,28 +41,37 @@ def __init__(
         target_attribute_name=None,
         shuffle_config=None,
     ):
-        """Create a definition for input data used by an SageMaker training job.
+        r"""Create a definition for input data used by an SageMaker training job.
 
-        See AWS documentation on the ``CreateTrainingJob`` API for more details on the parameters.
+        See AWS documentation on the ``CreateTrainingJob`` API for more details
+        on the parameters.
 
         Args:
-            s3_data (str): Defines the location of s3 data to train on.
-            distribution (str): Valid values: 'FullyReplicated', 'ShardedByS3Key'
-                (default: 'FullyReplicated').
-            compression (str): Valid values: 'Gzip', None (default: None). This is used only in
+            s3_data (str): Defines the location of S3 data to train on.
+            distribution (str): Valid values: ``'FullyReplicated'``,
+            ``'ShardedByS3Key'``
+                (default: ``'FullyReplicated'``).
+            compression (str): Valid values: ``'Gzip'``, ``None`` (default: None).
+            This is used only in
                 Pipe input mode.
             content_type (str): MIME type of the input data (default: None).
             record_wrapping (str): Valid values: 'RecordIO' (default: None).
-            s3_data_type (str): Valid values: 'S3Prefix', 'ManifestFile', 'AugmentedManifestFile'.
-                If 'S3Prefix', ``s3_data`` defines a prefix of s3 objects to train on.
+            s3_data_type (str): Valid values: ``'S3Prefix'``, ``'ManifestFile'``,
+            ``'AugmentedManifestFile'``.
+                If ``'S3Prefix'``, ``s3_data`` defines a prefix of s3 objects to train on.
                 All objects with s3 keys beginning with ``s3_data`` will be used to train.
-                If 'ManifestFile' or 'AugmentedManifestFile', then ``s3_data`` defines a
-                single S3 manifest file or augmented manifest file (respectively),
+                If ``'ManifestFile'`` or ``'AugmentedManifestFile'``,
+                then ``s3_data`` defines a
+                single S3 manifest file or augmented manifest file respectively,
                 listing the S3 data to train on. Both the ManifestFile and
-                AugmentedManifestFile formats are described in the SageMaker API documentation:
-                https://docs.aws.amazon.com/sagemaker/latest/dg/API_S3DataSource.html
-            instance_groups (list[str]): Optional. List of InstanceGroupNames to send data to
-                (default: None). By default, data will be sent to all groups.
+                AugmentedManifestFile formats are described at `S3DataSource
+                <https://docs.aws.amazon.com/sagemaker/latest/dg/API_S3DataSource.html>`_
+                in the `Amazon SageMaker API reference`.
+            instance_groups (list[str]): Optional. A list of ``instance_group_name``\ s
+                of a heterogeneous cluster that's configured using the
+                :class:`sagemaker.instance_group.InstanceGroup`.
+                S3 data will be sent to all instance groups in the specified list.
+                (default: None)
             input_mode (str): Optional override for this channel's input mode (default: None).
                 By default, channels will use the input mode defined on
                 ``sagemaker.estimator.EstimatorBase.input_mode``, but they will ignore

src/sagemaker/instance_group.py

@@ -10,32 +10,43 @@
 # 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 defines instance group for heterogeneous cluster."""
+"""Defines the InstanceGroup class that configures a heterogeneous cluster."""
 from __future__ import absolute_import
 
 
 class InstanceGroup(object):
-    """Accepts instance group parameters for conversion to request dict.
-
-    The `_to_request_dict` provides a method to turn the parameters into a dict.
-    """
+    """The class to create instance groups for a heterogeneous cluster."""
 
     def __init__(
         self,
         instance_group_name=None,
         instance_type=None,
         instance_count=None,
     ):
-        """Initialize a ``InstanceGroup`` instance.
+        """It initializes an ``InstanceGroup`` instance.
+
+        You can create instance group object of the ``InstanceGroup`` class
+        by specifying the instance group configuration arguments.
 
-        InstanceGroup accepts instance group parameters and provides a method to turn
-        these parameters into a dictionary.
+        For instructions on how to use InstanceGroup objects
+        to configure a heterogeneous cluster
+        through the SageMaker generic and framework estimator classes, see
+        `Train Using a Heterogeneous Cluster
+        <https://docs.aws.amazon.com/sagemaker/latest/dg/train-heterogeneous-cluster.html>`_
+        in the *Amazon SageMaker developer guide*.
 
         Args:
-            instance_group_name (str): Name of the instance group.
-            instance_type (str): Type of EC2 instance to use in the instance group,
-                for example, 'ml.c4.xlarge'.
-            instance_count (int): Number of EC2 instances to use in the instance group.
+            instance_group_name (str): The name of the instance group.
+            instance_type (str): The instance type to use in the instance group.
+            instance_count (int): The number of instances to use in the instance group.
+
+                .. tip::
+
+                    For more information about available values for the arguments,
+                    see `InstanceGroup
+                    <https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_InstanceGroup.html>`_
+                    API in the `Amazon SageMaker API reference`.
+
         """
         self.instance_group_name = instance_group_name
         self.instance_type = instance_type