Amazon SageMaker Service

2020/08/14 - Amazon SageMaker Service - 5 updated api methods

Changes  Update sagemaker client to latest version

CreateAutoMLJob (updated) Link ¶
Changes (request)
{'AutoMLJobObjective': {'MetricName': {'AUC'}}}

Creates an Autopilot job.

Find the best performing model after you run an Autopilot job by calling . Deploy that model by following the steps described in Step 6.1: Deploy the Model to Amazon SageMaker Hosting Services.

For information about how to use Autopilot, see Automate Model Development with Amazon SageMaker Autopilot.

See also: AWS API Documentation

Request Syntax

client.create_auto_ml_job(
    AutoMLJobName='string',
    InputDataConfig=[
        {
            'DataSource': {
                'S3DataSource': {
                    'S3DataType': 'ManifestFile'|'S3Prefix',
                    'S3Uri': 'string'
                }
            },
            'CompressionType': 'None'|'Gzip',
            'TargetAttributeName': 'string'
        },
    ],
    OutputDataConfig={
        'KmsKeyId': 'string',
        'S3OutputPath': 'string'
    },
    ProblemType='BinaryClassification'|'MulticlassClassification'|'Regression',
    AutoMLJobObjective={
        'MetricName': 'Accuracy'|'MSE'|'F1'|'F1macro'|'AUC'
    },
    AutoMLJobConfig={
        'CompletionCriteria': {
            'MaxCandidates': 123,
            'MaxRuntimePerTrainingJobInSeconds': 123,
            'MaxAutoMLJobRuntimeInSeconds': 123
        },
        'SecurityConfig': {
            'VolumeKmsKeyId': 'string',
            'EnableInterContainerTrafficEncryption': True|False,
            'VpcConfig': {
                'SecurityGroupIds': [
                    'string',
                ],
                'Subnets': [
                    'string',
                ]
            }
        }
    },
    RoleArn='string',
    GenerateCandidateDefinitionsOnly=True|False,
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)
type AutoMLJobName

string

param AutoMLJobName

[REQUIRED]

Identifies an Autopilot job. Must be unique to your account and is case-insensitive.

type InputDataConfig

list

param InputDataConfig

[REQUIRED]

Similar to InputDataConfig supported by Tuning. Format(s) supported: CSV. Minimum of 1000 rows.

  • (dict) --

    Similar to Channel. A channel is a named input source that training algorithms can consume. Refer to Channel for detailed descriptions.

    • DataSource (dict) -- [REQUIRED]

      The data source.

      • S3DataSource (dict) -- [REQUIRED]

        The Amazon S3 location of the input data.

        Note

        The input data must be in CSV format and contain at least 1000 rows.

        • S3DataType (string) -- [REQUIRED]

          The data type.

        • S3Uri (string) -- [REQUIRED]

          The URL to the Amazon S3 data source.

    • CompressionType (string) --

      You can use Gzip or None. The default value is None.

    • TargetAttributeName (string) -- [REQUIRED]

      The name of the target variable in supervised learning, a.k.a. 'y'.

type OutputDataConfig

dict

param OutputDataConfig

[REQUIRED]

Similar to OutputDataConfig supported by Tuning. Format(s) supported: CSV.

  • KmsKeyId (string) --

    The AWS KMS encryption key ID.

  • S3OutputPath (string) -- [REQUIRED]

    The Amazon S3 output path. Must be 128 characters or less.

type ProblemType

string

param ProblemType

Defines the kind of preprocessing and algorithms intended for the candidates. Options include: BinaryClassification, MulticlassClassification, and Regression.

type AutoMLJobObjective

dict

param AutoMLJobObjective

Defines the objective of a an AutoML job. You provide a AutoMLJobObjective$MetricName and Autopilot infers whether to minimize or maximize it. If a metric is not specified, the most commonly used ObjectiveMetric for problem type is automaically selected.

  • MetricName (string) -- [REQUIRED]

    The name of the objective metric used to measure the predictive quality of a machine learning system. This metric is optimized during training to provide the best estimate for model parameter values from data.

    Here are the options:

    • MSE : The mean squared error (MSE) is the average of the squared differences between the predicted and actual values. It is used for regression. MSE values are always positive, the better a model is at predicting the actual values the smaller the MSE value. When the data contains outliers, they tend to dominate the MSE which might cause subpar prediction performance.

    • Accuracy : The ratio of the number correctly classified items to the total number (correctly and incorrectly) classified. It is used for binary and multiclass classification. Measures how close the predicted class values are to the actual values. Accuracy values vary between zero and one, one being perfect accuracy and zero perfect inaccuracy.

    • F1 : The F1 score is the harmonic mean of the precision and recall. It is used for binary classification into classes traditionally referred to as positive and negative. Predictions are said to be true when they match their actual (correct) class; false when they do not. Precision is the ratio of the true positive predictions to all positive predictions (including the false positives) in a data set and measures the quality of the prediction when it predicts the positive class. Recall (or sensitivity) is the ratio of the true positive predictions to all actual positive instances and measures how completely a model predicts the actual class members in a data set. The standard F1 score weighs precision and recall equally. But which metric is paramount typically depends on specific aspects of a problem. F1 scores vary between zero and one, one being the best possible performance and zero the worst.

    • AUC : The area under the curve (AUC) metric is used to compare and evaluate binary classification by algorithms such as logistic regression that return probabilities. A threshold is needed to map the probabilities into classifications. The relevant curve is the receiver operating characteristic curve that plots the true positive rate (TPR) of predictions (or recall) against the false positive rate (FPR) as a function of the threshold value, above which a prediction is considered positive. Increasing the threshold results in fewer false positives but more false negatives. AUC is the area under this receiver operating characteristic curve and so provides an aggregated measure of the model performance across all possible classification thresholds. The AUC score can also be interpreted as the probability that a randomly selected positive data point is more likely to be predicted positive than a randomly selected negative example. AUC scores vary between zero and one, one being perfect accuracy and one half not better than a random classifier. Values less that one half predict worse than a random predictor and such consistently bad predictors can be inverted to obtain better than random predictors.

    • F1macro : The F1macro score applies F1 scoring to multiclass classification. In this context, you have multiple classes to predict. You just calculate the precision and recall for each class as you did for the positive class in binary classification. Then used these values to calculate the F1 score for each class and average them to obtain the F1macro score. F1macro scores vary between zero and one, one being the best possible performance and zero the worst.

    If you do not specify a metric explicitly, the default behavior is to automatically use:

    • MSE : for regression.

    • F1 : for binary classification

    • Accuracy : for multiclass classification.

type AutoMLJobConfig

dict

param AutoMLJobConfig

Contains CompletionCriteria and SecurityConfig.

  • CompletionCriteria (dict) --

    How long a job is allowed to run, or how many candidates a job is allowed to generate.

    • MaxCandidates (integer) --

      The maximum number of times a training job is allowed to run.

    • MaxRuntimePerTrainingJobInSeconds (integer) --

      The maximum time, in seconds, a job is allowed to run.

    • MaxAutoMLJobRuntimeInSeconds (integer) --

      The maximum time, in seconds, an AutoML job is allowed to wait for a trial to complete. It must be equal to or greater than MaxRuntimePerTrainingJobInSeconds.

  • SecurityConfig (dict) --

    Security configuration for traffic encryption or Amazon VPC settings.

    • VolumeKmsKeyId (string) --

      The key used to encrypt stored data.

    • EnableInterContainerTrafficEncryption (boolean) --

      Whether to use traffic encryption between the container layers.

    • VpcConfig (dict) --

      VPC configuration.

      • SecurityGroupIds (list) -- [REQUIRED]

        The VPC security group IDs, in the form sg-xxxxxxxx. Specify the security groups for the VPC that is specified in the Subnets field.

        • (string) --

      • Subnets (list) -- [REQUIRED]

        The ID of the subnets in the VPC to which you want to connect your training job or model. For information about the availability of specific instance types, see Supported Instance Types and Availability Zones.

        • (string) --

type RoleArn

string

param RoleArn

[REQUIRED]

The ARN of the role that is used to access the data.

type GenerateCandidateDefinitionsOnly

boolean

param GenerateCandidateDefinitionsOnly

Generates possible candidates without training a model. A candidate is a combination of data preprocessors, algorithms, and algorithm parameter settings.

type Tags

list

param Tags

Each tag consists of a key and an optional value. Tag keys must be unique per resource.

  • (dict) --

    Describes a tag.

    • Key (string) -- [REQUIRED]

      The tag key.

    • Value (string) -- [REQUIRED]

      The tag value.

rtype

dict

returns

Response Syntax

{
    'AutoMLJobArn': 'string'
}

Response Structure

  • (dict) --

    • AutoMLJobArn (string) --

      When a job is created, it is assigned a unique ARN.

CreateModel (updated) Link ¶
Changes (request)
{'Containers': {'ImageConfig': {'RepositoryAccessMode': 'Platform | Vpc'}},
 'PrimaryContainer': {'ImageConfig': {'RepositoryAccessMode': 'Platform | '
                                                              'Vpc'}}}

Creates a model in Amazon SageMaker. In the request, you name the model and describe a primary container. For the primary container, you specify the Docker image that contains inference code, artifacts (from prior training), and a custom environment map that the inference code uses when you deploy the model for predictions.

Use this API to create a model if you want to use Amazon SageMaker hosting services or run a batch transform job.

To host your model, you create an endpoint configuration with the CreateEndpointConfig API, and then create an endpoint with the CreateEndpoint API. Amazon SageMaker then deploys all of the containers that you defined for the model in the hosting environment.

For an example that calls this method when deploying a model to Amazon SageMaker hosting services, see Deploy the Model to Amazon SageMaker Hosting Services (AWS SDK for Python (Boto 3)).

To run a batch transform using your model, you start a job with the CreateTransformJob API. Amazon SageMaker uses your model and your dataset to get inferences which are then saved to a specified S3 location.

In the CreateModel request, you must define a container with the PrimaryContainer parameter.

In the request, you also provide an IAM role that Amazon SageMaker can assume to access model artifacts and docker image for deployment on ML compute hosting instances or for batch transform jobs. In addition, you also use the IAM role to manage permissions the inference code needs. For example, if the inference code access any other AWS resources, you grant necessary permissions via this role.

See also: AWS API Documentation

Request Syntax

client.create_model(
    ModelName='string',
    PrimaryContainer={
        'ContainerHostname': 'string',
        'Image': 'string',
        'ImageConfig': {
            'RepositoryAccessMode': 'Platform'|'Vpc'
        },
        'Mode': 'SingleModel'|'MultiModel',
        'ModelDataUrl': 'string',
        'Environment': {
            'string': 'string'
        },
        'ModelPackageName': 'string'
    },
    Containers=[
        {
            'ContainerHostname': 'string',
            'Image': 'string',
            'ImageConfig': {
                'RepositoryAccessMode': 'Platform'|'Vpc'
            },
            'Mode': 'SingleModel'|'MultiModel',
            'ModelDataUrl': 'string',
            'Environment': {
                'string': 'string'
            },
            'ModelPackageName': 'string'
        },
    ],
    ExecutionRoleArn='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ],
    VpcConfig={
        'SecurityGroupIds': [
            'string',
        ],
        'Subnets': [
            'string',
        ]
    },
    EnableNetworkIsolation=True|False
)
type ModelName

string

param ModelName

[REQUIRED]

The name of the new model.

type PrimaryContainer

dict

param PrimaryContainer

The location of the primary docker image containing inference code, associated artifacts, and custom environment map that the inference code uses when the model is deployed for predictions.

  • ContainerHostname (string) --

    This parameter is ignored for models that contain only a PrimaryContainer .

    When a ContainerDefinition is part of an inference pipeline, the value of the parameter uniquely identifies the container for the purposes of logging and metrics. For information, see Use Logs and Metrics to Monitor an Inference Pipeline. If you don't specify a value for this parameter for a ContainerDefinition that is part of an inference pipeline, a unique name is automatically assigned based on the position of the ContainerDefinition in the pipeline. If you specify a value for the ContainerHostName for any ContainerDefinition that is part of an inference pipeline, you must specify a value for the ContainerHostName parameter of every ContainerDefinition in that pipeline.

  • Image (string) --

    The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored. If you are using your own custom algorithm instead of an algorithm provided by Amazon SageMaker, the inference code must meet Amazon SageMaker requirements. Amazon SageMaker supports both registry/repository[:tag] and registry/repository[@digest] image path formats. For more information, see Using Your Own Algorithms with Amazon SageMaker

  • ImageConfig (dict) --

    Specifies whether the model container is in Amazon ECR or a private Docker registry in your Amazon Virtual Private Cloud (VPC). For information about storing containers in a private Docker registry, see Use a Private Docker Registry for Real-Time Inference Containers

    • RepositoryAccessMode (string) -- [REQUIRED]

      Set this to one of the following values:

      • Platform - The model image is hosted in Amazon ECR.

      • VPC - The model image is hosted in a private Docker registry in your VPC.

  • Mode (string) --

    Whether the container hosts a single model or multiple models.

  • ModelDataUrl (string) --

    The S3 path where the model artifacts, which result from model training, are stored. This path must point to a single gzip compressed tar archive (.tar.gz suffix). The S3 path is required for Amazon SageMaker built-in algorithms, but not if you use your own algorithms. For more information on built-in algorithms, see Common Parameters.

    If you provide a value for this parameter, Amazon SageMaker uses AWS Security Token Service to download model artifacts from the S3 path you provide. AWS STS is activated in your IAM user account by default. If you previously deactivated AWS STS for a region, you need to reactivate AWS STS for that region. For more information, see Activating and Deactivating AWS STS in an AWS Region in the AWS Identity and Access Management User Guide .

    Warning

    If you use a built-in algorithm to create a model, Amazon SageMaker requires that you provide a S3 path to the model artifacts in ModelDataUrl .

  • Environment (dict) --

    The environment variables to set in the Docker container. Each key and value in the Environment string to string map can have length of up to 1024. We support up to 16 entries in the map.

    • (string) --

      • (string) --

  • ModelPackageName (string) --

    The name or Amazon Resource Name (ARN) of the model package to use to create the model.

type Containers

list

param Containers

Specifies the containers in the inference pipeline.

  • (dict) --

    Describes the container, as part of model definition.

    • ContainerHostname (string) --

      This parameter is ignored for models that contain only a PrimaryContainer .

      When a ContainerDefinition is part of an inference pipeline, the value of the parameter uniquely identifies the container for the purposes of logging and metrics. For information, see Use Logs and Metrics to Monitor an Inference Pipeline. If you don't specify a value for this parameter for a ContainerDefinition that is part of an inference pipeline, a unique name is automatically assigned based on the position of the ContainerDefinition in the pipeline. If you specify a value for the ContainerHostName for any ContainerDefinition that is part of an inference pipeline, you must specify a value for the ContainerHostName parameter of every ContainerDefinition in that pipeline.

    • Image (string) --

      The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored. If you are using your own custom algorithm instead of an algorithm provided by Amazon SageMaker, the inference code must meet Amazon SageMaker requirements. Amazon SageMaker supports both registry/repository[:tag] and registry/repository[@digest] image path formats. For more information, see Using Your Own Algorithms with Amazon SageMaker

    • ImageConfig (dict) --

      Specifies whether the model container is in Amazon ECR or a private Docker registry in your Amazon Virtual Private Cloud (VPC). For information about storing containers in a private Docker registry, see Use a Private Docker Registry for Real-Time Inference Containers

      • RepositoryAccessMode (string) -- [REQUIRED]

        Set this to one of the following values:

        • Platform - The model image is hosted in Amazon ECR.

        • VPC - The model image is hosted in a private Docker registry in your VPC.

    • Mode (string) --

      Whether the container hosts a single model or multiple models.

    • ModelDataUrl (string) --

      The S3 path where the model artifacts, which result from model training, are stored. This path must point to a single gzip compressed tar archive (.tar.gz suffix). The S3 path is required for Amazon SageMaker built-in algorithms, but not if you use your own algorithms. For more information on built-in algorithms, see Common Parameters.

      If you provide a value for this parameter, Amazon SageMaker uses AWS Security Token Service to download model artifacts from the S3 path you provide. AWS STS is activated in your IAM user account by default. If you previously deactivated AWS STS for a region, you need to reactivate AWS STS for that region. For more information, see Activating and Deactivating AWS STS in an AWS Region in the AWS Identity and Access Management User Guide .

      Warning

      If you use a built-in algorithm to create a model, Amazon SageMaker requires that you provide a S3 path to the model artifacts in ModelDataUrl .

    • Environment (dict) --

      The environment variables to set in the Docker container. Each key and value in the Environment string to string map can have length of up to 1024. We support up to 16 entries in the map.

      • (string) --

        • (string) --

    • ModelPackageName (string) --

      The name or Amazon Resource Name (ARN) of the model package to use to create the model.

type ExecutionRoleArn

string

param ExecutionRoleArn

[REQUIRED]

The Amazon Resource Name (ARN) of the IAM role that Amazon SageMaker can assume to access model artifacts and docker image for deployment on ML compute instances or for batch transform jobs. Deploying on ML compute instances is part of model hosting. For more information, see Amazon SageMaker Roles.

Note

To be able to pass this role to Amazon SageMaker, the caller of this API must have the iam:PassRole permission.

type Tags

list

param Tags

An array of key-value pairs. For more information, see Using Cost Allocation Tags in the AWS Billing and Cost Management User Guide .

  • (dict) --

    Describes a tag.

    • Key (string) -- [REQUIRED]

      The tag key.

    • Value (string) -- [REQUIRED]

      The tag value.

type VpcConfig

dict

param VpcConfig

A VpcConfig object that specifies the VPC that you want your model to connect to. Control access to and from your model container by configuring the VPC. VpcConfig is used in hosting services and in batch transform. For more information, see Protect Endpoints by Using an Amazon Virtual Private Cloud and Protect Data in Batch Transform Jobs by Using an Amazon Virtual Private Cloud.

  • SecurityGroupIds (list) -- [REQUIRED]

    The VPC security group IDs, in the form sg-xxxxxxxx. Specify the security groups for the VPC that is specified in the Subnets field.

    • (string) --

  • Subnets (list) -- [REQUIRED]

    The ID of the subnets in the VPC to which you want to connect your training job or model. For information about the availability of specific instance types, see Supported Instance Types and Availability Zones.

    • (string) --

type EnableNetworkIsolation

boolean

param EnableNetworkIsolation

Isolates the model container. No inbound or outbound network calls can be made to or from the model container.

rtype

dict

returns

Response Syntax

{
    'ModelArn': 'string'
}

Response Structure

  • (dict) --

    • ModelArn (string) --

      The ARN of the model created in Amazon SageMaker.

DescribeAutoMLJob (updated) Link ¶
Changes (response)
{'AutoMLJobObjective': {'MetricName': {'AUC'}},
 'BestCandidate': {'FinalAutoMLJobObjectiveMetric': {'MetricName': {'AUC'}}},
 'ResolvedAttributes': {'AutoMLJobObjective': {'MetricName': {'AUC'}}}}

Returns information about an Amazon SageMaker job.

See also: AWS API Documentation

Request Syntax

client.describe_auto_ml_job(
    AutoMLJobName='string'
)
type AutoMLJobName

string

param AutoMLJobName

[REQUIRED]

Request information about a job using that job's unique name.

rtype

dict

returns

Response Syntax

{
    'AutoMLJobName': 'string',
    'AutoMLJobArn': 'string',
    'InputDataConfig': [
        {
            'DataSource': {
                'S3DataSource': {
                    'S3DataType': 'ManifestFile'|'S3Prefix',
                    'S3Uri': 'string'
                }
            },
            'CompressionType': 'None'|'Gzip',
            'TargetAttributeName': 'string'
        },
    ],
    'OutputDataConfig': {
        'KmsKeyId': 'string',
        'S3OutputPath': 'string'
    },
    'RoleArn': 'string',
    'AutoMLJobObjective': {
        'MetricName': 'Accuracy'|'MSE'|'F1'|'F1macro'|'AUC'
    },
    'ProblemType': 'BinaryClassification'|'MulticlassClassification'|'Regression',
    'AutoMLJobConfig': {
        'CompletionCriteria': {
            'MaxCandidates': 123,
            'MaxRuntimePerTrainingJobInSeconds': 123,
            'MaxAutoMLJobRuntimeInSeconds': 123
        },
        'SecurityConfig': {
            'VolumeKmsKeyId': 'string',
            'EnableInterContainerTrafficEncryption': True|False,
            'VpcConfig': {
                'SecurityGroupIds': [
                    'string',
                ],
                'Subnets': [
                    'string',
                ]
            }
        }
    },
    'CreationTime': datetime(2015, 1, 1),
    'EndTime': datetime(2015, 1, 1),
    'LastModifiedTime': datetime(2015, 1, 1),
    'FailureReason': 'string',
    'BestCandidate': {
        'CandidateName': 'string',
        'FinalAutoMLJobObjectiveMetric': {
            'Type': 'Maximize'|'Minimize',
            'MetricName': 'Accuracy'|'MSE'|'F1'|'F1macro'|'AUC',
            'Value': ...
        },
        'ObjectiveStatus': 'Succeeded'|'Pending'|'Failed',
        'CandidateSteps': [
            {
                'CandidateStepType': 'AWS::SageMaker::TrainingJob'|'AWS::SageMaker::TransformJob'|'AWS::SageMaker::ProcessingJob',
                'CandidateStepArn': 'string',
                'CandidateStepName': 'string'
            },
        ],
        'CandidateStatus': 'Completed'|'InProgress'|'Failed'|'Stopped'|'Stopping',
        'InferenceContainers': [
            {
                'Image': 'string',
                'ModelDataUrl': 'string',
                'Environment': {
                    'string': 'string'
                }
            },
        ],
        'CreationTime': datetime(2015, 1, 1),
        'EndTime': datetime(2015, 1, 1),
        'LastModifiedTime': datetime(2015, 1, 1),
        'FailureReason': 'string'
    },
    'AutoMLJobStatus': 'Completed'|'InProgress'|'Failed'|'Stopped'|'Stopping',
    'AutoMLJobSecondaryStatus': 'Starting'|'AnalyzingData'|'FeatureEngineering'|'ModelTuning'|'MaxCandidatesReached'|'Failed'|'Stopped'|'MaxAutoMLJobRuntimeReached'|'Stopping'|'CandidateDefinitionsGenerated',
    'GenerateCandidateDefinitionsOnly': True|False,
    'AutoMLJobArtifacts': {
        'CandidateDefinitionNotebookLocation': 'string',
        'DataExplorationNotebookLocation': 'string'
    },
    'ResolvedAttributes': {
        'AutoMLJobObjective': {
            'MetricName': 'Accuracy'|'MSE'|'F1'|'F1macro'|'AUC'
        },
        'ProblemType': 'BinaryClassification'|'MulticlassClassification'|'Regression',
        'CompletionCriteria': {
            'MaxCandidates': 123,
            'MaxRuntimePerTrainingJobInSeconds': 123,
            'MaxAutoMLJobRuntimeInSeconds': 123
        }
    }
}

Response Structure

  • (dict) --

    • AutoMLJobName (string) --

      Returns the name of a job.

    • AutoMLJobArn (string) --

      Returns the job's ARN.

    • InputDataConfig (list) --

      Returns the job's input data config.

      • (dict) --

        Similar to Channel. A channel is a named input source that training algorithms can consume. Refer to Channel for detailed descriptions.

        • DataSource (dict) --

          The data source.

          • S3DataSource (dict) --

            The Amazon S3 location of the input data.

            Note

            The input data must be in CSV format and contain at least 1000 rows.

            • S3DataType (string) --

              The data type.

            • S3Uri (string) --

              The URL to the Amazon S3 data source.

        • CompressionType (string) --

          You can use Gzip or None. The default value is None.

        • TargetAttributeName (string) --

          The name of the target variable in supervised learning, a.k.a. 'y'.

    • OutputDataConfig (dict) --

      Returns the job's output data config.

      • KmsKeyId (string) --

        The AWS KMS encryption key ID.

      • S3OutputPath (string) --

        The Amazon S3 output path. Must be 128 characters or less.

    • RoleArn (string) --

      The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that has read permission to the input data location and write permission to the output data location in Amazon S3.

    • AutoMLJobObjective (dict) --

      Returns the job's objective.

      • MetricName (string) --

        The name of the objective metric used to measure the predictive quality of a machine learning system. This metric is optimized during training to provide the best estimate for model parameter values from data.

        Here are the options:

        • MSE : The mean squared error (MSE) is the average of the squared differences between the predicted and actual values. It is used for regression. MSE values are always positive, the better a model is at predicting the actual values the smaller the MSE value. When the data contains outliers, they tend to dominate the MSE which might cause subpar prediction performance.

        • Accuracy : The ratio of the number correctly classified items to the total number (correctly and incorrectly) classified. It is used for binary and multiclass classification. Measures how close the predicted class values are to the actual values. Accuracy values vary between zero and one, one being perfect accuracy and zero perfect inaccuracy.

        • F1 : The F1 score is the harmonic mean of the precision and recall. It is used for binary classification into classes traditionally referred to as positive and negative. Predictions are said to be true when they match their actual (correct) class; false when they do not. Precision is the ratio of the true positive predictions to all positive predictions (including the false positives) in a data set and measures the quality of the prediction when it predicts the positive class. Recall (or sensitivity) is the ratio of the true positive predictions to all actual positive instances and measures how completely a model predicts the actual class members in a data set. The standard F1 score weighs precision and recall equally. But which metric is paramount typically depends on specific aspects of a problem. F1 scores vary between zero and one, one being the best possible performance and zero the worst.

        • AUC : The area under the curve (AUC) metric is used to compare and evaluate binary classification by algorithms such as logistic regression that return probabilities. A threshold is needed to map the probabilities into classifications. The relevant curve is the receiver operating characteristic curve that plots the true positive rate (TPR) of predictions (or recall) against the false positive rate (FPR) as a function of the threshold value, above which a prediction is considered positive. Increasing the threshold results in fewer false positives but more false negatives. AUC is the area under this receiver operating characteristic curve and so provides an aggregated measure of the model performance across all possible classification thresholds. The AUC score can also be interpreted as the probability that a randomly selected positive data point is more likely to be predicted positive than a randomly selected negative example. AUC scores vary between zero and one, one being perfect accuracy and one half not better than a random classifier. Values less that one half predict worse than a random predictor and such consistently bad predictors can be inverted to obtain better than random predictors.

        • F1macro : The F1macro score applies F1 scoring to multiclass classification. In this context, you have multiple classes to predict. You just calculate the precision and recall for each class as you did for the positive class in binary classification. Then used these values to calculate the F1 score for each class and average them to obtain the F1macro score. F1macro scores vary between zero and one, one being the best possible performance and zero the worst.

        If you do not specify a metric explicitly, the default behavior is to automatically use:

        • MSE : for regression.

        • F1 : for binary classification

        • Accuracy : for multiclass classification.

    • ProblemType (string) --

      Returns the job's problem type.

    • AutoMLJobConfig (dict) --

      Returns the job's config.

      • CompletionCriteria (dict) --

        How long a job is allowed to run, or how many candidates a job is allowed to generate.

        • MaxCandidates (integer) --

          The maximum number of times a training job is allowed to run.

        • MaxRuntimePerTrainingJobInSeconds (integer) --

          The maximum time, in seconds, a job is allowed to run.

        • MaxAutoMLJobRuntimeInSeconds (integer) --

          The maximum time, in seconds, an AutoML job is allowed to wait for a trial to complete. It must be equal to or greater than MaxRuntimePerTrainingJobInSeconds.

      • SecurityConfig (dict) --

        Security configuration for traffic encryption or Amazon VPC settings.

        • VolumeKmsKeyId (string) --

          The key used to encrypt stored data.

        • EnableInterContainerTrafficEncryption (boolean) --

          Whether to use traffic encryption between the container layers.

        • VpcConfig (dict) --

          VPC configuration.

          • SecurityGroupIds (list) --

            The VPC security group IDs, in the form sg-xxxxxxxx. Specify the security groups for the VPC that is specified in the Subnets field.

            • (string) --

          • Subnets (list) --

            The ID of the subnets in the VPC to which you want to connect your training job or model. For information about the availability of specific instance types, see Supported Instance Types and Availability Zones.

            • (string) --

    • CreationTime (datetime) --

      Returns the job's creation time.

    • EndTime (datetime) --

      Returns the job's end time.

    • LastModifiedTime (datetime) --

      Returns the job's last modified time.

    • FailureReason (string) --

      Returns the job's FailureReason.

    • BestCandidate (dict) --

      Returns the job's BestCandidate.

      • CandidateName (string) --

        The candidate name.

      • FinalAutoMLJobObjectiveMetric (dict) --

        The best candidate result from an AutoML training job.

        • Type (string) --

          The type of metric with the best result.

        • MetricName (string) --

          The name of the metric with the best result. For a description of the possible objective metrics, see AutoMLJobObjective$MetricName.

        • Value (float) --

          The value of the metric with the best result.

      • ObjectiveStatus (string) --

        The objective status.

      • CandidateSteps (list) --

        The candidate's steps.

        • (dict) --

          Information about the steps for a Candidate, and what step it is working on.

          • CandidateStepType (string) --

            Whether the Candidate is at the transform, training, or processing step.

          • CandidateStepArn (string) --

            The ARN for the Candidate's step.

          • CandidateStepName (string) --

            The name for the Candidate's step.

      • CandidateStatus (string) --

        The candidate's status.

      • InferenceContainers (list) --

        The inference containers.

        • (dict) --

          A list of container definitions that describe the different containers that make up one AutoML candidate. Refer to ContainerDefinition for more details.

          • Image (string) --

            The ECR path of the container. Refer to ContainerDefinition for more details.

          • ModelDataUrl (string) --

            The location of the model artifacts. Refer to ContainerDefinition for more details.

          • Environment (dict) --

            Environment variables to set in the container. Refer to ContainerDefinition for more details.

            • (string) --

              • (string) --

      • CreationTime (datetime) --

        The creation time.

      • EndTime (datetime) --

        The end time.

      • LastModifiedTime (datetime) --

        The last modified time.

      • FailureReason (string) --

        The failure reason.

    • AutoMLJobStatus (string) --

      Returns the job's AutoMLJobStatus.

    • AutoMLJobSecondaryStatus (string) --

      Returns the job's AutoMLJobSecondaryStatus.

    • GenerateCandidateDefinitionsOnly (boolean) --

      Returns the job's output from GenerateCandidateDefinitionsOnly.

    • AutoMLJobArtifacts (dict) --

      Returns information on the job's artifacts found in AutoMLJobArtifacts.

      • CandidateDefinitionNotebookLocation (string) --

        The URL to the notebook location.

      • DataExplorationNotebookLocation (string) --

        The URL to the notebook location.

    • ResolvedAttributes (dict) --

      This contains ProblemType, AutoMLJobObjective and CompletionCriteria. They're auto-inferred values, if not provided by you. If you do provide them, then they'll be the same as provided.

      • AutoMLJobObjective (dict) --

        Specifies a metric to minimize or maximize as the objective of a job.

        • MetricName (string) --

          The name of the objective metric used to measure the predictive quality of a machine learning system. This metric is optimized during training to provide the best estimate for model parameter values from data.

          Here are the options:

          • MSE : The mean squared error (MSE) is the average of the squared differences between the predicted and actual values. It is used for regression. MSE values are always positive, the better a model is at predicting the actual values the smaller the MSE value. When the data contains outliers, they tend to dominate the MSE which might cause subpar prediction performance.

          • Accuracy : The ratio of the number correctly classified items to the total number (correctly and incorrectly) classified. It is used for binary and multiclass classification. Measures how close the predicted class values are to the actual values. Accuracy values vary between zero and one, one being perfect accuracy and zero perfect inaccuracy.

          • F1 : The F1 score is the harmonic mean of the precision and recall. It is used for binary classification into classes traditionally referred to as positive and negative. Predictions are said to be true when they match their actual (correct) class; false when they do not. Precision is the ratio of the true positive predictions to all positive predictions (including the false positives) in a data set and measures the quality of the prediction when it predicts the positive class. Recall (or sensitivity) is the ratio of the true positive predictions to all actual positive instances and measures how completely a model predicts the actual class members in a data set. The standard F1 score weighs precision and recall equally. But which metric is paramount typically depends on specific aspects of a problem. F1 scores vary between zero and one, one being the best possible performance and zero the worst.

          • AUC : The area under the curve (AUC) metric is used to compare and evaluate binary classification by algorithms such as logistic regression that return probabilities. A threshold is needed to map the probabilities into classifications. The relevant curve is the receiver operating characteristic curve that plots the true positive rate (TPR) of predictions (or recall) against the false positive rate (FPR) as a function of the threshold value, above which a prediction is considered positive. Increasing the threshold results in fewer false positives but more false negatives. AUC is the area under this receiver operating characteristic curve and so provides an aggregated measure of the model performance across all possible classification thresholds. The AUC score can also be interpreted as the probability that a randomly selected positive data point is more likely to be predicted positive than a randomly selected negative example. AUC scores vary between zero and one, one being perfect accuracy and one half not better than a random classifier. Values less that one half predict worse than a random predictor and such consistently bad predictors can be inverted to obtain better than random predictors.

          • F1macro : The F1macro score applies F1 scoring to multiclass classification. In this context, you have multiple classes to predict. You just calculate the precision and recall for each class as you did for the positive class in binary classification. Then used these values to calculate the F1 score for each class and average them to obtain the F1macro score. F1macro scores vary between zero and one, one being the best possible performance and zero the worst.

          If you do not specify a metric explicitly, the default behavior is to automatically use:

          • MSE : for regression.

          • F1 : for binary classification

          • Accuracy : for multiclass classification.

      • ProblemType (string) --

        The problem type.

      • CompletionCriteria (dict) --

        How long a job is allowed to run, or how many candidates a job is allowed to generate.

        • MaxCandidates (integer) --

          The maximum number of times a training job is allowed to run.

        • MaxRuntimePerTrainingJobInSeconds (integer) --

          The maximum time, in seconds, a job is allowed to run.

        • MaxAutoMLJobRuntimeInSeconds (integer) --

          The maximum time, in seconds, an AutoML job is allowed to wait for a trial to complete. It must be equal to or greater than MaxRuntimePerTrainingJobInSeconds.

DescribeModel (updated) Link ¶
Changes (response)
{'Containers': {'ImageConfig': {'RepositoryAccessMode': 'Platform | Vpc'}},
 'PrimaryContainer': {'ImageConfig': {'RepositoryAccessMode': 'Platform | '
                                                              'Vpc'}}}

Describes a model that you created using the CreateModel API.

See also: AWS API Documentation

Request Syntax

client.describe_model(
    ModelName='string'
)
type ModelName

string

param ModelName

[REQUIRED]

The name of the model.

rtype

dict

returns

Response Syntax

{
    'ModelName': 'string',
    'PrimaryContainer': {
        'ContainerHostname': 'string',
        'Image': 'string',
        'ImageConfig': {
            'RepositoryAccessMode': 'Platform'|'Vpc'
        },
        'Mode': 'SingleModel'|'MultiModel',
        'ModelDataUrl': 'string',
        'Environment': {
            'string': 'string'
        },
        'ModelPackageName': 'string'
    },
    'Containers': [
        {
            'ContainerHostname': 'string',
            'Image': 'string',
            'ImageConfig': {
                'RepositoryAccessMode': 'Platform'|'Vpc'
            },
            'Mode': 'SingleModel'|'MultiModel',
            'ModelDataUrl': 'string',
            'Environment': {
                'string': 'string'
            },
            'ModelPackageName': 'string'
        },
    ],
    'ExecutionRoleArn': 'string',
    'VpcConfig': {
        'SecurityGroupIds': [
            'string',
        ],
        'Subnets': [
            'string',
        ]
    },
    'CreationTime': datetime(2015, 1, 1),
    'ModelArn': 'string',
    'EnableNetworkIsolation': True|False
}

Response Structure

  • (dict) --

    • ModelName (string) --

      Name of the Amazon SageMaker model.

    • PrimaryContainer (dict) --

      The location of the primary inference code, associated artifacts, and custom environment map that the inference code uses when it is deployed in production.

      • ContainerHostname (string) --

        This parameter is ignored for models that contain only a PrimaryContainer .

        When a ContainerDefinition is part of an inference pipeline, the value of the parameter uniquely identifies the container for the purposes of logging and metrics. For information, see Use Logs and Metrics to Monitor an Inference Pipeline. If you don't specify a value for this parameter for a ContainerDefinition that is part of an inference pipeline, a unique name is automatically assigned based on the position of the ContainerDefinition in the pipeline. If you specify a value for the ContainerHostName for any ContainerDefinition that is part of an inference pipeline, you must specify a value for the ContainerHostName parameter of every ContainerDefinition in that pipeline.

      • Image (string) --

        The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored. If you are using your own custom algorithm instead of an algorithm provided by Amazon SageMaker, the inference code must meet Amazon SageMaker requirements. Amazon SageMaker supports both registry/repository[:tag] and registry/repository[@digest] image path formats. For more information, see Using Your Own Algorithms with Amazon SageMaker

      • ImageConfig (dict) --

        Specifies whether the model container is in Amazon ECR or a private Docker registry in your Amazon Virtual Private Cloud (VPC). For information about storing containers in a private Docker registry, see Use a Private Docker Registry for Real-Time Inference Containers

        • RepositoryAccessMode (string) --

          Set this to one of the following values:

          • Platform - The model image is hosted in Amazon ECR.

          • VPC - The model image is hosted in a private Docker registry in your VPC.

      • Mode (string) --

        Whether the container hosts a single model or multiple models.

      • ModelDataUrl (string) --

        The S3 path where the model artifacts, which result from model training, are stored. This path must point to a single gzip compressed tar archive (.tar.gz suffix). The S3 path is required for Amazon SageMaker built-in algorithms, but not if you use your own algorithms. For more information on built-in algorithms, see Common Parameters.

        If you provide a value for this parameter, Amazon SageMaker uses AWS Security Token Service to download model artifacts from the S3 path you provide. AWS STS is activated in your IAM user account by default. If you previously deactivated AWS STS for a region, you need to reactivate AWS STS for that region. For more information, see Activating and Deactivating AWS STS in an AWS Region in the AWS Identity and Access Management User Guide .

        Warning

        If you use a built-in algorithm to create a model, Amazon SageMaker requires that you provide a S3 path to the model artifacts in ModelDataUrl .

      • Environment (dict) --

        The environment variables to set in the Docker container. Each key and value in the Environment string to string map can have length of up to 1024. We support up to 16 entries in the map.

        • (string) --

          • (string) --

      • ModelPackageName (string) --

        The name or Amazon Resource Name (ARN) of the model package to use to create the model.

    • Containers (list) --

      The containers in the inference pipeline.

      • (dict) --

        Describes the container, as part of model definition.

        • ContainerHostname (string) --

          This parameter is ignored for models that contain only a PrimaryContainer .

          When a ContainerDefinition is part of an inference pipeline, the value of the parameter uniquely identifies the container for the purposes of logging and metrics. For information, see Use Logs and Metrics to Monitor an Inference Pipeline. If you don't specify a value for this parameter for a ContainerDefinition that is part of an inference pipeline, a unique name is automatically assigned based on the position of the ContainerDefinition in the pipeline. If you specify a value for the ContainerHostName for any ContainerDefinition that is part of an inference pipeline, you must specify a value for the ContainerHostName parameter of every ContainerDefinition in that pipeline.

        • Image (string) --

          The Amazon EC2 Container Registry (Amazon ECR) path where inference code is stored. If you are using your own custom algorithm instead of an algorithm provided by Amazon SageMaker, the inference code must meet Amazon SageMaker requirements. Amazon SageMaker supports both registry/repository[:tag] and registry/repository[@digest] image path formats. For more information, see Using Your Own Algorithms with Amazon SageMaker

        • ImageConfig (dict) --

          Specifies whether the model container is in Amazon ECR or a private Docker registry in your Amazon Virtual Private Cloud (VPC). For information about storing containers in a private Docker registry, see Use a Private Docker Registry for Real-Time Inference Containers

          • RepositoryAccessMode (string) --

            Set this to one of the following values:

            • Platform - The model image is hosted in Amazon ECR.

            • VPC - The model image is hosted in a private Docker registry in your VPC.

        • Mode (string) --

          Whether the container hosts a single model or multiple models.

        • ModelDataUrl (string) --

          The S3 path where the model artifacts, which result from model training, are stored. This path must point to a single gzip compressed tar archive (.tar.gz suffix). The S3 path is required for Amazon SageMaker built-in algorithms, but not if you use your own algorithms. For more information on built-in algorithms, see Common Parameters.

          If you provide a value for this parameter, Amazon SageMaker uses AWS Security Token Service to download model artifacts from the S3 path you provide. AWS STS is activated in your IAM user account by default. If you previously deactivated AWS STS for a region, you need to reactivate AWS STS for that region. For more information, see Activating and Deactivating AWS STS in an AWS Region in the AWS Identity and Access Management User Guide .

          Warning

          If you use a built-in algorithm to create a model, Amazon SageMaker requires that you provide a S3 path to the model artifacts in ModelDataUrl .

        • Environment (dict) --

          The environment variables to set in the Docker container. Each key and value in the Environment string to string map can have length of up to 1024. We support up to 16 entries in the map.

          • (string) --

            • (string) --

        • ModelPackageName (string) --

          The name or Amazon Resource Name (ARN) of the model package to use to create the model.

    • ExecutionRoleArn (string) --

      The Amazon Resource Name (ARN) of the IAM role that you specified for the model.

    • VpcConfig (dict) --

      A VpcConfig object that specifies the VPC that this model has access to. For more information, see Protect Endpoints by Using an Amazon Virtual Private Cloud

      • SecurityGroupIds (list) --

        The VPC security group IDs, in the form sg-xxxxxxxx. Specify the security groups for the VPC that is specified in the Subnets field.

        • (string) --

      • Subnets (list) --

        The ID of the subnets in the VPC to which you want to connect your training job or model. For information about the availability of specific instance types, see Supported Instance Types and Availability Zones.

        • (string) --

    • CreationTime (datetime) --

      A timestamp that shows when the model was created.

    • ModelArn (string) --

      The Amazon Resource Name (ARN) of the model.

    • EnableNetworkIsolation (boolean) --

      If True , no inbound or outbound network calls can be made to or from the model container.

ListCandidatesForAutoMLJob (updated) Link ¶
Changes (response)
{'Candidates': {'FinalAutoMLJobObjectiveMetric': {'MetricName': {'AUC'}}}}

List the Candidates created for the job.

See also: AWS API Documentation

Request Syntax

client.list_candidates_for_auto_ml_job(
    AutoMLJobName='string',
    StatusEquals='Completed'|'InProgress'|'Failed'|'Stopped'|'Stopping',
    CandidateNameEquals='string',
    SortOrder='Ascending'|'Descending',
    SortBy='CreationTime'|'Status'|'FinalObjectiveMetricValue',
    MaxResults=123,
    NextToken='string'
)
type AutoMLJobName

string

param AutoMLJobName

[REQUIRED]

List the Candidates created for the job by providing the job's name.

type StatusEquals

string

param StatusEquals

List the Candidates for the job and filter by status.

type CandidateNameEquals

string

param CandidateNameEquals

List the Candidates for the job and filter by candidate name.

type SortOrder

string

param SortOrder

The sort order for the results. The default is Ascending.

type SortBy

string

param SortBy

The parameter by which to sort the results. The default is Descending.

type MaxResults

integer

param MaxResults

List the job's Candidates up to a specified limit.

type NextToken

string

param NextToken

If the previous response was truncated, you receive this token. Use it in your next request to receive the next set of results.

rtype

dict

returns

Response Syntax

{
    'Candidates': [
        {
            'CandidateName': 'string',
            'FinalAutoMLJobObjectiveMetric': {
                'Type': 'Maximize'|'Minimize',
                'MetricName': 'Accuracy'|'MSE'|'F1'|'F1macro'|'AUC',
                'Value': ...
            },
            'ObjectiveStatus': 'Succeeded'|'Pending'|'Failed',
            'CandidateSteps': [
                {
                    'CandidateStepType': 'AWS::SageMaker::TrainingJob'|'AWS::SageMaker::TransformJob'|'AWS::SageMaker::ProcessingJob',
                    'CandidateStepArn': 'string',
                    'CandidateStepName': 'string'
                },
            ],
            'CandidateStatus': 'Completed'|'InProgress'|'Failed'|'Stopped'|'Stopping',
            'InferenceContainers': [
                {
                    'Image': 'string',
                    'ModelDataUrl': 'string',
                    'Environment': {
                        'string': 'string'
                    }
                },
            ],
            'CreationTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1),
            'LastModifiedTime': datetime(2015, 1, 1),
            'FailureReason': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Candidates (list) --

      Summaries about the Candidates.

      • (dict) --

        An Autopilot job returns recommendations, or candidates. Each candidate has futher details about the steps involed, and the status.

        • CandidateName (string) --

          The candidate name.

        • FinalAutoMLJobObjectiveMetric (dict) --

          The best candidate result from an AutoML training job.

          • Type (string) --

            The type of metric with the best result.

          • MetricName (string) --

            The name of the metric with the best result. For a description of the possible objective metrics, see AutoMLJobObjective$MetricName.

          • Value (float) --

            The value of the metric with the best result.

        • ObjectiveStatus (string) --

          The objective status.

        • CandidateSteps (list) --

          The candidate's steps.

          • (dict) --

            Information about the steps for a Candidate, and what step it is working on.

            • CandidateStepType (string) --

              Whether the Candidate is at the transform, training, or processing step.

            • CandidateStepArn (string) --

              The ARN for the Candidate's step.

            • CandidateStepName (string) --

              The name for the Candidate's step.

        • CandidateStatus (string) --

          The candidate's status.

        • InferenceContainers (list) --

          The inference containers.

          • (dict) --

            A list of container definitions that describe the different containers that make up one AutoML candidate. Refer to ContainerDefinition for more details.

            • Image (string) --

              The ECR path of the container. Refer to ContainerDefinition for more details.

            • ModelDataUrl (string) --

              The location of the model artifacts. Refer to ContainerDefinition for more details.

            • Environment (dict) --

              Environment variables to set in the container. Refer to ContainerDefinition for more details.

              • (string) --

                • (string) --

        • CreationTime (datetime) --

          The creation time.

        • EndTime (datetime) --

          The end time.

        • LastModifiedTime (datetime) --

          The last modified time.

        • FailureReason (string) --

          The failure reason.

    • NextToken (string) --

      If the previous response was truncated, you receive this token. Use it in your next request to receive the next set of results.