HyperparameterTuner

class sagemaker.tuner.HyperparameterTuner(estimator, objective_metric_name, hyperparameter_ranges, metric_definitions=None, strategy='Bayesian', objective_type='Maximize', max_jobs=1, max_parallel_jobs=1, tags=None, base_tuning_job_name=None)

Bases: object

A class for creating and interacting with Amazon SageMaker hyperparameter tuning jobs, as well as deploying the resulting model(s).

Initialize a HyperparameterTuner. It takes an estimator to obtain configuration information for training jobs that are created as the result of a hyperparameter tuning job.

Parameters:
  • estimator (sagemaker.estimator.EstimatorBase) – An estimator object that has been initialized with the desired configuration. There does not need to be a training job associated with this instance.
  • objective_metric_name (str) – Name of the metric for evaluating training jobs.
  • hyperparameter_ranges (dict[str, sagemaker.tuner._ParameterRange]) – Dictionary of parameter ranges. These parameter ranges can be one of three types: Continuous, Integer, or Categorical. The keys of the dictionary are the names of the hyperparameter, and the values are the appropriate parameter range class to represent the range.
  • metric_definitions (list[dict]) – A list of dictionaries that defines the metric(s) used to evaluate the training jobs (default: None). Each dictionary 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.
  • strategy (str) – Strategy to be used for hyperparameter estimations (default: ‘Bayesian’).
  • 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 (default: 1).
  • max_parallel_jobs (int) – Maximum number of parallel training jobs to start (default: 1).
  • tags (list[dict]) – List of tags for labeling the tuning job (default: None). For more, see https://docs.aws.amazon.com/sagemaker/latest/dg/API_Tag.html.
  • base_tuning_job_name (str) – Prefix for the hyperparameter tuning job name when the fit() method launches. If not specified, a default job name is generaged, based on the training image name and current timestamp.
TUNING_JOB_NAME_MAX_LENGTH = 32
SAGEMAKER_ESTIMATOR_MODULE = 'sagemaker_estimator_module'
SAGEMAKER_ESTIMATOR_CLASS_NAME = 'sagemaker_estimator_class_name'
DEFAULT_ESTIMATOR_MODULE = 'sagemaker.estimator'
DEFAULT_ESTIMATOR_CLS_NAME = 'Estimator'
fit(inputs, job_name=None, include_cls_metadata=True, **kwargs)

Start a hyperparameter tuning job.

Parameters:
  • inputs –

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

    • (str) - The S3 location where training data is saved.
    • (dict[str, str] or dict[str, sagemaker.session.s3_input]) - If using multiple channels for
      training data, you can specify a dict mapping channel names to strings or s3_input() objects.
    • (sagemaker.session.s3_input) - Channel configuration for S3 data sources that can provide
      additional information about the training dataset. See sagemaker.session.s3_input() for full details.
    • (sagemaker.amazon.amazon_estimator.RecordSet) - A collection of
      Amazon :class:~`Record` objects serialized and stored in S3. For use with an estimator for an Amazon algorithm.
    • (list[sagemaker.amazon.amazon_estimator.RecordSet]) - A list of
      :class:~`sagemaker.amazon.amazon_estimator.RecordSet` objects, where each instance is a different channel of training data.
  • 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.
  • **kwargs – Other arguments needed for training. Please refer to the fit() method of the associated estimator to see what other arguments are needed.
classmethod attach(tuning_job_name, sagemaker_session=None, job_details=None, estimator_cls=None)

Attach to an existing hyperparameter tuning job.

Create a HyperparameterTuner bound to an existing hyperparameter tuning job. After attaching, if there exists a best training job (or any other completed training job), that can be deploy()``ed to create an Amazon SageMaker Endpoint and return a ``Predictor.

Parameters:
  • tuning_job_name (str) – The name of the hyperparameter tuning job to attach to.
  • sagemaker_session (sagemaker.session.Session) – Session object which manages interactions with Amazon SageMaker APIs and any other AWS services needed. If not specified, one is created using the default AWS configuration chain.
  • job_details (dict) – The response to a DescribeHyperParameterTuningJob call. If not specified, the HyperparameterTuner will perform one such call with the provided hyperparameter tuning job name.
  • estimator_cls (str) – The estimator class name associated with the training jobs, e.g. ‘sagemaker.estimator.Estimator’. If not specified, the HyperparameterTuner will try to derive the correct estimator class from training job metadata, defaulting to :class:~`sagemaker.estimator.Estimator` if it is unable to determine a more specific class.

Examples

>>> my_tuner.fit()
>>> job_name = my_tuner.latest_tuning_job.name
Later on:
>>> attached_tuner = HyperparameterTuner.attach(job_name)
>>> attached_tuner.deploy()
Returns:
A HyperparameterTuner instance with the attached hyperparameter
tuning job.
Return type:sagemaker.tuner.HyperparameterTuner
deploy(initial_instance_count, instance_type, endpoint_name=None, **kwargs)

Deploy the best trained or user specified model to an Amazon SageMaker endpoint and return a sagemaker.RealTimePredictor object.

For more information: http://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html

Parameters:
  • initial_instance_count (int) – Minimum number of EC2 instances to deploy to an endpoint for prediction.
  • instance_type (str) – Type of EC2 instance to deploy to an endpoint for prediction, for example, ‘ml.c4.xlarge’.
  • endpoint_name (str) – Name to use for creating an Amazon SageMaker endpoint. If not specified, the name of the training job is used.
  • **kwargs – Other arguments needed for deployment. Please refer to the create_model() method of the associated estimator to see what other arguments are needed.
Returns:

A predictor that provides a predict() method,

which can be used to send requests to the Amazon SageMaker endpoint and obtain inferences.
Return type:

sagemaker.predictor.RealTimePredictor
stop_tuning_job()

Stop latest running hyperparameter tuning job.

wait()

Wait for latest hyperparameter tuning job to finish.

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.
delete_endpoint(endpoint_name=None)

Delete an Amazon SageMaker endpoint.

If an endpoint name is not specified, this defaults to looking for an endpoint that shares a name with the best training job for deletion.

Parameters:endpoint_name (str) – Name of the endpoint to delete
hyperparameter_ranges()

Return the hyperparameter ranges in a dictionary to be used as part of a request for creating a hyperparameter tuning job.

sagemaker_session

**Convenience method for accessing the* – class* – ~`sagemaker.session.Session` object associated with the estimator for the HyperparameterTuner.

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.

class sagemaker.tuner.ContinuousParameter(min_value, max_value)

Bases: sagemaker.tuner._ParameterRange

A class for representing hyperparameters that have a continuous range of possible values.

Initialize a ContinuousParameter.

Parameters:
  • min_value (float) – The minimum value for the range.
  • max_value (float) – The maximum value for the range.
class sagemaker.tuner.IntegerParameter(min_value, max_value)

Bases: sagemaker.tuner._ParameterRange

A class for representing hyperparameters that have an integer range of possible values.

Initialize a IntegerParameter.

Parameters:
  • min_value (int) – The minimum value for the range.
  • max_value (int) – The maximum value for the range.
class sagemaker.tuner.CategoricalParameter(values)

Bases: sagemaker.tuner._ParameterRange

A class for representing hyperparameters that have a discrete list of possible values.

Initialize a CategoricalParameter.

Parameters:values (list or object) – The possible values for the hyperparameter. This input will be converted into a list of strings.
as_tuning_range(name)

Represent the parameter range as a dicionary suitable for a request to create an Amazon SageMaker hyperparameter tuning job.

Parameters:name (str) – The name of the hyperparameter.
Returns:A dictionary that contains the name and values of the hyperparameter.
Return type:dict[str, list[str]]
as_json_range(name)

Represent the parameter range as a dictionary suitable for a request to create an Amazon SageMaker hyperparameter tuning job using one of the deep learning frameworks.

The deep learning framework images require that hyperparameters be serialized as JSON.

Parameters:name (str) – The name of the hyperparameter.
Returns:
A dictionary that contains the name and values of the hyperparameter,
where the values are serialized as JSON.
Return type:dict[str, list[str]]