hyper_parameter_tuning_jobs

Creates, updates, deletes, gets or lists a hyper_parameter_tuning_jobs resource.

Overview

Name	hyper_parameter_tuning_jobs
Type	Resource
Id	aws.sagemaker.hyper_parameter_tuning_jobs

Fields

The following fields are returned by SELECT queries:

describe_hyper_parameter_tuning_job

Name	Datatype	Description
autotune	object	A flag to indicate if autotune is enabled for the hyperparameter tuning job.
best_training_job	object	A TrainingJobSummary object that describes the training job that completed with the best current HyperParameterTuningJobObjective.
consumed_resources	object	The total resources consumed by your hyperparameter tuning job.
creation_time	string (date-time)	The date and time that the tuning job started.
failure_reason	string	If the tuning job failed, the reason it failed.
hyper_parameter_tuning_end_time	string (date-time)	The date and time that the tuning job ended.
hyper_parameter_tuning_job_arn	string	The Amazon Resource Name (ARN) of the tuning job. (pattern: <code>arn:aws[a-z-]:sagemaker:[a-z0-9-]:[0-9]{12}:hyper-parameter-tuning-job/.*</code>)
hyper_parameter_tuning_job_config	object	The HyperParameterTuningJobConfig object that specifies the configuration of the tuning job.
hyper_parameter_tuning_job_name	string	The name of the hyperparameter tuning job. (pattern: <code>[a-zA-Z0-9](-*[a-zA-Z0-9]){0,31}</code>)
hyper_parameter_tuning_job_status	string	The status of the tuning job. (Completed, InProgress, Failed, Stopped, Stopping, Deleting, DeleteFailed)
last_modified_time	string (date-time)	The date and time that the status of the tuning job was modified.
objective_status_counters	object	The ObjectiveStatusCounters object that specifies the number of training jobs, categorized by the status of their final objective metric, that this tuning job launched.
overall_best_training_job	object	If the hyperparameter tuning job is an warm start tuning job with a WarmStartType of IDENTICAL_DATA_AND_ALGORITHM, this is the TrainingJobSummary for the training job with the best objective metric value of all training jobs launched by this tuning job and all parent jobs specified for the warm start tuning job.
training_job_definition	object	Defines the training jobs launched by a hyperparameter tuning job.
training_job_definitions	array	A list of the HyperParameterTrainingJobDefinition objects launched for this tuning job.
training_job_status_counters	object	The TrainingJobStatusCounters object that specifies the number of training jobs, categorized by status, that this tuning job launched.
tuning_job_completion_details	object	Tuning job completion information returned as the response from a hyperparameter tuning job. This information tells if your tuning job has or has not converged. It also includes the number of training jobs that have not improved model performance as evaluated against the objective function.
warm_start_config	object	The configuration for starting the hyperparameter parameter tuning job using one or more previous tuning jobs as a starting point. The results of previous tuning jobs are used to inform which combinations of hyperparameters to search over in the new tuning job.

list_hyper_parameter_tuning_jobs

Name	Datatype	Description
creation_time	string (date-time)	The date and time that the tuning job was created.
hyper_parameter_tuning_end_time	string (date-time)	The date and time that the tuning job ended.
hyper_parameter_tuning_job_arn	string	The Amazon Resource Name (ARN) of the tuning job. (pattern: <code>arn:aws[a-z-]:sagemaker:[a-z0-9-]:[0-9]{12}:hyper-parameter-tuning-job/.*</code>)
hyper_parameter_tuning_job_name	string	The name of the tuning job. (pattern: <code>[a-zA-Z0-9](-*[a-zA-Z0-9]){0,31}</code>)
hyper_parameter_tuning_job_status	string	The status of the tuning job. (Completed, InProgress, Failed, Stopped, Stopping, Deleting, DeleteFailed)
last_modified_time	string (date-time)	The date and time that the tuning job was modified.
objective_status_counters	object	The ObjectiveStatusCounters object that specifies the numbers of training jobs, categorized by objective metric status, that this tuning job launched.
resource_limits	object	The ResourceLimits object that specifies the maximum number of training jobs and parallel training jobs allowed for this tuning job.
strategy	string	Specifies the search strategy hyperparameter tuning uses to choose which hyperparameters to evaluate at each iteration. (Bayesian, Random, Hyperband, Grid)
training_job_status_counters	object	The TrainingJobStatusCounters object that specifies the numbers of training jobs, categorized by status, that this tuning job launched.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_hyper_parameter_tuning_job	select	region		Returns a description of a hyperparameter tuning job, depending on the fields selected. These fields can include the name, Amazon Resource Name (ARN), job status of your tuning job and more.
list_hyper_parameter_tuning_jobs	select	region		Gets a list of HyperParameterTuningJobSummary objects that describe the hyperparameter tuning jobs launched in your account.
create_hyper_parameter_tuning_job	insert	region, HyperParameterTuningJobName, HyperParameterTuningJobConfig		Starts a hyperparameter tuning job. A hyperparameter tuning job finds the best version of a model by running many training jobs on your dataset using the algorithm you choose and values for hyperparameters within ranges that you specify. It then chooses the hyperparameter values that result in a model that performs the best, as measured by an objective metric that you choose. A hyperparameter tuning job automatically creates Amazon SageMaker experiments, trials, and trial components for each training job that it runs. You can view these entities in Amazon SageMaker Studio. For more information, see View Experiments, Trials, and Trial Components. Do not include any security-sensitive information including account access IDs, secrets, or tokens in any hyperparameter fields. As part of the shared responsibility model, you are responsible for any potential exposure, unauthorized access, or compromise of your sensitive data if caused by any security-sensitive information included in the request hyperparameter variable or plain text fields..
delete_hyper_parameter_tuning_job	delete	region		Deletes a hyperparameter tuning job. The DeleteHyperParameterTuningJob API deletes only the tuning job entry that was created in SageMaker when you called the CreateHyperParameterTuningJob API. It does not delete training jobs, artifacts, or the IAM role that you specified when creating the model.
stop_hyper_parameter_tuning_job	exec	region, HyperParameterTuningJobName		Stops a running hyperparameter tuning job and all running training jobs that the tuning job launched. All model artifacts output from the training jobs are stored in Amazon Simple Storage Service (Amazon S3). All data that the training jobs write to Amazon CloudWatch Logs are still available in CloudWatch. After the tuning job moves to the Stopped state, it releases all reserved resources for the tuning job.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_hyper_parameter_tuning_job

Returns a description of a hyperparameter tuning job, depending on the fields selected. These fields can include the name, Amazon Resource Name (ARN), job status of your tuning job and more.

SELECT
autotune,
best_training_job,
consumed_resources,
creation_time,
failure_reason,
hyper_parameter_tuning_end_time,
hyper_parameter_tuning_job_arn,
hyper_parameter_tuning_job_config,
hyper_parameter_tuning_job_name,
hyper_parameter_tuning_job_status,
last_modified_time,
objective_status_counters,
overall_best_training_job,
training_job_definition,
training_job_definitions,
training_job_status_counters,
tuning_job_completion_details,
warm_start_config
FROM aws.sagemaker.hyper_parameter_tuning_jobs
WHERE region = '{{ region }}' -- required
;

list_hyper_parameter_tuning_jobs

Gets a list of HyperParameterTuningJobSummary objects that describe the hyperparameter tuning jobs launched in your account.

SELECT
creation_time,
hyper_parameter_tuning_end_time,
hyper_parameter_tuning_job_arn,
hyper_parameter_tuning_job_name,
hyper_parameter_tuning_job_status,
last_modified_time,
objective_status_counters,
resource_limits,
strategy,
training_job_status_counters
FROM aws.sagemaker.hyper_parameter_tuning_jobs
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_hyper_parameter_tuning_job

Starts a hyperparameter tuning job. A hyperparameter tuning job finds the best version of a model by running many training jobs on your dataset using the algorithm you choose and values for hyperparameters within ranges that you specify. It then chooses the hyperparameter values that result in a model that performs the best, as measured by an objective metric that you choose. A hyperparameter tuning job automatically creates Amazon SageMaker experiments, trials, and trial components for each training job that it runs. You can view these entities in Amazon SageMaker Studio. For more information, see View Experiments, Trials, and Trial Components. Do not include any security-sensitive information including account access IDs, secrets, or tokens in any hyperparameter fields. As part of the shared responsibility model, you are responsible for any potential exposure, unauthorized access, or compromise of your sensitive data if caused by any security-sensitive information included in the request hyperparameter variable or plain text fields..

INSERT INTO aws.sagemaker.hyper_parameter_tuning_jobs (
HyperParameterTuningJobName,
HyperParameterTuningJobConfig,
TrainingJobDefinition,
TrainingJobDefinitions,
WarmStartConfig,
Tags,
Autotune,
region
)
SELECT 
'{{ HyperParameterTuningJobName }}' /* required */,
'{{ HyperParameterTuningJobConfig }}' /* required */,
'{{ TrainingJobDefinition }}',
'{{ TrainingJobDefinitions }}',
'{{ WarmStartConfig }}',
'{{ Tags }}',
'{{ Autotune }}',
'{{ region }}'
RETURNING
hyper_parameter_tuning_job_arn
;

Manifest

# Description fields are for documentation purposes
- name: hyper_parameter_tuning_jobs
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the hyper_parameter_tuning_jobs resource.
  - name: HyperParameterTuningJobName
    value: "{{ HyperParameterTuningJobName }}"
    description: |
      The name of the tuning job. This name is the prefix for the names of all training jobs that this tuning job launches. The name must be unique within the same Amazon Web Services account and Amazon Web Services Region. The name must have 1 to 32 characters. Valid characters are a-z, A-Z, 0-9, and : + = @ _ % - (hyphen). The name is not case sensitive.
  - name: HyperParameterTuningJobConfig
    description: |
      The HyperParameterTuningJobConfig object that describes the tuning job, including the search strategy, the objective metric used to evaluate training jobs, ranges of parameters to search, and resource limits for the tuning job. For more information, see How Hyperparameter Tuning Works.
    value:
      Strategy: "{{ Strategy }}"
      StrategyConfig:
        HyperbandStrategyConfig:
          MinResource: {{ MinResource }}
          MaxResource: {{ MaxResource }}
      HyperParameterTuningJobObjective:
        Type: "{{ Type }}"
        MetricName: "{{ MetricName }}"
      ResourceLimits:
        MaxNumberOfTrainingJobs: {{ MaxNumberOfTrainingJobs }}
        MaxParallelTrainingJobs: {{ MaxParallelTrainingJobs }}
        MaxRuntimeInSeconds: {{ MaxRuntimeInSeconds }}
      ParameterRanges:
        IntegerParameterRanges:
          - Name: "{{ Name }}"
            MinValue: "{{ MinValue }}"
            MaxValue: "{{ MaxValue }}"
            ScalingType: "{{ ScalingType }}"
        ContinuousParameterRanges:
          - Name: "{{ Name }}"
            MinValue: "{{ MinValue }}"
            MaxValue: "{{ MaxValue }}"
            ScalingType: "{{ ScalingType }}"
        CategoricalParameterRanges:
          - Name: "{{ Name }}"
            Values: "{{ Values }}"
        AutoParameters:
          - Name: "{{ Name }}"
            ValueHint: "{{ ValueHint }}"
      TrainingJobEarlyStoppingType: "{{ TrainingJobEarlyStoppingType }}"
      TuningJobCompletionCriteria:
        TargetObjectiveMetricValue: {{ TargetObjectiveMetricValue }}
        BestObjectiveNotImproving:
          MaxNumberOfTrainingJobsNotImproving: {{ MaxNumberOfTrainingJobsNotImproving }}
        ConvergenceDetected:
          CompleteOnConvergence: "{{ CompleteOnConvergence }}"
      RandomSeed: {{ RandomSeed }}
  - name: TrainingJobDefinition
    description: |
      The HyperParameterTrainingJobDefinition object that describes the training jobs that this tuning job launches, including static hyperparameters, input data configuration, output data configuration, resource configuration, and stopping condition.
    value:
      DefinitionName: "{{ DefinitionName }}"
      TuningObjective:
        Type: "{{ Type }}"
        MetricName: "{{ MetricName }}"
      HyperParameterRanges:
        IntegerParameterRanges:
          - Name: "{{ Name }}"
            MinValue: "{{ MinValue }}"
            MaxValue: "{{ MaxValue }}"
            ScalingType: "{{ ScalingType }}"
        ContinuousParameterRanges:
          - Name: "{{ Name }}"
            MinValue: "{{ MinValue }}"
            MaxValue: "{{ MaxValue }}"
            ScalingType: "{{ ScalingType }}"
        CategoricalParameterRanges:
          - Name: "{{ Name }}"
            Values: "{{ Values }}"
        AutoParameters:
          - Name: "{{ Name }}"
            ValueHint: "{{ ValueHint }}"
      StaticHyperParameters: "{{ StaticHyperParameters }}"
      AlgorithmSpecification:
        TrainingImage: "{{ TrainingImage }}"
        TrainingInputMode: "{{ TrainingInputMode }}"
        AlgorithmName: "{{ AlgorithmName }}"
        MetricDefinitions:
          - Name: "{{ Name }}"
            Regex: "{{ Regex }}"
      RoleArn: "{{ RoleArn }}"
      InputDataConfig:
        - ChannelName: "{{ ChannelName }}"
          DataSource:
            S3DataSource:
              S3DataType: "{{ S3DataType }}"
              S3Uri: "{{ S3Uri }}"
              S3DataDistributionType: "{{ S3DataDistributionType }}"
              AttributeNames:
                - "{{ AttributeNames }}"
              InstanceGroupNames:
                - "{{ InstanceGroupNames }}"
              ModelAccessConfig:
                AcceptEula: {{ AcceptEula }}
              HubAccessConfig:
                HubContentArn: "{{ HubContentArn }}"
            FileSystemDataSource:
              FileSystemId: "{{ FileSystemId }}"
              FileSystemAccessMode: "{{ FileSystemAccessMode }}"
              FileSystemType: "{{ FileSystemType }}"
              DirectoryPath: "{{ DirectoryPath }}"
            DatasetSource:
              DatasetArn: "{{ DatasetArn }}"
          ContentType: "{{ ContentType }}"
          CompressionType: "{{ CompressionType }}"
          RecordWrapperType: "{{ RecordWrapperType }}"
          InputMode: "{{ InputMode }}"
          ShuffleConfig:
            Seed: {{ Seed }}
      VpcConfig:
        SecurityGroupIds:
          - "{{ SecurityGroupIds }}"
        Subnets:
          - "{{ Subnets }}"
      OutputDataConfig:
        KmsKeyId: "{{ KmsKeyId }}"
        S3OutputPath: "{{ S3OutputPath }}"
        CompressionType: "{{ CompressionType }}"
      ResourceConfig:
        InstanceType: "{{ InstanceType }}"
        InstanceCount: {{ InstanceCount }}
        VolumeSizeInGB: {{ VolumeSizeInGB }}
        VolumeKmsKeyId: "{{ VolumeKmsKeyId }}"
        KeepAlivePeriodInSeconds: {{ KeepAlivePeriodInSeconds }}
        InstanceGroups:
          - InstanceType: "{{ InstanceType }}"
            InstanceCount: {{ InstanceCount }}
            InstanceGroupName: "{{ InstanceGroupName }}"
        TrainingPlanArn: "{{ TrainingPlanArn }}"
        InstancePlacementConfig:
          EnableMultipleJobs: {{ EnableMultipleJobs }}
          PlacementSpecifications:
            - UltraServerId: "{{ UltraServerId }}"
              InstanceCount: {{ InstanceCount }}
      HyperParameterTuningResourceConfig:
        InstanceType: "{{ InstanceType }}"
        InstanceCount: {{ InstanceCount }}
        VolumeSizeInGB: {{ VolumeSizeInGB }}
        VolumeKmsKeyId: "{{ VolumeKmsKeyId }}"
        AllocationStrategy: "{{ AllocationStrategy }}"
        InstanceConfigs:
          - InstanceType: "{{ InstanceType }}"
            InstanceCount: {{ InstanceCount }}
            VolumeSizeInGB: {{ VolumeSizeInGB }}
      StoppingCondition:
        MaxRuntimeInSeconds: {{ MaxRuntimeInSeconds }}
        MaxWaitTimeInSeconds: {{ MaxWaitTimeInSeconds }}
        MaxPendingTimeInSeconds: {{ MaxPendingTimeInSeconds }}
      EnableNetworkIsolation: {{ EnableNetworkIsolation }}
      EnableInterContainerTrafficEncryption: {{ EnableInterContainerTrafficEncryption }}
      EnableManagedSpotTraining: {{ EnableManagedSpotTraining }}
      CheckpointConfig:
        S3Uri: "{{ S3Uri }}"
        LocalPath: "{{ LocalPath }}"
      RetryStrategy:
        MaximumRetryAttempts: {{ MaximumRetryAttempts }}
      Environment: "{{ Environment }}"
  - name: TrainingJobDefinitions
    description: |
      A list of the HyperParameterTrainingJobDefinition objects launched for this tuning job.
    value:
      - DefinitionName: "{{ DefinitionName }}"
        TuningObjective:
          Type: "{{ Type }}"
          MetricName: "{{ MetricName }}"
        HyperParameterRanges:
          IntegerParameterRanges:
            - Name: "{{ Name }}"
              MinValue: "{{ MinValue }}"
              MaxValue: "{{ MaxValue }}"
              ScalingType: "{{ ScalingType }}"
          ContinuousParameterRanges:
            - Name: "{{ Name }}"
              MinValue: "{{ MinValue }}"
              MaxValue: "{{ MaxValue }}"
              ScalingType: "{{ ScalingType }}"
          CategoricalParameterRanges:
            - Name: "{{ Name }}"
              Values: "{{ Values }}"
          AutoParameters:
            - Name: "{{ Name }}"
              ValueHint: "{{ ValueHint }}"
        StaticHyperParameters: "{{ StaticHyperParameters }}"
        AlgorithmSpecification:
          TrainingImage: "{{ TrainingImage }}"
          TrainingInputMode: "{{ TrainingInputMode }}"
          AlgorithmName: "{{ AlgorithmName }}"
          MetricDefinitions:
            - Name: "{{ Name }}"
              Regex: "{{ Regex }}"
        RoleArn: "{{ RoleArn }}"
        InputDataConfig: "{{ InputDataConfig }}"
        VpcConfig:
          SecurityGroupIds:
            - "{{ SecurityGroupIds }}"
          Subnets:
            - "{{ Subnets }}"
        OutputDataConfig:
          KmsKeyId: "{{ KmsKeyId }}"
          S3OutputPath: "{{ S3OutputPath }}"
          CompressionType: "{{ CompressionType }}"
        ResourceConfig:
          InstanceType: "{{ InstanceType }}"
          InstanceCount: {{ InstanceCount }}
          VolumeSizeInGB: {{ VolumeSizeInGB }}
          VolumeKmsKeyId: "{{ VolumeKmsKeyId }}"
          KeepAlivePeriodInSeconds: {{ KeepAlivePeriodInSeconds }}
          InstanceGroups:
            - InstanceType: "{{ InstanceType }}"
              InstanceCount: {{ InstanceCount }}
              InstanceGroupName: "{{ InstanceGroupName }}"
          TrainingPlanArn: "{{ TrainingPlanArn }}"
          InstancePlacementConfig:
            EnableMultipleJobs: {{ EnableMultipleJobs }}
            PlacementSpecifications:
              - UltraServerId: "{{ UltraServerId }}"
                InstanceCount: {{ InstanceCount }}
        HyperParameterTuningResourceConfig:
          InstanceType: "{{ InstanceType }}"
          InstanceCount: {{ InstanceCount }}
          VolumeSizeInGB: {{ VolumeSizeInGB }}
          VolumeKmsKeyId: "{{ VolumeKmsKeyId }}"
          AllocationStrategy: "{{ AllocationStrategy }}"
          InstanceConfigs:
            - InstanceType: "{{ InstanceType }}"
              InstanceCount: {{ InstanceCount }}
              VolumeSizeInGB: {{ VolumeSizeInGB }}
        StoppingCondition:
          MaxRuntimeInSeconds: {{ MaxRuntimeInSeconds }}
          MaxWaitTimeInSeconds: {{ MaxWaitTimeInSeconds }}
          MaxPendingTimeInSeconds: {{ MaxPendingTimeInSeconds }}
        EnableNetworkIsolation: {{ EnableNetworkIsolation }}
        EnableInterContainerTrafficEncryption: {{ EnableInterContainerTrafficEncryption }}
        EnableManagedSpotTraining: {{ EnableManagedSpotTraining }}
        CheckpointConfig:
          S3Uri: "{{ S3Uri }}"
          LocalPath: "{{ LocalPath }}"
        RetryStrategy:
          MaximumRetryAttempts: {{ MaximumRetryAttempts }}
        Environment: "{{ Environment }}"
  - name: WarmStartConfig
    description: |
      Specifies the configuration for starting the hyperparameter tuning job using one or more previous tuning jobs as a starting point. The results of previous tuning jobs are used to inform which combinations of hyperparameters to search over in the new tuning job. All training jobs launched by the new hyperparameter tuning job are evaluated by using the objective metric. If you specify IDENTICAL_DATA_AND_ALGORITHM as the WarmStartType value for the warm start configuration, the training job that performs the best in the new tuning job is compared to the best training jobs from the parent tuning jobs. From these, the training job that performs the best as measured by the objective metric is returned as the overall best training job. All training jobs launched by parent hyperparameter tuning jobs and the new hyperparameter tuning jobs count against the limit of training jobs for the tuning job.
    value:
      ParentHyperParameterTuningJobs:
        - HyperParameterTuningJobName: "{{ HyperParameterTuningJobName }}"
      WarmStartType: "{{ WarmStartType }}"
  - name: Tags
    description: |
      An array of key-value pairs. You can use tags to categorize your Amazon Web Services resources in different ways, for example, by purpose, owner, or environment. For more information, see Tagging Amazon Web Services Resources. Tags that you specify for the tuning job are also added to all training jobs that the tuning job launches.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: Autotune
    description: |
      Configures SageMaker Automatic model tuning (AMT) to automatically find optimal parameters for the following fields: ParameterRanges: The names and ranges of parameters that a hyperparameter tuning job can optimize. ResourceLimits: The maximum resources that can be used for a training job. These resources include the maximum number of training jobs, the maximum runtime of a tuning job, and the maximum number of training jobs to run at the same time. TrainingJobEarlyStoppingType: A flag that specifies whether or not to use early stopping for training jobs launched by a hyperparameter tuning job. RetryStrategy: The number of times to retry a training job. Strategy: Specifies how hyperparameter tuning chooses the combinations of hyperparameter values to use for the training jobs that it launches. ConvergenceDetected: A flag to indicate that Automatic model tuning (AMT) has detected model convergence.
    value:
      Mode: "{{ Mode }}"

DELETE examples

delete_hyper_parameter_tuning_job

Deletes a hyperparameter tuning job. The DeleteHyperParameterTuningJob API deletes only the tuning job entry that was created in SageMaker when you called the CreateHyperParameterTuningJob API. It does not delete training jobs, artifacts, or the IAM role that you specified when creating the model.

DELETE FROM aws.sagemaker.hyper_parameter_tuning_jobs
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

stop_hyper_parameter_tuning_job

Stops a running hyperparameter tuning job and all running training jobs that the tuning job launched. All model artifacts output from the training jobs are stored in Amazon Simple Storage Service (Amazon S3). All data that the training jobs write to Amazon CloudWatch Logs are still available in CloudWatch. After the tuning job moves to the Stopped state, it releases all reserved resources for the tuning job.

EXEC aws.sagemaker.hyper_parameter_tuning_jobs.stop_hyper_parameter_tuning_job 
@region='{{ region }}' --required 
@@json=
'{
"HyperParameterTuningJobName": "{{ HyperParameterTuningJobName }}"
}'
;