sagemaker.train.tuner

Placeholder docstring

Classes

HyperparameterTuner(model_trainer, ...[, ...])	Defines interaction with Amazon SageMaker hyperparameter tuning jobs.
WarmStartTypes(value)	An enumeration.

class sagemaker.train.tuner.HyperparameterTuner(model_trainer: ModelTrainer, objective_metric_name: str | PipelineVariable, hyperparameter_ranges: Dict[str, ParameterRange], metric_definitions: List[Dict[str, str | PipelineVariable]] | None = None, strategy: str | PipelineVariable = 'Bayesian', objective_type: str | PipelineVariable = 'Maximize', max_jobs: int | PipelineVariable = None, max_parallel_jobs: int | PipelineVariable = 1, max_runtime_in_seconds: int | PipelineVariable | None = None, tags: List[Dict[str, str | PipelineVariable]] | Dict[str, str | PipelineVariable] | None = None, base_tuning_job_name: str | None = None, warm_start_config: HyperParameterTuningJobWarmStartConfig | None = None, strategy_config: HyperParameterTuningJobStrategyConfig | None = None, completion_criteria_config: TuningJobCompletionCriteria | None = None, early_stopping_type: str | PipelineVariable = 'Off', model_trainer_name: str | None = None, random_seed: int | None = None, autotune: bool = False, hyperparameters_to_keep_static: List[str] | None = None)

Bases: object

Defines interaction with Amazon SageMaker hyperparameter tuning jobs.

It also supports deploying the resulting models.

TUNING_JOB_NAME_MAX_LENGTH = 32

analytics()

An instance of HyperparameterTuningJobAnalytics for this latest tuning job of this tuner.

Analytics olbject gives you access to tuning results summarized into a pandas dataframe.

best_training_job()

Return name of the best training job for the latest hyperparameter tuning job.

Raises:

Exception – If there is no best training job available for the hyperparameter tuning job.

classmethod create(model_trainer_dict, objective_metric_name_dict, hyperparameter_ranges_dict, metric_definitions_dict=None, base_tuning_job_name=None, strategy='Bayesian', strategy_config=None, completion_criteria_config=None, objective_type='Maximize', max_jobs=None, max_parallel_jobs=1, max_runtime_in_seconds=None, tags=None, warm_start_config=None, early_stopping_type='Off', random_seed=None, autotune=False, hyperparameters_to_keep_static_dict=None)

Factory method to create a HyperparameterTuner instance.

It takes one or more model_trainers to obtain configuration information for training jobs that are created as the result of a hyperparameter tuning job. The model_trainers are provided through a dictionary (i.e. model_trainer_dict) with unique model_trainer names as the keys. For individual model_trainers separate objective metric names and hyperparameter ranges should be provided in two dictionaries, i.e. objective_metric_name_dict and hyperparameter_ranges_dict, with the same model_trainer names as the keys. Optional metrics definitions could also be provided for individual model_trainers via another dictionary metric_definitions_dict.

Parameters:

• model_trainer_dict (dict[str, sagemaker.train.model_trainer.ModelTrainer]) – Dictionary of model_trainer instances that have been initialized with the desired configuration. There does not need to be a training job associated with the model_trainer instances. The keys of the dictionary would be referred to as “model_trainer names”.

• objective_metric_name_dict (dict[str, str]) – Dictionary of names of the objective metric for evaluating training jobs. The keys are the same set of model_trainer names as in model_trainer_dict, and there must be one entry for each model_trainer in model_trainer_dict.

• hyperparameter_ranges_dict (dict[str, dict[str, sagemaker.parameter.ParameterRange]]) – Dictionary of tunable hyperparameter ranges. The keys are the same set of model_trainer names as in model_trainer_dict, and there must be one entry for each model_trainer in model_trainer_dict. Each value is a dictionary of sagemaker.parameter.ParameterRange instance, which can be one of three types: Continuous, Integer, or Categorical. The keys of each ParameterRange dictionaries are the names of the hyperparameter, and the values are the appropriate parameter range class to represent the range.

• metric_definitions_dict (dict(str, list[dict]]) – Dictionary of metric definitions. The keys are the same set or a subset of model_trainer names as in model_trainer_dict, and there must be one entry for each model_trainer in model_trainer_dict. Each value is a list of dictionaries that defines the metric(s) used to evaluate the training jobs (default: None). Each of these dictionaries contains two keys: ‘Name’ for the name of the metric, and ‘Regex’ for the regular expression used to extract the metric from the logs. This should be defined only for hyperparameter tuning jobs that don’t use an Amazon algorithm.

• base_tuning_job_name (str) – Prefix for the hyperparameter tuning job name when the train() method launches. If not specified, a default job name is generated, based on the training image name and current timestamp.

• strategy (str or PipelineVariable) – Strategy to be used for hyperparameter estimations. More information about different strategies: https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-how-it-works.html. Available options are: ‘Bayesian’, ‘Random’, ‘Hyperband’, ‘Grid’ (default: ‘Bayesian’)

• strategy_config (dict) – The configuration for a training job launched by a hyperparameter tuning job.

• completion_criteria_config (dict) – The configuration for tuning job completion criteria.

• objective_type (str) – The type of the objective metric for evaluating training jobs. This value can be either ‘Minimize’ or ‘Maximize’ (default: ‘Maximize’).

• max_jobs (int) – Maximum total number of training jobs to start for the hyperparameter tuning job. The default value is unspecified fot the ‘Grid’ strategy and the value is 1 for all others strategies (default: None).

• max_parallel_jobs (int) – Maximum number of parallel training jobs to start (default: 1).

• max_runtime_in_seconds (int) – The maximum time in seconds that a hyperparameter tuning job can run.

• tags (Optional[Tags]) – List of tags for labeling the tuning job (default: None). For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.

• warm_start_config (sagemaker.core.shapes.HyperParameterTuningJobWarmStartConfig) – A HyperParameterTuningJobWarmStartConfig object that has been initialized with the configuration defining the nature of warm start tuning job.

• early_stopping_type (str) – Specifies whether early stopping is enabled for the job. Can be either ‘Auto’ or ‘Off’ (default: ‘Off’). If set to ‘Off’, early stopping will not be attempted. If set to ‘Auto’, early stopping of some training jobs may happen, but is not guaranteed to.

• random_seed (int) – An initial value used to initialize a pseudo-random number generator. Setting a random seed will make the hyperparameter tuning search strategies to produce more consistent configurations for the same tuning job.

• autotune (bool) – Whether the parameter ranges or other unset settings of a tuning job should be chosen automatically (default: False).

• hyperparameters_to_keep_static_dict (dict(str, list[str]]) – Dictionary of hyperparameter names that will be kept static. The keys are the same set or a subset of model_trainer names as in model_trainer_dict, and there must be one entry for each model_trainer in model_trainer_dict. Each value is a list of hyperparameter names that will be kept static and will not be assigned a tunable range with Autotune functionality (default: None).

Returns:

a new HyperparameterTuner object that can start a hyperparameter tuning job with one or more model_trainers.

Return type:

sagemaker.core.shapes.HyperparameterTuner

describe()

Returns a response from the DescribeHyperParameterTuningJob API call.

hyperparameter_ranges()

Return the hyperparameter ranges in a dictionary.

Dictionary to be used as part of a request for creating a hyperparameter tuning job.

hyperparameter_ranges_dict()

Return a dictionary of hyperparameter ranges for all model_trainers in model_trainer_dict

override_resource_config(instance_configs: List[HyperParameterTuningInstanceConfig] | Dict[str, List[HyperParameterTuningInstanceConfig]])

Override the instance configuration of the model_trainers used by the tuner.

Parameters:

instance_configs (List[HyperParameterTuningInstanceConfig] or Dict[str, List[HyperParameterTuningInstanceConfig]) – The InstanceConfigs to use as an override for the instance configuration of the model_trainer. None will remove the override.

property sagemaker_session

Convenience method for accessing the SageMaker session.

It access Session object associated with the model_trainer for the HyperparameterTuner.

stop_tuning_job()

Stop latest running hyperparameter tuning job.

transfer_learning_tuner(additional_parents=None, model_trainer=None)

Creates a new HyperparameterTuner.

Creation is done by copying the request fields from the provided parent to the new instance of HyperparameterTuner. Followed by addition of warm start configuration with the type as “TransferLearning” and parents as the union of provided list of additional_parents and the self. Also, training image in the new tuner’s model_trainer is updated with the provided training_image.

Examples

>>> parent_tuner = HyperparameterTuner.attach(tuning_job_name="parent-job-1")
>>> transfer_learning_tuner = parent_tuner.transfer_learning_tuner(
>>>                                             additional_parents={"parent-job-2"})
Later On:
>>> transfer_learning_tuner.train(inputs={})

Parameters:

• additional_parents (set{str}) – Set of additional parents along with the self to be used in warm starting

• model_trainer (sagemaker.train.model_trainer.ModelTrainer) – A ModelTrainer object that has been initialized with the desired configuration. There does not need to be a training job associated with this instance.

Returns:

HyperparameterTuner instance which can be used to launch transfer learning tuning job.

Return type:

sagemaker.core.shapes.HyperparameterTuner

tune(inputs: str | Dict[str, str] | List[Channel | InputData] | None = None, job_name: str | None = None, model_trainer_kwargs: Dict[str, dict] | None = None, wait: bool = True, **kwargs)

Start a hyperparameter tuning job.

Parameters:

• inputs –

  Information about the training data. Please refer to the train() method of the associated model_trainer, as this can take any of the following forms:

  • (str) - The S3 location where training data is saved.

  • (dict[str, str]) - If using multiple channels for training data, you can specify

    a dict mapping channel names to S3 URI strings.

  • (list[sagemaker.train.configs.Channel]) - A list of Channel objects for

    detailed input data configuration.

  • (list[sagemaker.train.configs.InputData]) - A list of InputData objects for

    simplified input data specification.

• job_name (str) – Tuning job name. If not specified, the tuner generates a default job name, based on the training image name and current timestamp.

• model_trainer_kwargs (dict[str, dict]) – Dictionary for other arguments needed for training. Should be used only for tuners created via the factory method create(). The keys are the model_trainer names for the model_trainer_dict argument of create() method. Each value is a dictionary for the other arguments needed for training of the corresponding model_trainer.

• wait (bool) – Whether the call should wait until the job completes (default: True).

• **kwargs – Other arguments needed for training. Please refer to the train() method of the associated model_trainer to see what other arguments are needed.

wait()

Wait for latest hyperparameter tuning job to finish.

class sagemaker.train.tuner.WarmStartTypes(value)

Bases: Enum

An enumeration.

IDENTICAL_DATA_AND_ALGORITHM = 'IdenticalDataAndAlgorithm'

TRANSFER_LEARNING = 'TransferLearning'