0
# Hyperparameter Tuning
1

2
Automated hyperparameter optimization with support for multiple search strategies, early stopping, and warm starting from previous tuning jobs to find optimal model configurations efficiently.
3

4
## Capabilities
5

6
### Hyperparameter Tuner
7

8
Main class for automated hyperparameter optimization that explores hyperparameter spaces to find optimal model configurations.
9

10
```python { .api }
11
class HyperparameterTuner:
12
    """
13
    SageMaker automatic hyperparameter tuning service.
14
    
15
    Parameters:
16
    - estimator (Estimator): Estimator to tune
17
    - objective_metric_name (str): Metric to optimize
18
    - objective_type (str, optional): Optimization direction ("Maximize" or "Minimize")
19
    - metric_definitions (List[dict], optional): Custom metric definitions
20
    - hyperparameter_ranges (dict): Dictionary of parameter ranges to tune
21
    - strategy (str, optional): Search strategy ("Bayesian", "Random", "Hyperband", "Grid")
22
    - strategy_config (dict, optional): Strategy-specific configuration
23
    - max_jobs (int, optional): Maximum number of training jobs
24
    - max_parallel_jobs (int, optional): Maximum parallel training jobs
25
    - early_stopping_type (str, optional): Early stopping strategy ("Off" or "Auto")
26
    - base_tuning_job_name (str, optional): Base name for tuning jobs
27
    - warm_start_config (WarmStartConfig, optional): Warm start configuration
28
    - completion_criteria (TuningJobCompletionCriteriaConfig, optional): Completion criteria
29
    - tags (List[dict], optional): Resource tags
30
    """
31
    def __init__(self, estimator: Estimator, objective_metric_name: str,
32
                 hyperparameter_ranges: dict, **kwargs): ...
33
    
34
    def fit(self, inputs=None, job_name: str = None, include_cls_metadata: bool = None,
35
            wait: bool = True, **kwargs): ...
36
    
37
    def deploy(self, initial_instance_count: int, instance_type: str,
38
               serializer: BaseSerializer = None, deserializer: BaseDeserializer = None,
39
               endpoint_name: str = None, **kwargs) -> Predictor: ...
40
    
41
    def create_model(self, name: str = None, role: str = None, 
42
                    vpc_config_override: dict = None) -> Model: ...
43
    
44
    def stop_tuning_job(self): ...
45
    
46
    def wait(self): ...
47
    
48
    def describe(self) -> dict: ...
49
    
50
    def best_training_job(self) -> dict: ...
51
    
52
    def best_estimator(self) -> Estimator: ...
53
    
54
    def transfer_learning_tuner(self, additional_parents: set = None,
55
                               estimator: Estimator = None, **kwargs) -> 'HyperparameterTuner': ...
56
    
57
    def identical_dataset_and_algorithm_tuner(self, additional_parents: set = None) -> 'HyperparameterTuner': ...
58
```
59

60
### Parameter Range Classes
61

62
Classes for defining hyperparameter search spaces with different data types and constraints.
63

64
```python { .api }
65
class IntegerParameter:
66
    """
67
    Integer hyperparameter range for tuning.
68
    
69
    Parameters:
70
    - min_value (int): Minimum value in the range
71
    - max_value (int): Maximum value in the range
72
    - scaling_type (str, optional): Scaling type ("Auto", "Linear", "Logarithmic", "ReverseLogarithmic")
73
    """
74
    def __init__(self, min_value: int, max_value: int, scaling_type: str = "Auto"): ...
75

76
class ContinuousParameter:
77
    """
78
    Continuous (float) hyperparameter range for tuning.
79
    
80
    Parameters:
81
    - min_value (float): Minimum value in the range
82
    - max_value (float): Maximum value in the range  
83
    - scaling_type (str, optional): Scaling type ("Auto", "Linear", "Logarithmic", "ReverseLogarithmic")
84
    """
85
    def __init__(self, min_value: float, max_value: float, scaling_type: str = "Auto"): ...
86

87
class CategoricalParameter:
88
    """
89
    Categorical hyperparameter with discrete values for tuning.
90
    
91
    Parameters:
92
    - values (List[str]): List of possible categorical values
93
    """
94
    def __init__(self, values: List[str]): ...
95
```
96

97
### Warm Start Configuration
98

99
Configuration for initializing tuning jobs with knowledge from previous tuning runs to accelerate optimization.
100

101
```python { .api }
102
class WarmStartConfig:
103
    """
104
    Configuration for warm starting hyperparameter tuning jobs.
105
    
106
    Parameters:
107
    - type (WarmStartTypes): Type of warm start
108
    - parents (set): Set of parent tuning job names or ARNs
109
    """
110
    def __init__(self, type: 'WarmStartTypes', parents: set): ...
111

112
class WarmStartTypes:
113
    """
114
    Enumeration of warm start types for hyperparameter tuning.
115
    
116
    Values:
117
    - IdenticalDataAndAlgorithm: Same dataset and algorithm
118
    - TransferLearning: Different dataset, same algorithm
119
    """
120
    IdenticalDataAndAlgorithm = "IdenticalDataAndAlgorithm"
121
    TransferLearning = "TransferLearning"
122
```
123

124
### Strategy Configuration
125

126
Advanced configuration options for different hyperparameter search strategies.
127

128
```python { .api }
129
class HyperbandStrategyConfig:
130
    """
131
    Configuration for Hyperband optimization strategy.
132
    
133
    Parameters:
134
    - min_resource (int, optional): Minimum resource units
135
    - max_resource (int, optional): Maximum resource units
136
    """
137
    def __init__(self, min_resource: int = None, max_resource: int = None): ...
138

139
class StrategyConfig:
140
    """
141
    General strategy configuration for hyperparameter tuning.
142
    
143
    Parameters:
144
    - hyperband_strategy_config (HyperbandStrategyConfig, optional): Hyperband configuration
145
    """
146
    def __init__(self, hyperband_strategy_config: HyperbandStrategyConfig = None): ...
147
```
148

149
### Completion Criteria
150

151
Configuration for automatic stopping criteria based on convergence or resource limits.
152

153
```python { .api }
154
class TuningJobCompletionCriteriaConfig:
155
    """
156
    Completion criteria for hyperparameter tuning jobs.
157
    
158
    Parameters:
159
    - target_objective_metric_value (float, optional): Target metric value for early stopping
160
    - best_objective_not_improving (BestObjectiveNotImproving, optional): Non-improvement stopping
161
    - convergence_detected (ConvergenceDetected, optional): Convergence detection settings
162
    """
163
    def __init__(self, target_objective_metric_value: float = None, **kwargs): ...
164

165
class BestObjectiveNotImproving:
166
    """
167
    Early stopping when best objective stops improving.
168
    
169
    Parameters:
170
    - max_number_of_training_jobs_not_improving (int): Max jobs without improvement
171
    """
172
    def __init__(self, max_number_of_training_jobs_not_improving: int): ...
173

174
class ConvergenceDetected:
175
    """
176
    Early stopping based on convergence detection.
177
    
178
    Parameters:
179
    - complete_on_convergence (str): Action on convergence ("Disabled" or "Enabled")
180
    """
181
    def __init__(self, complete_on_convergence: str = "Disabled"): ...
182
```
183

184
### Analytics and Monitoring
185

186
Classes for analyzing tuning job progress and results.
187

188
```python { .api }
189
class HyperparameterTuningJobAnalytics:
190
    """
191
    Analytics for hyperparameter tuning job results and progress.
192
    
193
    Parameters:
194
    - hyperparameter_tuning_job_name (str): Name of the tuning job
195
    - sagemaker_session (Session, optional): SageMaker session
196
    """
197
    def __init__(self, hyperparameter_tuning_job_name: str, **kwargs): ...
198
    
199
    def dataframe(self, force_refresh: bool = False) -> 'DataFrame': ...
200
    
201
    def export_csv(self, filename: str, force_refresh: bool = False): ...
202
```
203

204
## Usage Examples
205

206
### Basic Hyperparameter Tuning
207

208
```python
209
from sagemaker.tuner import HyperparameterTuner, IntegerParameter, ContinuousParameter, CategoricalParameter
210
from sagemaker.sklearn import SKLearn
211

212
# Create estimator
213
sklearn_estimator = SKLearn(
214
    entry_point="train.py",
215
    framework_version="1.2-1",
216
    instance_type="ml.m5.large",
217
    role=role
218
)
219

220
# Define hyperparameter ranges
221
hyperparameter_ranges = {
222
    'n_estimators': IntegerParameter(10, 200),
223
    'max_depth': IntegerParameter(3, 10),
224
    'learning_rate': ContinuousParameter(0.01, 1.0, scaling_type="Logarithmic"),
225
    'algorithm': CategoricalParameter(['gbtree', 'gblinear', 'dart'])
226
}
227

228
# Create hyperparameter tuner
229
tuner = HyperparameterTuner(
230
    estimator=sklearn_estimator,
231
    objective_metric_name='validation:rmse',
232
    objective_type='Minimize',
233
    hyperparameter_ranges=hyperparameter_ranges,
234
    max_jobs=50,
235
    max_parallel_jobs=3,
236
    strategy='Bayesian',
237
    early_stopping_type='Auto'
238
)
239

240
# Start tuning
241
tuner.fit({"training": "s3://bucket/train", "validation": "s3://bucket/val"})
242

243
# Get best training job
244
best_job = tuner.best_training_job()
245
print(f"Best job: {best_job['TrainingJobName']}")
246
print(f"Best metric: {best_job['FinalMetricDataList'][0]['Value']}")
247

248
# Deploy best model
249
predictor = tuner.deploy(
250
    initial_instance_count=1,
251
    instance_type="ml.m5.large"
252
)
253
```
254

255
### Advanced Tuning with Warm Start
256

257
```python
258
from sagemaker.tuner import WarmStartConfig, WarmStartTypes
259

260
# First tuning job
261
initial_tuner = HyperparameterTuner(
262
    estimator=estimator,
263
    objective_metric_name='validation:accuracy',
264
    objective_type='Maximize',
265
    hyperparameter_ranges=hyperparameter_ranges,
266
    max_jobs=25,
267
    max_parallel_jobs=3
268
)
269

270
initial_tuner.fit(inputs)
271
initial_tuner.wait()
272

273
# Warm start configuration
274
warm_start_config = WarmStartConfig(
275
    type=WarmStartTypes.TransferLearning,
276
    parents={initial_tuner.latest_tuning_job.job_name}
277
)
278

279
# Second tuning job with warm start
280
transfer_tuner = HyperparameterTuner(
281
    estimator=new_estimator,  # Different dataset
282
    objective_metric_name='validation:accuracy',
283
    objective_type='Maximize',
284
    hyperparameter_ranges=updated_ranges,
285
    max_jobs=25,
286
    max_parallel_jobs=3,
287
    warm_start_config=warm_start_config
288
)
289

290
transfer_tuner.fit(new_inputs)
291
```
292

293
### Early Stopping and Completion Criteria
294

295
```python
296
from sagemaker.tuner import TuningJobCompletionCriteriaConfig, BestObjectiveNotImproving
297

298
# Configure early stopping
299
completion_criteria = TuningJobCompletionCriteriaConfig(
300
    target_objective_metric_value=0.95,  # Stop when accuracy reaches 95%
301
    best_objective_not_improving=BestObjectiveNotImproving(
302
        max_number_of_training_jobs_not_improving=10
303
    )
304
)
305

306
# Create tuner with early stopping
307
tuner = HyperparameterTuner(
308
    estimator=estimator,
309
    objective_metric_name='validation:accuracy',
310
    objective_type='Maximize',
311
    hyperparameter_ranges=hyperparameter_ranges,
312
    max_jobs=100,
313
    max_parallel_jobs=5,
314
    completion_criteria=completion_criteria
315
)
316

317
tuner.fit(inputs)
318
```