--- title: "POST /v1/{+parent}/studies" method: POST path: "/v1/{+parent}/studies" tags: ["projects"] --- # POST /v1/{+parent}/studies `POST /v1/{+parent}/studies` Creates a Study. A resource name will be generated after creation of the Study. ## Path parameters - `parent` string, required ## Request body - GoogleCloudAiplatformV1Study — A message representing a Study. - `name` string — Output only. The name of a study. The study's globally unique identifier. Format: `projects/{project}/locations/{location}/studies/{study}` - `displayName` string — Required. Describes the Study, default value is empty string. - `createTime` string, google-datetime — Output only. Time at which the study was created. - `inactiveReason` string — Output only. A human readable reason why the Study is inactive. This should be empty if a study is ACTIVE or COMPLETED. - `state` 'STATE_UNSPECIFIED' | 'ACTIVE' | 'INACTIVE' | 'COMPLETED' — Output only. The detailed state of a Study. - `studySpec` GoogleCloudAiplatformV1StudySpec — Represents specification of a Study. - `medianAutomatedStoppingSpec` GoogleCloudAiplatformV1StudySpecMedianAutomatedStoppingSpec — The median automated stopping rule stops a pending Trial if the Trial's best objective_value is strictly below the median 'performance' of all completed Trials reported up to the Trial's last measurement. Currently, 'performance' refers to the running average of the objective values reported by the Trial in each measurement. - `useElapsedDuration` boolean — True if median automated stopping rule applies on Measurement.elapsed_duration. It means that elapsed_duration field of latest measurement of current Trial is used to compute median objective value for each completed Trials. - `decayCurveStoppingSpec` GoogleCloudAiplatformV1StudySpecDecayCurveAutomatedStoppingSpec — The decay curve automated stopping rule builds a Gaussian Process Regressor to predict the final objective value of a Trial based on the already completed Trials and the intermediate measurements of the current Trial. Early stopping is requested for the current Trial if there is very low probability to exceed the optimal value found so far. - `useElapsedDuration` boolean — True if Measurement.elapsed_duration is used as the x-axis of each Trials Decay Curve. Otherwise, Measurement.step_count will be used as the x-axis. - `convexAutomatedStoppingSpec` GoogleCloudAiplatformV1StudySpecConvexAutomatedStoppingSpec — Configuration for ConvexAutomatedStoppingSpec. When there are enough completed trials (configured by min_measurement_count), for pending trials with enough measurements and steps, the policy first computes an overestimate of the objective value at max_num_steps according to the slope of the incomplete objective value curve. No prediction can be made if the curve is completely flat. If the overestimation is worse than the best objective value of the completed trials, this pending trial will be early-stopped, but a last measurement will be added to the pending trial with max_num_steps and predicted objective value from the autoregression model. - `minMeasurementCount` string, int64 — The minimal number of measurements in a Trial. Early-stopping checks will not trigger if less than min_measurement_count+1 completed trials or pending trials with less than min_measurement_count measurements. If not defined, the default value is 5. - `maxStepCount` string, int64 — Steps used in predicting the final objective for early stopped trials. In general, it's set to be the same as the defined steps in training / tuning. If not defined, it will learn it from the completed trials. When use_steps is false, this field is set to the maximum elapsed seconds. - `learningRateParameterName` string — The hyper-parameter name used in the tuning job that stands for learning rate. Leave it blank if learning rate is not in a parameter in tuning. The learning_rate is used to estimate the objective value of the ongoing trial. - `minStepCount` string, int64 — Minimum number of steps for a trial to complete. Trials which do not have a measurement with step_count > min_step_count won't be considered for early stopping. It's ok to set it to 0, and a trial can be early stopped at any stage. By default, min_step_count is set to be one-tenth of the max_step_count. When use_elapsed_duration is true, this field is set to the minimum elapsed seconds. - `updateAllStoppedTrials` boolean — ConvexAutomatedStoppingSpec by default only updates the trials that needs to be early stopped using a newly trained auto-regressive model. When this flag is set to True, all stopped trials from the beginning are potentially updated in terms of their `final_measurement`. Also, note that the training logic of autoregressive models is different in this case. Enabling this option has shown better results and this may be the default option in the future. - `useElapsedDuration` boolean — This bool determines whether or not the rule is applied based on elapsed_secs or steps. If use_elapsed_duration==false, the early stopping decision is made according to the predicted objective values according to the target steps. If use_elapsed_duration==true, elapsed_secs is used instead of steps. Also, in this case, the parameters max_num_steps and min_num_steps are overloaded to contain max_elapsed_seconds and min_elapsed_seconds. - `metrics` GoogleCloudAiplatformV1StudySpecMetricSpec[] — Required. Metric specs for the Study. - `metricId` string — Required. The ID of the metric. Must not contain whitespaces and must be unique amongst all MetricSpecs. - `goal` 'GOAL_TYPE_UNSPECIFIED' | 'MAXIMIZE' | 'MINIMIZE' — Required. The optimization goal of the metric. - `safetyConfig` GoogleCloudAiplatformV1StudySpecMetricSpecSafetyMetricConfig — Used in safe optimization to specify threshold levels and risk tolerance. - `safetyThreshold` number, double — Safety threshold (boundary value between safe and unsafe). NOTE that if you leave SafetyMetricConfig unset, a default value of 0 will be used. - `desiredMinSafeTrialsFraction` number, double — Desired minimum fraction of safe trials (over total number of trials) that should be targeted by the algorithm at any time during the study (best effort). This should be between 0.0 and 1.0 and a value of 0.0 means that there is no minimum and an algorithm proceeds without targeting any specific fraction. A value of 1.0 means that the algorithm attempts to only Suggest safe Trials. - `observationNoise` 'OBSERVATION_NOISE_UNSPECIFIED' | 'LOW' | 'HIGH' — The observation noise level of the study. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline. - `algorithm` 'ALGORITHM_UNSPECIFIED' | 'GRID_SEARCH' | 'RANDOM_SEARCH' — The search algorithm specified for the Study. - `measurementSelectionType` 'MEASUREMENT_SELECTION_TYPE_UNSPECIFIED' | 'LAST_MEASUREMENT' | 'BEST_MEASUREMENT' — Describe which measurement selection type will be used - `parameters` GoogleCloudAiplatformV1StudySpecParameterSpec[] — Required. The set of parameters to tune. - `discreteValueSpec` GoogleCloudAiplatformV1StudySpecParameterSpecDiscreteValueSpec — Value specification for a parameter in `DISCRETE` type. - `defaultValue` number, double — A default value for a `DISCRETE` parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point. It automatically rounds to the nearest feasible discrete point. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline. - `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` 'SCALE_TYPE_UNSPECIFIED' | 'UNIT_LINEAR_SCALE' | 'UNIT_LOG_SCALE' | 'UNIT_REVERSE_LOG_SCALE' — How the parameter should be scaled. Leave unset for `CATEGORICAL` parameters. - `conditionalParameterSpecs` GoogleCloudAiplatformV1StudySpecParameterSpecConditionalParameterSpec[] — A conditional parameter node is active if the parameter's value matches the conditional node's parent_value_condition. If two items in conditional_parameter_specs have the same name, they must have disjoint parent_value_condition. - `parentIntValues` GoogleCloudAiplatformV1StudySpecParameterSpecConditionalParameterSpecIntValueCondition — Represents the spec to match integer values from parent parameter. - `values` string[] — Required. Matches values of the parent parameter of 'INTEGER' type. All values must lie in `integer_value_spec` of parent parameter. - `parentCategoricalValues` GoogleCloudAiplatformV1StudySpecParameterSpecConditionalParameterSpecCategoricalValueCondition — Represents the spec to match categorical values from parent parameter. - `values` string[] — Required. Matches values of the parent parameter of 'CATEGORICAL' type. All values must exist in `categorical_value_spec` of parent parameter. - `parentDiscreteValues` GoogleCloudAiplatformV1StudySpecParameterSpecConditionalParameterSpecDiscreteValueCondition — Represents the spec to match discrete values from parent parameter. - `values` number[] — Required. Matches values of the parent parameter of 'DISCRETE' type. All values must exist in `discrete_value_spec` of parent parameter. The Epsilon of the value matching is 1e-10. - `parameterSpec` GoogleCloudAiplatformV1StudySpecParameterSpec — recursive - `doubleValueSpec` GoogleCloudAiplatformV1StudySpecParameterSpecDoubleValueSpec — Value specification for a parameter in `DOUBLE` type. - `minValue` number, double — Required. Inclusive minimum value of the parameter. - `defaultValue` number, double — A default value for a `DOUBLE` parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline. - `maxValue` number, double — Required. Inclusive maximum value of the parameter. - `parameterId` string — Required. The ID of the parameter. Must not contain whitespaces and must be unique amongst all ParameterSpecs. - `integerValueSpec` GoogleCloudAiplatformV1StudySpecParameterSpecIntegerValueSpec — Value specification for a parameter in `INTEGER` type. - `maxValue` string, int64 — Required. Inclusive maximum value of the parameter. - `defaultValue` string, int64 — A default value for an `INTEGER` parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline. - `minValue` string, int64 — Required. Inclusive minimum value of the parameter. - `categoricalValueSpec` GoogleCloudAiplatformV1StudySpecParameterSpecCategoricalValueSpec — Value specification for a parameter in `CATEGORICAL` type. - `values` string[] — Required. The list of possible categories. - `defaultValue` string — A default value for a `CATEGORICAL` parameter that is assumed to be a relatively good starting point. Unset value signals that there is no offered starting point. Currently only supported by the Vertex AI Vizier service. Not supported by HyperparameterTuningJob or TrainingPipeline. - `studyStoppingConfig` GoogleCloudAiplatformV1StudySpecStudyStoppingConfig — The configuration (stopping conditions) for automated stopping of a Study. Conditions include trial budgets, time budgets, and convergence detection. - `minimumRuntimeConstraint` GoogleCloudAiplatformV1StudyTimeConstraint — Time-based Constraint for Study - `endTime` string, google-datetime — Compares the wallclock time to this time. Must use UTC timezone. - `maxDuration` string, google-duration — Counts the wallclock time passed since the creation of this Study. - `maxNumTrialsNoProgress` integer — If the objective value has not improved for this many consecutive trials, stop the study. WARNING: Effective only for single-objective studies. - `maxDurationNoProgress` string, google-duration — If the objective value has not improved for this much time, stop the study. WARNING: Effective only for single-objective studies. - `maximumRuntimeConstraint` GoogleCloudAiplatformV1StudyTimeConstraint — Time-based Constraint for Study - `endTime` string, google-datetime — Compares the wallclock time to this time. Must use UTC timezone. - `maxDuration` string, google-duration — Counts the wallclock time passed since the creation of this Study. - `shouldStopAsap` boolean — If true, a Study enters STOPPING_ASAP whenever it would normally enters STOPPING state. The bottom line is: set to true if you want to interrupt on-going evaluations of Trials as soon as the study stopping condition is met. (Please see Study.State documentation for the source of truth). - `minNumTrials` integer — If there are fewer than this many COMPLETED trials, do not stop the study. - `maxNumTrials` integer — If there are more than this many trials, stop the study. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/aiplatform.md) · [All operations](https://skmtc.net/google/apis/aiplatform/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/aiplatform/versions/b608d71b91f0/schema)