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)
  },

  // Union field engine_config can be only one of the following:
  "similarDocumentsConfig": {
    object (SimilarDocumentsEngineConfig)
  },
  "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:
  "recommendationMetadata": {
    object (RecommendationMetadata)
  },
  "chatEngineMetadata": {
    object (ChatEngineMetadata)
  }
  // End of list of possible types for union field engine_metadata.
}
Fields
name

string

Immutable. 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/{projectNumber}/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.

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. Timestamp the Recommendation Engine was last 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".
dataStoreIds[]

string

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)

The industry vertical that the engine registers. The restriction of the Engine industry vertical is based on DataStore: If unspecified, default to GENERIC. Vertical on Engine has to match vertical of the DataStore liniked to the engine.
commonConfig

object (CommonConfig)

Common config spec that specifies the metadata of the engine.
Union field engine_config. Additional config specs that defines the behavior of the engine. engine_config can be only one of the following:
similarDocumentsConfig

object (SimilarDocumentsEngineConfig)

Additional config specs for a similar-items engine.
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:
recommendationMetadata

object (RecommendationMetadata)

Output only. Additional information of a recommendation engine. Only applicable if solutionType is SOLUTION_TYPE_RECOMMENDATION.
chatEngineMetadata

object (ChatEngineMetadata)

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

SimilarDocumentsEngineConfig

This type has no fields.

Additional config specs for a similar-items engine.

ChatEngineConfig

Configurations for a Chat Engine.

JSON representation 
{
  "agentCreationConfig": {
    object (AgentCreationConfig)
  },
  "dialogflowAgentToLink": string
}
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.

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)
}
Fields
type

string

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

This field together with [optimizationObjective][Engine.optimization_objective] 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.

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.

RecommendationMetadata

Additional information of a recommendation engine.

JSON representation 
{
  "servingState": enum (ServingState),
  "dataState": enum (DataState),
  "lastTuneTime": string,
  "tuningOperation": string
}
Fields
servingState

enum (ServingState)

Output only. The serving state of the engine: ACTIVE, NOT_ACTIVE.
dataState

enum (DataState)

Output only. The state of data requirements for this engine: DATA_OK and DATA_ERROR.

Engine cannot be trained if the data is in DATA_ERROR state. Engine can have DATA_ERROR state even if serving state is ACTIVE: engines were trained successfully before, but cannot be refreshed because the underlying engine no longer has sufficient data for training.
lastTuneTime

string (Timestamp format)

Output only. The timestamp when the latest successful tune finished. Only applicable on Media Recommendation engines.

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".
tuningOperation

string

Output only. The latest tune operation id associated with the engine. Only applicable on Media Recommendation engines.

If present, this operation id can be used to determine if there is an ongoing tune for this engine. To check the operation status, send the operations.get request with this operation id in the engine resource format. If no tuning has happened for this engine, the string is empty.

ServingState

The serving state of the recommendation engine.

Enums
SERVING_STATE_UNSPECIFIED Unspecified serving state.
INACTIVE The engine is not serving.
ACTIVE The engine is serving and can be queried.
TUNED The engine is trained on tuned hyperparameters and can be queried.

DataState

Describes whether this engine have sufficient training data to be continuously trained.

Enums
DATA_STATE_UNSPECIFIED Unspecified default value, should never be explicitly set.
DATA_OK The engine has sufficient training data.
DATA_ERROR The engine does not have sufficient training data. Error messages can be queried via Stackdriver.

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

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

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.