REST Resource: projects.locations.collections.engines

資源：引擎

描述 Engine 訓練和服務參數的中繼資料。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "dataStoreIds": [
    string
  ],
  "solutionType": enum (SolutionType),
  "industryVertical": enum (IndustryVertical),
  "commonConfig": {
    object (CommonConfig)
  },
  "appType": enum (AppType),
  "disableAnalytics": boolean,
  "features": {
    string: enum (FeatureState),
    ...
  },
  "configurableBillingApproach": enum (ConfigurableBillingApproach),

  // 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.
}
欄位
name

string

不可變動。ID。引擎的完整資源名稱。

這個欄位必須是 UTF-8 編碼的字串，長度上限為 1024 個字元。

格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine} 引擎長度應為 1 至 63 個字元，有效字元為 /[a-z0-9][a-z0-9-_]*/。否則，系統會傳回 INVALID_ARGUMENT 錯誤。
displayName

string

這是必要旗標，引擎的顯示名稱。應為人類可讀的格式。採用 UTF-8 編碼的字串，最多 1024 個字元。
createTime

string (Timestamp format)

僅供輸出。建立建議引擎的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

僅供輸出。上次更新 Recommendation Engine 的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
dataStoreIds[]

string

(選用步驟) 與這個引擎相關聯的資料儲存庫。

SOLUTION_TYPE_SEARCH 和 SOLUTION_TYPE_RECOMMENDATION 類型的引擎最多只能與一個資料儲存庫建立關聯。

如果 solutionType 為 SOLUTION_TYPE_CHAT，則可在此處建立同一 Collection 中多個 DataStore 的關聯。

請注意，在 CreateEngineRequest 中使用時，必須提供一個 DataStore ID，系統會使用該 ID 進行必要的初始化作業。
solutionType

enum (SolutionType)

這是必要旗標，引擎的解決方案。
industryVertical

enum (IndustryVertical)

(選用步驟) 引擎註冊的產業別。引擎產業類別的限制依據 DataStore 而定：引擎上的產業類別必須與連結至引擎的 DataStore 產業類別相符。
commonConfig

object (CommonConfig)

指定引擎中繼資料的通用設定規格。
appType

enum (AppType)

(選用步驟) 不可變動。這是這個引擎資源代表的應用程式類型。注意：這是與現有產業垂直或解決方案類型無關的新概念。
disableAnalytics

boolean

(選用步驟) 是否要停用透過這個引擎執行的搜尋分析。
features

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

(選用步驟) 引擎的功能設定，可選擇啟用或停用功能。支援的索引鍵：

  • *：所有功能 (如有)，系統會忽略所有其他功能狀態設定。
  • 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
  • disable-agent-sharing
  • disable-image-generation
  • disable-video-generation
  • disable-onedrive-upload
  • disable-talk-to-content
  • disable-google-drive-upload
configurableBillingApproach

enum (ConfigurableBillingApproach)

(選用步驟) 可設定的帳單方式設定。
聯集欄位 engine_config。定義引擎行為的其他設定規格。engine_config 只能是下列其中一項：
chatEngineConfig

object (ChatEngineConfig)

Chat Engine 的設定。只有在 solutionType 為 SOLUTION_TYPE_CHAT 時才適用。
searchEngineConfig

object (SearchEngineConfig)

搜尋引擎的設定。只有在 solutionType 為 SOLUTION_TYPE_SEARCH 時才適用。
mediaRecommendationEngineConfig

object (MediaRecommendationEngineConfig)

媒體引擎的設定。僅適用於具有 solutionType SOLUTION_TYPE_RECOMMENDATION 和 IndustryVertical.MEDIA 垂直的資料儲存庫。
聯集欄位 engine_metadata。引擎中繼資料，可監控引擎狀態。engine_metadata 只能是下列其中一項：
chatEngineMetadata

object (ChatEngineMetadata)

僅供輸出。Chat Engine 的其他資訊。只有在 solutionType 為 SOLUTION_TYPE_CHAT 時才適用。

ChatEngineConfig

Chat Engine 的設定。

JSON 表示法 
{
  "agentCreationConfig": {
    object (AgentCreationConfig)
  },
  "dialogflowAgentToLink": string,
  "allowCrossRegion": boolean
}
欄位
agentCreationConfig

object (AgentCreationConfig)

用來產生與這個引擎相關聯的 Dialogflow 虛擬服務專員。

請注意，這些設定只會由 Dialogflow 服務使用一次，並傳遞給該服務。也就是說，引擎建立後，就無法使用 EngineService.GetEngine 或 EngineService.ListEngines API 擷取這些資料。
allowCrossRegion

boolean

(選用步驟) 如果旗標設為 true，我們允許代理程式和引擎位於不同位置，否則代理程式和引擎必須位於相同位置。這項標記預設為 false。

請注意，allowCrossRegion 會由 EngineService.CreateEngine 消耗並傳遞至 EngineService.CreateEngine，且只能使用一次。也就是說，引擎建立後，就無法使用 EngineService.GetEngine 或 EngineService.ListEngines API 擷取這些資料。

AgentCreationConfig

生成 Dialogflow 虛擬服務專員的設定。

請注意，這些設定只會由 Dialogflow 服務使用一次，並傳遞給該服務。也就是說，引擎建立後，就無法使用 EngineService.GetEngine 或 EngineService.ListEngines API 擷取這些資料。

JSON 表示法 
{
  "business": string,
  "defaultLanguageCode": string,
  "timeZone": string,
  "location": string
}
欄位
business

string

代理人代表的公司、機構或其他實體名稱。用於知識連接器 LLM 提示和知識搜尋。
defaultLanguageCode

string

這是必要旗標，代理程式的預設語言，以語言標記表示。如需目前支援的語言代碼清單，請參閱語言支援一文。
timeZone

string

這是必要旗標，代理程式的時區 (來自時區資料庫)，例如 America/New_York、Europe/Paris。
location

string

建立代理程式時的代理程式位置，支援的值為：global/us/eu。如未提供，美國引擎預設會使用 us-central-1 建立代理程式；歐盟引擎預設會使用 eu-west-1 建立代理程式。

SearchEngineConfig

搜尋引擎的設定。

JSON 表示法 
{
  "searchTier": enum (SearchTier),
  "searchAddOns": [
    enum (SearchAddOn)
  ]
}
欄位
searchTier

enum (SearchTier)

這個引擎的搜尋功能層級。

不同層級的價格可能不同。詳情請參閱定價說明文件。

如未指定，則預設值為 SearchTier.SEARCH_TIER_STANDARD。
searchAddOns[]

enum (SearchAddOn)

這個搜尋引擎啟用的外掛程式。

SearchTier

搜尋功能層級。不同層級的價格可能不同。詳情請參閱定價說明文件。

列舉
SEARCH_TIER_UNSPECIFIED 未指定列舉時的預設值。無法使用。
SEARCH_TIER_STANDARD 標準級。
SEARCH_TIER_ENTERPRISE Enterprise 級別。

SearchAddOn

外掛程式，可提供額外的搜尋功能。

列舉
SEARCH_ADD_ON_UNSPECIFIED 未指定列舉時的預設值。無法使用。
SEARCH_ADD_ON_LLM 大型語言模型外掛程式。

MediaRecommendationEngineConfig

媒體推薦引擎的其他設定規格。

JSON 表示法 
{
  "type": string,
  "optimizationObjective": string,
  "optimizationObjectiveConfig": {
    object (OptimizationObjectiveConfig)
  },
  "trainingState": enum (TrainingState),
  "engineFeaturesConfig": {
    object (EngineFeaturesConfig)
  }
}
欄位
type

string

這是必要旗標，引擎類型，例如recommended-for-you。

這個欄位和 optimizationObjective 會說明用來控管引擎訓練和服務的引擎中繼資料。

目前支援的值：recommended-for-you、others-you-may-like、more-like-this、most-popular-items。
optimizationObjective

string

最佳化目標，例如cvr。

這個欄位和 optimizationObjective 會說明用來控管引擎訓練和服務的引擎中繼資料。

目前支援的值：ctr、cvr。

如未指定，我們會根據引擎類型選擇預設值。預設值取決於最佳化建議類型：

recommended-for-you => ctr

others-you-may-like => ctr
optimizationObjectiveConfig

object (OptimizationObjectiveConfig)

轉換率最佳化目標的自訂門檻名稱和值。如果是 targetField watch-time，target_field_value 必須是介於 (0, 86400] 之間的整數值，表示媒體進度時間 (以秒為單位)，例如 90)。如果是 targetField watch-percentage，target_field_value 必須是介於 (0, 1.0] 的有效浮點值 (不含 0，含 1.0)，例如 0.5)。
trainingState

enum (TrainingState)

引擎的訓練狀態 (例如 TRAINING 或 PAUSED)。

因為執行服務的部分費用取決於訓練頻率，因此可用於決定何時訓練引擎，以控管成本。如未指定：engines.create 方法的預設值為 TRAINING。engines.patch 方法的預設值是維持先前的狀態。
engineFeaturesConfig

object (EngineFeaturesConfig)

(選用步驟) 其他引擎功能設定。

OptimizationObjectiveConfig

cvr optimizationObjective 的自訂門檻。

JSON 表示法 
{
  "targetField": string,
  "targetFieldValueFloat": number
}
欄位
targetField

string

這是必要旗標，要指定目標的欄位名稱。目前支援的值：watch-percentage、watch-time。
targetFieldValueFloat

number

這是必要旗標，要套用至目標的門檻 (例如0.5)。

TrainingState

引擎的訓練狀態。

列舉
TRAINING_STATE_UNSPECIFIED 未指定訓練狀態。
PAUSED 引擎訓練已暫停。
TRAINING 引擎正在訓練。

EngineFeaturesConfig

所選引擎類型的更多功能設定。

JSON 表示法 
{

  // 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.
}
欄位
聯集欄位 type_dedicated_config。套用至特定類型媒體建議引擎的功能相關設定。type_dedicated_config 只能是下列其中一項：
recommendedForYouConfig

object (RecommendedForYouFeatureConfig)

建議您使用引擎功能設定。

RecommendedForYouFeatureConfig

建立 recommended-for-you 引擎的其他功能設定。

JSON 表示法 
{
  "contextEventType": string
}
欄位
contextEventType

string

引擎在預測時查詢的事件類型。如果設為 generic，則只會使用 view-item、media-play 和 media-complete 做為引擎訓練中的 context-event。如果設為 view-home-page，除了 view-item、media-play 和 media-complete 之外，view-home-page 也會做為 context-events 使用。目前支援 recommended-for-you 引擎。目前支援的值：view-home-page、generic。

MostPopularFeatureConfig

建立「最受歡迎」引擎時必須進行的功能設定。

JSON 表示法 
{
  "timeWindowDays": string
}
欄位
timeWindowDays

string (int64 format)

引擎在訓練和預測期間接受查詢的時間範圍。只能使用正整數。這個值會轉換為過去 X 天的事件。目前是 most-popular-items 引擎的必要項目。

ChatEngineMetadata

Chat Engine 的額外資訊。這個訊息中的欄位僅供輸出。

JSON 表示法 
{
  "dialogflowAgent": string
}
欄位
dialogflowAgent

string

Chat Engine 參照的 Dialogflow 虛擬服務專員資源名稱。

格式：projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>。

CommonConfig

引擎的常見設定。

JSON 表示法 
{
  "companyName": string
}
欄位
companyName

string

與引擎相關聯的公司、商家或實體名稱。設定這項資訊有助於提升 LLM 相關功能。

AppType

引擎的應用程式。

列舉
APP_TYPE_UNSPECIFIED 所有未指定的應用程式。
APP_TYPE_INTRANET 適用於內部網路搜尋和 Agentspace 的應用程式類型。

FeatureState

引擎的特徵狀態。

列舉
FEATURE_STATE_UNSPECIFIED 未指定功能狀態。
FEATURE_STATE_ON 這項功能已開啟，因此可供存取。
FEATURE_STATE_OFF 這項功能已關閉，因此無法存取。

ConfigurableBillingApproach

可設定的帳單方式設定。

列舉
CONFIGURABLE_BILLING_APPROACH_UNSPECIFIED 預設值。適用於 Spark 和非 Spark 的不可設定帳單方式。一般定價模式。
CONFIGURABLE_BILLING_APPROACH_ENABLED 帳單結算方式會依據客戶指定的設定。

方法

create

 建立 Engine。

delete

 刪除 Engine。

get

 取得 Engine。

list

 列出與專案相關聯的所有 Engine。

patch

 更新 Engine