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.
- inputs –
-
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, theHyperparameterTuner
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:
-
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:
-
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:
-
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]]
-