10.2 Hyperparameter Tuning on Agent Platform
Key Takeaways
- A hyperparameter tuning job runs trials of your training code with different values and optimizes a numeric metric that the code reports with the cloudml-hypertune package.
- If no search algorithm is specified, Agent Platform uses Bayesian optimization, choosing among Gaussian process bandits, linear combination search, or their variants.
- GRID_SEARCH requires every parameter to be INTEGER, CATEGORICAL, or DISCRETE; RANDOM_SEARCH samples the feasible space randomly.
- UNIT_LOG_SCALE suits hyperparameters that span orders of magnitude, such as learning rate, and requires a strictly positive range.
- Tuning cost depends on trial duration, and more parallel trials finish sooner but give the Bayesian algorithm fewer completed results to learn from.
The exam guide lists hyperparameter tuning in Section 3.2. Expect questions about setting up an Agent Platform tuning job correctly, picking search algorithms and scales, balancing parallelism against efficiency, and recognizing when BigQuery ML or AutoML already handle tuning.
Parameters vs. Hyperparameters
- Model parameters (weights, split thresholds) are learned during training.
- Hyperparameters (learning rate, tree depth, number of layers, dropout, batch size) govern training and stay fixed within a run. They're tuned by running whole training jobs and comparing a metric.
Each tuned hyperparameter adds to the search space and the number of trials needed, so tune only the ones that matter most.
How an Agent Platform Hyperparameter Tuning Job Works
- You write training code that accepts each tuned hyperparameter as a command-line argument with a matching name.
- You define a study spec: the metric (name and goal, MAXIMIZE or MINIMIZE), the parameters and their ranges, and optionally the algorithm.
- You define the trial job spec: worker pools, machine type, and container, just like a CustomJob.
- Agent Platform runs trials, passing different values as arguments. Your code trains, evaluates on validation data, and reports the metric:
import hypertune
hpt = hypertune.HyperTune()
hpt.report_hyperparameter_tuning_metric(
hyperparameter_metric_tag="val_auc_pr",
metric_value=val_auc_pr,
global_step=epoch)
- The service uses finished trials to choose better values for the next ones. At the end, you get every trial's values and metrics, plus the best configuration.
Job-level settings
| Setting | Meaning | Guidance |
|---|---|---|
maxTrialCount | Total trials | Enough to explore. Cost scales with trial duration × count |
parallelTrialCount | Trials running at once | More parallel = faster wall-clock time, but the Bayesian search gets less feedback before choosing new values |
maxFailedTrialCount | Failures allowed before the job fails | Catch systematic errors early |
Parameter Types and Scaling
| Type | Values |
|---|---|
DOUBLE | minValue to maxValue (floating point) |
INTEGER | minValue to maxValue (integers) |
CATEGORICAL | List of strings, such as optimizer names |
DISCRETE | Ascending list of specific numbers, such as batch sizes 32, 64, or 128 |
| Scale type | Use when |
|---|---|
UNIT_LINEAR_SCALE | Values matter evenly across the range, like dropout from 0.1 to 0.5 |
UNIT_LOG_SCALE | Values span orders of magnitude, like learning rate from 1e-5 to 1e-1. The range must be strictly positive |
UNIT_REVERSE_LOG_SCALE | You want more resolution near the top of the range, like momentum near 1.0. Strictly positive |
Conditional hyperparameters
A ConditionalParameterSpec adds a hyperparameter only when a parent parameter matches a value. For example, num_hidden_layers is added only when training_method = DNN. You can also give linear regression and the DNN separate learning-rate parameters, so what the search learns about one method doesn't mislead the other.
Search Algorithms
| Algorithm | Behavior | Choose when |
|---|---|---|
Default (ALGORITHM_UNSPECIFIED) | Bayesian optimization. Agent Platform picks among Gaussian process bandits, linear combination search, or variants | Most tuning jobs. Efficient use of expensive trials |
GRID_SEARCH | Tries points on a grid. Every parameter must be INTEGER, CATEGORICAL, or DISCRETE | Small, discrete spaces, or when you ask for more trials than there are grid points (the default algorithm might then repeat suggestions) |
RANDOM_SEARCH | Samples randomly | Simple baselines, highly parallel runs where adaptive feedback matters less |
Agent Platform can also improve across related tuning jobs, such as reruns that change only the objective or add a column.
Agent Platform Vizier
Vizier is the black-box optimization service behind tuning, and you can use it directly. It optimizes any system with configurable parameters when each evaluation is expensive, even outside ML. Examples include tuning a recommendation system's business rules, or testing button colors and font sizes on a website.
Tuning Elsewhere on Google Cloud
| Product | Built-in tuning |
|---|---|
| BigQuery ML | NUM_TRIALS, MAX_PARALLEL_TRIALS, HPARAM_RANGE / HPARAM_CANDIDATES, HPARAM_TUNING_ALGORITHM (VIZIER_DEFAULT, RANDOM_SEARCH, GRID_SEARCH), inspected with ML.TRIAL_INFO (Chapter 2) |
| AutoML | Tunes automatically. You can't set hyperparameter values |
| Gemini tuning | Epochs, adapter size, and learning rate multiplier (Section 10.3) |
| Ray on Agent Platform | Ray Tune for distributed search inside Ray workloads |
Worked Example: Reading a Study Result
A 30-trial study tunes an XGBoost fraud model on max_depth (INTEGER 3-12), learning_rate (DOUBLE 0.001-0.3, log scale), and subsample (DOUBLE 0.5-1.0, linear), maximizing validation AUC PR.
| Observation | Interpretation |
|---|---|
The best 5 trials all have learning_rate between 0.03 and 0.08 | The useful range is found. Narrow it in the next study |
max_depth above 9 never lands in the top 10 | Deep trees overfit here. Lower the upper bound |
subsample shows no clear pattern | Low sensitivity. Fix it at a reasonable value and stop tuning it |
| The best validation AUC PR is 0.62, but test AUC PR is 0.55 | Some overfitting to validation from repeated selection. Report the test value honestly, and consider cross-validation or more validation data |
Practical Strategy
- Start from sensible defaults and a baseline run.
- Tune the most influential hyperparameters first, such as learning rate, tree depth, and regularization.
- Use log scale for rates and regularization strengths.
- Optimize the metric that matters, like AUC PR for rare-event problems, measured on validation data. Keep the test set untouched for the final report.
- Moderate parallelism: a common balance is a few trials at a time, so Bayesian search keeps learning.
- Use early stopping inside each trial so hopeless configurations end quickly and save cost.
- Register the best trial's model and log the study results to Experiments.
A team tunes learning rates between 0.00001 and 0.1 with UNIT_LINEAR_SCALE, and nearly every trial lands at the high end of the range. What change should they make?
A tuning job must let Agent Platform learn from completed trials to choose better configurations, and the budget allows 40 trials. Which setting best supports efficient Bayesian optimization?
How does a custom training application report its objective metric to an Agent Platform hyperparameter tuning job?