REST Resource: projects.locations.collections.engines

Resource: Engine

Metadata that describes the training and serving parameters of an Engine.

JSON representation 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "dataStoreIds": [
    string
  ],
  "solutionType": enum (SolutionType),
  "industryVertical": enum (IndustryVertical),
  "commonConfig": {
    object (CommonConfig)
  },
  "disableAnalytics": boolean,
  "features": {
    string: enum (FeatureState),
    ...
  },

  // Union field engine_config can be only one of the following:
  "chatEngineConfig": {
    object (ChatEngineConfig)
  },
  "searchEngineConfig": {
    object (SearchEngineConfig)
  },
  "mediaRecommendationEngineConfig": {
    object (MediaRecommendationEngineConfig)
  }
  // End of list of possible types for union field engine_config.

  // Union field engine_metadata can be only one of the following:
  "chatEngineMetadata": {
    object (ChatEngineMetadata)
  }
  // End of list of possible types for union field engine_metadata.
}
Fields
name

string

Immutable. Identifier. The fully qualified resource name of the engine.

This field must be a UTF-8 encoded string with a length limit of 1024 characters.

Format: projects/{project}/locations/{___location}/collections/{collection}/engines/{engine} engine should be 1-63 characters, and valid characters are /[a-z0-9][a-z0-9-_]*/. Otherwise, an INVALID_ARGUMENT error is returned.
displayName

string

Required. The display name of the engine. Should be human readable. UTF-8 encoded string with limit of 1024 characters.
createTime

string (Timestamp format)

Output only. Timestamp the Recommendation Engine was created at.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Timestamp the Recommendation Engine was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
dataStoreIds[]

string

Optional. The data stores associated with this engine.

For SOLUTION_TYPE_SEARCH and SOLUTION_TYPE_RECOMMENDATION type of engines, they can only associate with at most one data store.

If solutionType is SOLUTION_TYPE_CHAT, multiple DataStores in the same Collection can be associated here.

Note that when used in CreateEngineRequest, one DataStore id must be provided as the system will use it for necessary initializations.
solutionType

enum (SolutionType)

Required. The solutions of the engine.
industryVertical

enum (IndustryVertical)

Optional. The industry vertical that the engine registers. The restriction of the Engine industry vertical is based on DataStore: Vertical on Engine has to match vertical of the DataStore linked to the engine.
commonConfig

object (CommonConfig)

Common config spec that specifies the metadata of the engine.
disableAnalytics

boolean

Optional. Whether to disable analytics for searches performed on this engine.
features

map (key: string, value: enum (FeatureState))

Optional. Feature config for the engine to opt in or opt out of features. Supported keys:

  • *: all features, if it's present, all other feature state settings are ignored.
  • agent-gallery
  • no-code-agent-builder
  • prompt-gallery
  • model-selector
  • notebook-lm
  • people-search
  • people-search-org-chart
  • bi-directional-audio
  • feedback
  • session-sharing
  • personalization-memory - Enables personalization based on user preferences.
Union field engine_config. Additional config specs that defines the behavior of the engine. engine_config can be only one of the following:
chatEngineConfig

object (ChatEngineConfig)

Configurations for the Chat Engine. Only applicable if solutionType is SOLUTION_TYPE_CHAT.
searchEngineConfig

object (SearchEngineConfig)

Configurations for the Search Engine. Only applicable if solutionType is SOLUTION_TYPE_SEARCH.
mediaRecommendationEngineConfig

object (MediaRecommendationEngineConfig)

Configurations for the Media Engine. Only applicable on the data stores with solutionType SOLUTION_TYPE_RECOMMENDATION and IndustryVertical.MEDIA vertical.
Union field engine_metadata. Engine metadata to monitor the status of the engine. engine_metadata can be only one of the following:
chatEngineMetadata

object (ChatEngineMetadata)

Output only. Additional information of the Chat Engine. Only applicable if solutionType is SOLUTION_TYPE_CHAT.

ChatEngineConfig

Configurations for a Chat Engine.

JSON representation 
{
  "agentCreationConfig": {
    object (AgentCreationConfig)
  },
  "dialogflowAgentToLink": string,
  "allowCrossRegion": boolean
}
Fields
agentCreationConfig

object (AgentCreationConfig)

The configurationt generate the Dialogflow agent that is associated to this Engine.

Note that these configurations are one-time consumed by and passed to Dialogflow service. It means they cannot be retrieved using EngineService.GetEngine or EngineService.ListEngines API after engine creation.
allowCrossRegion

boolean

Optional. If the flag set to true, we allow the agent and engine are in different locations, otherwise the agent and engine are required to be in the same ___location. The flag is set to false by default.

Note that the allowCrossRegion are one-time consumed by and passed to EngineService.CreateEngine. It means they cannot be retrieved using EngineService.GetEngine or EngineService.ListEngines API after engine creation.

AgentCreationConfig

Configurations for generating a Dialogflow agent.

Note that these configurations are one-time consumed by and passed to Dialogflow service. It means they cannot be retrieved using EngineService.GetEngine or EngineService.ListEngines API after engine creation.

JSON representation 
{
  "business": string,
  "defaultLanguageCode": string,
  "timeZone": string,
  "___location": string
}
Fields
business

string

Name of the company, organization or other entity that the agent represents. Used for knowledge connector LLM prompt and for knowledge search.
defaultLanguageCode

string

Required. The default language of the agent as a language tag. See Language Support for a list of the currently supported language codes.
timeZone

string

Required. The time zone of the agent from the time zone database, e.g., America/New_York, Europe/Paris.
___location

string

Agent ___location for Agent creation, supported values: global/us/eu. If not provided, us Engine will create Agent using us-central-1 by default; eu Engine will create Agent using eu-west-1 by default.

SearchEngineConfig

Configurations for a Search Engine.

JSON representation 
{
  "searchTier": enum (SearchTier),
  "searchAddOns": [
    enum (SearchAddOn)
  ]
}
Fields
searchTier

enum (SearchTier)

The search feature tier of this engine.

Different tiers might have different pricing. To learn more, check the pricing documentation.

Defaults to SearchTier.SEARCH_TIER_STANDARD if not specified.
searchAddOns[]

enum (SearchAddOn)

The add-on that this search engine enables.

SearchTier

Tiers of search features. Different tiers might have different pricing. To learn more, check the pricing documentation.

Enums
SEARCH_TIER_UNSPECIFIED Default value when the enum is unspecified. This is invalid to use.
SEARCH_TIER_STANDARD Standard tier.
SEARCH_TIER_ENTERPRISE Enterprise tier.

SearchAddOn

Add-on that provides additional functionality for search.

Enums
SEARCH_ADD_ON_UNSPECIFIED Default value when the enum is unspecified. This is invalid to use.
SEARCH_ADD_ON_LLM Large language model add-on.

MediaRecommendationEngineConfig

Additional config specs for a Media Recommendation engine.

JSON representation 
{
  "type": string,
  "optimizationObjective": string,
  "optimizationObjectiveConfig": {
    object (OptimizationObjectiveConfig)
  },
  "trainingState": enum (TrainingState),
  "engineFeaturesConfig": {
    object (EngineFeaturesConfig)
  }
}
Fields
type

string

Required. The type of engine. e.g., recommended-for-you.

This field together with optimizationObjective describe engine metadata to use to control engine training and serving.

Currently supported values: recommended-for-you, others-you-may-like, more-like-this, most-popular-items.
optimizationObjective

string

The optimization objective. e.g., cvr.

This field together with optimizationObjective describe engine metadata to use to control engine training and serving.

Currently supported values: ctr, cvr.

If not specified, we choose default based on engine type. Default depends on type of recommendation:

recommended-for-you => ctr

others-you-may-like => ctr
optimizationObjectiveConfig

object (OptimizationObjectiveConfig)

Name and value of the custom threshold for cvr optimizationObjective. For targetField watch-time, target_field_value must be an integer value indicating the media progress time in seconds between (0, 86400] (excludes 0, includes 86400) (e.g., 90). For targetField watch-percentage, the target_field_value must be a valid float value between (0, 1.0] (excludes 0, includes 1.0) (e.g., 0.5).
trainingState

enum (TrainingState)

The training state that the engine is in (e.g. TRAINING or PAUSED).

Since part of the cost of running the service is frequency of training - this can be used to determine when to train engine in order to control cost. If not specified: the default value for engines.create method is TRAINING. The default value for engines.patch method is to keep the state the same as before.
engineFeaturesConfig

object (EngineFeaturesConfig)

Optional. Additional engine features config.

OptimizationObjectiveConfig

Custom threshold for cvr optimizationObjective.

JSON representation 
{
  "targetField": string,
  "targetFieldValueFloat": number
}
Fields
targetField

string

Required. The name of the field to target. Currently supported values: watch-percentage, watch-time.
targetFieldValueFloat

number

Required. The threshold to be applied to the target (e.g., 0.5).

TrainingState

The training state of the engine.

Enums
TRAINING_STATE_UNSPECIFIED Unspecified training state.
PAUSED The engine training is paused.
TRAINING The engine is training.

EngineFeaturesConfig

More feature configs of the selected engine type.

JSON representation 
{

  // Union field type_dedicated_config can be only one of the following:
  "recommendedForYouConfig": {
    object (RecommendedForYouFeatureConfig)
  },
  "mostPopularConfig": {
    object (MostPopularFeatureConfig)
  }
  // End of list of possible types for union field type_dedicated_config.
}
Fields
Union field type_dedicated_config. Feature related configurations applied to a specific type of media recommendation engines. type_dedicated_config can be only one of the following:
recommendedForYouConfig

object (RecommendedForYouFeatureConfig)

Recommended for you engine feature config.

RecommendedForYouFeatureConfig

Additional feature configurations for creating a recommended-for-you engine.

JSON representation 
{
  "contextEventType": string
}
Fields
contextEventType

string

The type of event with which the engine is queried at prediction time. If set to generic, only view-item, media-play,and media-complete will be used as context-event in engine training. If set to view-home-page, view-home-page will also be used as context-events in addition to view-item, media-play, and media-complete. Currently supported for the recommended-for-you engine. Currently supported values: view-home-page, generic.

MostPopularFeatureConfig

Feature configurations that are required for creating a Most Popular engine.

JSON representation 
{
  "timeWindowDays": string
}
Fields
timeWindowDays

string (int64 format)

The time window of which the engine is queried at training and prediction time. Positive integers only. The value translates to the last X days of events. Currently required for the most-popular-items engine.

ChatEngineMetadata

Additional information of a Chat Engine. Fields in this message are output only.

JSON representation 
{
  "dialogflowAgent": string
}
Fields
dialogflowAgent

string

The resource name of a Dialogflow agent, that this Chat Engine refers to.

Format: projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>.

CommonConfig

Common configurations for an Engine.

JSON representation 
{
  "companyName": string
}
Fields
companyName

string

The name of the company, business or entity that is associated with the engine. Setting this may help improve LLM related features.

FeatureState

The state of the feature for the engine.

Enums
FEATURE_STATE_UNSPECIFIED The feature state is unspecified.
FEATURE_STATE_ON The feature is turned on to be accessible.
FEATURE_STATE_OFF The feature is turned off to be inaccessible.

Methods

create

 Creates a Engine.

delete

 Deletes a Engine.

get

 Gets a Engine.

list

 Lists all the Engines associated with the project.

patch

 Updates an Engine

pause

 Pauses the training of an existing engine.

resume

 Resumes the training of an existing engine.

tune

 Tunes an existing engine.