REST Resource: projects.locations.hyperparameterTuningJobs

Resource: HyperparameterTuningJob

Represents a HyperparameterTuningJob. A HyperparameterTuningJob has a Study specification and multiple CustomJobs with identical CustomJob specification.

JSON representation
{
  "name": string,
  "displayName": string,
  "studySpec": {
    object (StudySpec)
  },
  "maxTrialCount": integer,
  "parallelTrialCount": integer,
  "maxFailedTrialCount": integer,
  "trialJobSpec": {
    object (CustomJobSpec)
  },
  "trials": [
    {
      object (Trial)
    }
  ],
  "state": enum (JobState),
  "createTime": string,
  "startTime": string,
  "endTime": string,
  "updateTime": string,
  "error": {
    object (Status)
  },
  "labels": {
    string: string,
    ...
  },
  "encryptionSpec": {
    object (EncryptionSpec)
  }
}
Fields
name

string

Output only. Resource name of the HyperparameterTuningJob.

displayName

string

Required. The display name of the HyperparameterTuningJob. The name can be up to 128 characters long and can be consist of any UTF-8 characters.

studySpec

object (StudySpec)

Required. Study configuration of the HyperparameterTuningJob.

maxTrialCount

integer

Required. The desired total number of Trials.

parallelTrialCount

integer

Required. The desired number of Trials to run in parallel.

maxFailedTrialCount

integer

The number of failed Trials that need to be seen before failing the HyperparameterTuningJob.

If set to 0, Vertex AI decides how many Trials must fail before the whole job fails.

trialJobSpec

object (CustomJobSpec)

Required. The spec of a trial job. The same spec applies to the CustomJobs created in all the trials.

trials[]

object (Trial)

Output only. Trials of the HyperparameterTuningJob.

state

enum (JobState)

Output only. The detailed state of the job.

createTime

string (Timestamp format)

Output only. Time when the HyperparameterTuningJob was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

startTime

string (Timestamp format)

Output only. Time when the HyperparameterTuningJob for the first time entered the JOB_STATE_RUNNING state.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. Time when the HyperparameterTuningJob entered any of the following states: JOB_STATE_SUCCEEDED, JOB_STATE_FAILED, JOB_STATE_CANCELLED.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Output only. Time when the HyperparameterTuningJob was most recently updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

error

object (Status)

Output only. Only populated when job's state is JOB_STATE_FAILED or JOB_STATE_CANCELLED.

labels

map (key: string, value: string)

The labels with user-defined metadata to organize HyperparameterTuningJobs.

Label keys and values can be no longer than 64 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed.

See https://goo.gl/xmQnxf for more information and examples of labels.

encryptionSpec

object (EncryptionSpec)

Customer-managed encryption key options for a HyperparameterTuningJob. If this is set, then all resources created by the HyperparameterTuningJob will be encrypted with the provided encryption key.

StudySpec

Represents specification of a Study.

JSON representation
{
  "metrics": [
    {
      object (MetricSpec)
    }
  ],
  "parameters": [
    {
      object (ParameterSpec)
    }
  ],
  "algorithm": enum (Algorithm),
  "measurementSelectionType": enum (MeasurementSelectionType)
}
Fields
metrics[]

object (MetricSpec)

Required. Metric specs for the Study.

parameters[]

object (ParameterSpec)

Required. The set of parameters to tune.

algorithm

enum (Algorithm)

The search algorithm specified for the Study.

measurementSelectionType

enum (MeasurementSelectionType)

Describe which measurement selection type will be used

MetricSpec

Represents a metric to optimize.

JSON representation
{
  "metricId": string,
  "goal": enum (GoalType)
}
Fields
metricId

string

Required. The ID of the metric. Must not contain whitespaces and must be unique amongst all MetricSpecs.

goal

enum (GoalType)

Required. The optimization goal of the metric.

GoalType

The available types of optimization goals.

Enums
GOAL_TYPE_UNSPECIFIED Goal Type will default to maximize.
MAXIMIZE Maximize the goal metric.
MINIMIZE Minimize the goal metric.

ParameterSpec

Represents a single parameter to optimize.

JSON representation
{
  "parameterId": string,
  "scaleType": enum (ScaleType),
  "conditionalParameterSpecs": [
    {
      object (ConditionalParameterSpec)
    }
  ],

  // Union field parameter_value_spec can be only one of the following:
  "doubleValueSpec": {
    object (DoubleValueSpec)
  },
  "integerValueSpec": {
    object (IntegerValueSpec)
  },
  "categoricalValueSpec": {
    object (CategoricalValueSpec)
  },
  "discreteValueSpec": {
    object (DiscreteValueSpec)
  }
  // End of list of possible types for union field parameter_value_spec.
}
Fields
parameterId

string

Required. The ID of the parameter. Must not contain whitespaces and must be unique amongst all ParameterSpecs.

scaleType

enum (ScaleType)

How the parameter should be scaled. Leave unset for CATEGORICAL parameters.

conditionalParameterSpecs[]

object (ConditionalParameterSpec)

A conditional parameter node is active if the parameter's value matches the conditional node's parent_value_condition.

If two items in conditionalParameterSpecs have the same name, they must have disjoint parent_value_condition.

Union field parameter_value_spec.

parameter_value_spec can be only one of the following:

doubleValueSpec

object (DoubleValueSpec)

The value spec for a 'DOUBLE' parameter.

integerValueSpec

object (IntegerValueSpec)

The value spec for an 'INTEGER' parameter.

categoricalValueSpec

object (CategoricalValueSpec)

The value spec for a 'CATEGORICAL' parameter.

discreteValueSpec

object (DiscreteValueSpec)

The value spec for a 'DISCRETE' parameter.

DoubleValueSpec

Value specification for a parameter in DOUBLE type.

JSON representation
{
  "minValue": number,
  "maxValue": number
}
Fields
minValue

number

Required. Inclusive minimum value of the parameter.

maxValue

number

Required. Inclusive maximum value of the parameter.

IntegerValueSpec

Value specification for a parameter in INTEGER type.

JSON representation
{
  "minValue": string,
  "maxValue": string
}
Fields
minValue

string (int64 format)

Required. Inclusive minimum value of the parameter.

maxValue

string (int64 format)

Required. Inclusive maximum value of the parameter.

CategoricalValueSpec

Value specification for a parameter in CATEGORICAL type.

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string

Required. The list of possible categories.

DiscreteValueSpec

Value specification for a parameter in DISCRETE type.

JSON representation
{
  "values": [
    number
  ]
}
Fields
values[]

number

Required. A list of possible values. The list should be in increasing order and at least 1e-10 apart. For instance, this parameter might have possible settings of 1.5, 2.5, and 4.0. This list should not contain more than 1,000 values.

ScaleType

The type of scaling that should be applied to this parameter.

Enums
SCALE_TYPE_UNSPECIFIED By default, no scaling is applied.
UNIT_LINEAR_SCALE Scales the feasible space to (0, 1) linearly.
UNIT_LOG_SCALE Scales the feasible space logarithmically to (0, 1). The entire feasible space must be strictly positive.
UNIT_REVERSE_LOG_SCALE Scales the feasible space "reverse" logarithmically to (0, 1). The result is that values close to the top of the feasible space are spread out more than points near the bottom. The entire feasible space must be strictly positive.

ConditionalParameterSpec

Represents a parameter spec with condition from its parent parameter.

JSON representation
{
  "parameterSpec": {
    object (ParameterSpec)
  },

  // Union field parent_value_condition can be only one of the following:
  "parentDiscreteValues": {
    object (DiscreteValueCondition)
  },
  "parentIntValues": {
    object (IntValueCondition)
  },
  "parentCategoricalValues": {
    object (CategoricalValueCondition)
  }
  // End of list of possible types for union field parent_value_condition.
}
Fields
parameterSpec

object (ParameterSpec)

Required. The spec for a conditional parameter.

Union field parent_value_condition. A set of parameter values from the parent ParameterSpec's feasible space. parent_value_condition can be only one of the following:
parentDiscreteValues

object (DiscreteValueCondition)

The spec for matching values from a parent parameter of DISCRETE type.

parentIntValues

object (IntValueCondition)

The spec for matching values from a parent parameter of INTEGER type.

parentCategoricalValues

object (CategoricalValueCondition)

The spec for matching values from a parent parameter of CATEGORICAL type.

DiscreteValueCondition

Represents the spec to match discrete values from parent parameter.

JSON representation
{
  "values": [
    number
  ]
}
Fields
values[]

number

Required. Matches values of the parent parameter of 'DISCRETE' type. All values must exist in discreteValueSpec of parent parameter.

The Epsilon of the value matching is 1e-10.

IntValueCondition

Represents the spec to match integer values from parent parameter.

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string (int64 format)

Required. Matches values of the parent parameter of 'INTEGER' type. All values must lie in integerValueSpec of parent parameter.

CategoricalValueCondition

Represents the spec to match categorical values from parent parameter.

JSON representation
{
  "values": [
    string
  ]
}
Fields
values[]

string

Required. Matches values of the parent parameter of 'CATEGORICAL' type. All values must exist in categoricalValueSpec of parent parameter.

Algorithm

The available search algorithms for the Study.

Enums
ALGORITHM_UNSPECIFIED The default algorithm used by Vertex AI for hyperparameter tuning and Vertex Vizier.

MeasurementSelectionType

This indicates which measurement to use if/when the service automatically selects the final measurement from previously reported intermediate measurements. Choose this based on two considerations: A) Do you expect your measurements to monotonically improve? If so, choose LAST_MEASUREMENT. On the other hand, if you're in a situation where your system can "over-train" and you expect the performance to get better for a while but then start declining, choose BEST_MEASUREMENT. B) Are your measurements significantly noisy and/or irreproducible? If so, BEST_MEASUREMENT will tend to be over-optimistic, and it may be better to choose LAST_MEASUREMENT. If both or neither of (A) and (B) apply, it doesn't matter which selection type is chosen.

Enums
MEASUREMENT_SELECTION_TYPE_UNSPECIFIED Will be treated as LAST_MEASUREMENT.
LAST_MEASUREMENT Use the last measurement reported.
BEST_MEASUREMENT Use the best measurement reported.

Trial

A message representing a Trial. A Trial contains a unique set of Parameters that has been or will be evaluated, along with the objective metrics got by running the Trial.

JSON representation
{
  "name": string,
  "id": string,
  "state": enum (State),
  "parameters": [
    {
      object (Parameter)
    }
  ],
  "finalMeasurement": {
    object (Measurement)
  },
  "measurements": [
    {
      object (Measurement)
    }
  ],
  "startTime": string,
  "endTime": string,
  "clientId": string,
  "infeasibleReason": string,
  "customJob": string
}
Fields
name

string

Output only. Resource name of the Trial assigned by the service.

id

string

Output only. The identifier of the Trial assigned by the service.

state

enum (State)

Output only. The detailed state of the Trial.

parameters[]

object (Parameter)

Output only. The parameters of the Trial.

finalMeasurement

object (Measurement)

Output only. The final measurement containing the objective value.

measurements[]

object (Measurement)

Output only. A list of measurements that are strictly lexicographically ordered by their induced tuples (steps, elapsedDuration). These are used for early stopping computations.

startTime

string (Timestamp format)

Output only. Time when the Trial was started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. Time when the Trial's status changed to SUCCEEDED or INFEASIBLE.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

clientId

string

Output only. The identifier of the client that originally requested this Trial. Each client is identified by a unique clientId. When a client asks for a suggestion, Vizier will assign it a Trial. The client should evaluate the Trial, complete it, and report back to Vizier. If suggestion is asked again by same clientId before the Trial is completed, the same Trial will be returned. Multiple clients with different client_ids can ask for suggestions simultaneously, each of them will get their own Trial.

infeasibleReason

string

Output only. A human readable string describing why the Trial is infeasible. This is set only if Trial state is INFEASIBLE.

customJob

string

Output only. The CustomJob name linked to the Trial. It's set for a HyperparameterTuningJob's Trial.

State

Describes a Trial state.

Enums
STATE_UNSPECIFIED The Trial state is unspecified.
REQUESTED Indicates that a specific Trial has been requested, but it has not yet been suggested by the service.
ACTIVE Indicates that the Trial has been suggested.
STOPPING Indicates that the Trial should stop according to the service.
SUCCEEDED Indicates that the Trial is completed successfully.
INFEASIBLE Indicates that the Trial should not be attempted again. The service will set a Trial to INFEASIBLE when it's done but missing the finalMeasurement.

Parameter

A message representing a parameter to be tuned.

JSON representation
{
  "parameterId": string,
  "value": value
}
Fields
parameterId

string

Output only. The ID of the parameter. The parameter should be defined in StudySpec's Parameters.

value

value (Value format)

Output only. The value of the parameter. numberValue will be set if a parameter defined in StudySpec is in type 'INTEGER', 'DOUBLE' or 'DISCRETE'. stringValue will be set if a parameter defined in StudySpec is in type 'CATEGORICAL'.

Measurement

A message representing a Measurement of a Trial. A Measurement contains the Metrics got by executing a Trial using suggested hyperparameter values.

JSON representation
{
  "elapsedDuration": string,
  "stepCount": string,
  "metrics": [
    {
      object (Metric)
    }
  ]
}
Fields
elapsedDuration

string (Duration format)

Output only. Time that the Trial has been running at the point of this Measurement.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

stepCount

string (int64 format)

Output only. The number of steps the machine learning model has been trained for. Must be non-negative.

metrics[]

object (Metric)

Output only. A list of metrics got by evaluating the objective functions using suggested Parameter values.

Metric

A message representing a metric in the measurement.

JSON representation
{
  "metricId": string,
  "value": number
}
Fields
metricId

string

Output only. The ID of the Metric. The Metric should be defined in StudySpec's Metrics.

value

number

Output only. The value for this metric.

Methods

cancel

Cancels a HyperparameterTuningJob.

create

Creates a HyperparameterTuningJob

delete

Deletes a HyperparameterTuningJob.

get

Gets a HyperparameterTuningJob

list

Lists HyperparameterTuningJobs in a Location.