Try Gemini 1.5 Pro, our most advanced multimodal model in Vertex AI, and see what you can build with a 1M token context window. Try Gemini 1.5 Pro, our most advanced multimodal model in Vertex AI, and see what you can build with a 1M token context window.

Method: projects.locations.studies.trials.suggest

Adds one or more Trials to a Study, with parameter values suggested by Vertex AI Vizier. Returns a long-running operation associated with the generation of Trial suggestions. When this long-running operation succeeds, it will contain a SuggestTrialsResponse.

HTTP request

POST https://{service-endpoint}/v1/{parent}/trials:suggest

Where {service-endpoint} is one of the supported service endpoints.

Path parameters

Parameters

Parameters
`parent`	`string` Required. The project and location that the Study belongs to. Format: `projects/{project}/locations/{location}/studies/{study}`

parent

string

Required. The project and location that the Study belongs to. Format: projects/{project}/locations/{location}/studies/{study}

Request body

The request body contains data with the following structure:

JSON representation
{ "suggestionCount": integer, "clientId": string, "contexts": [ { object (`TrialContext`) } ] }

Fields

Fields
`suggestionCount`	`integer` Required. The number of suggestions requested. It must be positive.
`clientId`	`string` Required. The identifier of the client that is requesting the suggestion. If multiple SuggestTrialsRequests have the same `clientId`, the service will return the identical suggested Trial if the Trial is pending, and provide a new Trial if the last suggested Trial was completed.
`contexts[]`	`object (TrialContext)` Optional. This allows you to specify the "context" for a Trial; a context is a slice (a subspace) of the search space. Typical uses for contexts: 1) You are using Vizier to tune a server for best performance, but there's a strong weekly cycle. The context specifies the day-of-week. This allows Tuesday to generalize from Wednesday without assuming that everything is identical. 2) Imagine you're optimizing some medical treatment for people. As they walk in the door, you know certain facts about them (e.g. sex, weight, height, blood-pressure). Put that information in the context, and Vizier will adapt its suggestions to the patient. 3) You want to do a fair A/B test efficiently. Specify the "A" and "B" conditions as contexts, and Vizier will generalize between "A" and "B" conditions. If they are similar, this will allow Vizier to converge to the optimum faster than if "A" and "B" were separate Studies. NOTE: You can also enter contexts as REQUESTED Trials, e.g. via the trials.create() RPC; that's the asynchronous option where you don't need a close association between contexts and suggestions. NOTE: All the Parameters you set in a context MUST be defined in the Study. NOTE: You must supply 0 or $suggestionCount contexts. If you don't supply any contexts, Vizier will make suggestions from the full search space specified in the StudySpec; if you supply a full set of context, each suggestion will match the corresponding context. NOTE: A Context with no features set matches anything, and allows suggestions from the full search space. NOTE: contexts MUST lie within the search space specified in the StudySpec. It's an error if they don't. NOTE: contexts preferentially match ACTIVE then REQUESTED trials before new suggestions are generated. NOTE: Generation of suggestions involves a match between a Context and (optionally) a REQUESTED trial; if that match is not fully specified, a suggestion will be geneated in the merged subspace.

suggestionCount

integer

Required. The number of suggestions requested. It must be positive.

clientId

string

Required. The identifier of the client that is requesting the suggestion.

If multiple SuggestTrialsRequests have the same clientId, the service will return the identical suggested Trial if the Trial is pending, and provide a new Trial if the last suggested Trial was completed.

contexts[]

object (TrialContext)

Optional. This allows you to specify the "context" for a Trial; a context is a slice (a subspace) of the search space.

Typical uses for contexts: 1) You are using Vizier to tune a server for best performance, but there's a strong weekly cycle. The context specifies the day-of-week. This allows Tuesday to generalize from Wednesday without assuming that everything is identical. 2) Imagine you're optimizing some medical treatment for people. As they walk in the door, you know certain facts about them (e.g. sex, weight, height, blood-pressure). Put that information in the context, and Vizier will adapt its suggestions to the patient. 3) You want to do a fair A/B test efficiently. Specify the "A" and "B" conditions as contexts, and Vizier will generalize between "A" and "B" conditions. If they are similar, this will allow Vizier to converge to the optimum faster than if "A" and "B" were separate Studies. NOTE: You can also enter contexts as REQUESTED Trials, e.g. via the trials.create() RPC; that's the asynchronous option where you don't need a close association between contexts and suggestions.

NOTE: All the Parameters you set in a context MUST be defined in the Study. NOTE: You must supply 0 or $suggestionCount contexts. If you don't supply any contexts, Vizier will make suggestions from the full search space specified in the StudySpec; if you supply a full set of context, each suggestion will match the corresponding context. NOTE: A Context with no features set matches anything, and allows suggestions from the full search space. NOTE: contexts MUST lie within the search space specified in the StudySpec. It's an error if they don't. NOTE: contexts preferentially match ACTIVE then REQUESTED trials before new suggestions are generated. NOTE: Generation of suggestions involves a match between a Context and (optionally) a REQUESTED trial; if that match is not fully specified, a suggestion will be geneated in the merged subspace.

Response body

If successful, the response body contains an instance of Operation.

Authorization scopes

Requires the following OAuth scope:

https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

aiplatform.trials.create

For more information, see the IAM documentation.

TrialContext

Next ID: 3

JSON representation
{ "description": string, "parameters": [ { object (`Parameter`) } ] }

Fields

Fields
`description`	`string` A human-readable field which can store a description of this context. This will become part of the resulting Trial's description field.
`parameters[]`	`object (Parameter)` If/when a Trial is generated or selected from this Context, its Parameters will match any parameters specified here. (I.e. if this context specifies parameter name:'a' intValue:3, then a resulting Trial will have intValue:3 for its parameter named 'a'.) Note that we first attempt to match existing REQUESTED Trials with contexts, and if there are no matches, we generate suggestions in the subspace defined by the parameters specified here. NOTE: a Context without any Parameters matches the entire feasible search space.

description

string

A human-readable field which can store a description of this context. This will become part of the resulting Trial's description field.

parameters[]

object (Parameter)

If/when a Trial is generated or selected from this Context, its Parameters will match any parameters specified here. (I.e. if this context specifies parameter name:'a' intValue:3, then a resulting Trial will have intValue:3 for its parameter named 'a'.) Note that we first attempt to match existing REQUESTED Trials with contexts, and if there are no matches, we generate suggestions in the subspace defined by the parameters specified here. NOTE: a Context without any Parameters matches the entire feasible search space.