REST Resource: projects.locations.collections.engines

• 資源：引擎
  • JSON 表示法
• SimilarDocumentsEngineConfig
• ChatEngineConfig
  • JSON 表示法
• AgentCreationConfig
  • JSON 表示法
• SearchEngineConfig
  • JSON 表示法
• SearchTier
• SearchAddOn
• MediaRecommendationEngineConfig
  • JSON 表示法
• OptimizationObjectiveConfig
  • JSON 表示法
• TrainingState
• EngineFeaturesConfig
  • JSON 表示法
• RecommendedForYouFeatureConfig
  • JSON 表示法
• MostPopularFeatureConfig
  • JSON 表示法
• RecommendationMetadata
  • JSON 表示法
• ServingState
• DataState
• ChatEngineMetadata
  • JSON 表示法
• CommonConfig
  • JSON 表示法
• AppType
• FeatureState
• ConfigurableBillingApproach
• 方法

資源：引擎

描述 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: "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. }

欄位
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 只能是下列其中一項：
similarDocumentsConfig	object (SimilarDocumentsEngineConfig) similar-items 引擎的其他設定規格。
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 只能是下列其中一項：
recommendationMetadata	object (RecommendationMetadata) 僅供輸出。推薦引擎的其他資訊。只有在 solutionType 為 SOLUTION_TYPE_RECOMMENDATION 時才適用。
chatEngineMetadata	object (ChatEngineMetadata) 僅供輸出。Chat Engine 的其他資訊。只有在 solutionType 為 SOLUTION_TYPE_CHAT 時才適用。

SimilarDocumentsEngineConfig

這個類型沒有任何欄位。

similar-items 引擎的其他設定規格。

ChatEngineConfig

Chat Engine 的設定。

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

欄位
agentCreationConfig	object (AgentCreationConfig) 用來產生與這個引擎相關聯的 Dialogflow 虛擬服務專員。 請注意，這些設定只會由 Dialogflow 服務使用一次，並傳遞給該服務。也就是說，引擎建立後，就無法使用 EngineService.GetEngine 或 EngineService.ListEngines API 擷取這些資料。
dialogflowAgentToLink	string 要連結至這個 Chat Engine 的現有 Dialogflow 虛擬服務專員資源名稱。客戶可以提供 agentCreationConfig 來建立代理程式，也可以提供代理程式名稱，將代理程式連結至 Chat 引擎。 格式：projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>。 請注意，dialogflowAgentToLink 會由 Dialogflow 服務一次性使用並傳遞。也就是說，引擎建立後，就無法使用 EngineService.GetEngine 或 EngineService.ListEngines API 擷取這些資料。建立引擎後，請使用 ChatEngineMetadata.dialogflow_agent 建立實際的代理關聯。
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) 建議您使用引擎功能設定。
mostPopularConfig	object (MostPopularFeatureConfig) 最熱門的引擎功能設定。

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 引擎的必要項目。

RecommendationMetadata

推薦引擎的其他資訊。

JSON 表示法
{ "servingState": enum (ServingState), "dataState": enum (DataState), "lastTuneTime": string, "lastTrainTime": string, "tuningOperation": string }

欄位
servingState	enum (ServingState) 僅供輸出。引擎的服務狀態：ACTIVE、NOT_ACTIVE。
dataState	enum (DataState) 僅供輸出。這個引擎的資料規定狀態：DATA_OK和DATA_ERROR。 如果資料處於 DATA_ERROR 狀態，就無法訓練引擎。即使服務狀態為 ACTIVE，引擎仍可能處於 DATA_ERROR 狀態：引擎先前已成功訓練，但由於基礎引擎不再有足夠的訓練資料，因此無法重新整理。
lastTuneTime	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"。
lastTrainTime	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"。
tuningOperation	string 僅供輸出。與引擎相關聯的最新微調作業 ID。僅適用於媒體建議引擎。 如果存在，這個作業 ID 可用於判斷這個引擎是否有進行中的調整作業。如要查看作業狀態，請以引擎資源格式傳送 operations.get 要求，並附上這個作業 ID。如果這個引擎未經過任何微調，字串會空白。

ServingState

推薦引擎的服務狀態。

列舉
SERVING_STATE_UNSPECIFIED	未指定放送狀態。
INACTIVE	引擎未放送。
ACTIVE	引擎正在提供服務，且可接受查詢。
TUNED	引擎會根據調整後的超參數進行訓練，並可供查詢。

DataState

說明這個引擎是否有足夠的訓練資料，可持續接受訓練。

列舉
DATA_STATE_UNSPECIFIED	未指定的預設值，不應明確設定。
DATA_OK	引擎有足夠的訓練資料。
DATA_ERROR	引擎沒有足夠的訓練資料。您可以透過 Stackdriver 查詢錯誤訊息。

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。
getCompletionConfig	取得 CompletionConfig
getWorkspaceSettings	取得使用者的 Workspace 設定。
list	列出與專案相關聯的所有 Engine。
patch	更新 Engine
pause	暫停訓練現有引擎。
resume	繼續訓練現有引擎。
tune	調整現有引擎。
updateCompletionConfig	更新 CompletionConfig。