Method: projects.locations.collections.engines.servingConfigs.recommend

提供建議，這需要情境式使用者事件。

HTTP 要求

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:recommend

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
servingConfig

string

這是必要旗標，ServingConfig 的完整資源名稱：projects/*/locations/global/collections/*/engines/*/servingConfigs/* 或 projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

建立推薦引擎時，系統會一併建立一個預設供應設定。引擎 ID 會做為預設放送設定的 ID。舉例來說，如果是引擎 projects/*/locations/global/collections/*/engines/my-engine，您可以將 projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine 用於 RecommendationService.Recommend 要求。

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
欄位
userEvent

object (UserEvent)

這是必要旗標，使用者相關背景資訊、使用者瀏覽的內容，以及使用者觸發 servingConfigs.recommend 要求所採取的動作。請注意，這項使用者事件詳細資料不會擷取至 userEvent 記錄。因此，記錄事件時必須另外提出 userEvent 寫入要求。

請勿為不同使用者將 UserEvent.user_pseudo_id 或 UserEvent.user_info.user_id 設為相同的固定 ID。如要接收非個人化推薦內容 (不建議，這可能會對模型效能造成負面影響)，請將 UserEvent.user_pseudo_id 設為隨機的專屬 ID，並將 UserEvent.user_info.user_id 設為未設定。
pageSize

integer

一頁的結果數上限，將這項屬性設為所需建議結果的數量。如果為零，服務會選擇合理的預設值。允許的最大值為 100。如果值大於 100，系統會將值設為 100。
filter

string

篩選條件，可限制建議結果，長度上限為 5,000 個字元。目前僅支援 filterTags 屬性的篩選運算式。

範例：

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

如果 params 欄位下的 attributeFilteringSyntax 設為 true，則系統會預期使用屬性運算式，而非上述以標記為基礎的語法。範例：

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

如果篩選器封鎖所有結果，API 會傳回一般 (未經篩選) 熱門文件。如果只希望搜尋結果完全符合篩選條件，請在 RecommendRequest.params 中將 strictFiltering 設為 true，這樣就會收到空白結果。

請注意，無論篩選條件為何，API 一律不會傳回 Document 含有 storageStatus 做為 EXPIRED 或 DELETED 的 EXPIRED。
validateOnly

boolean

請使用僅驗證模式查詢這項建議。如果設為 true，系統會使用傳回任意文件 ID 的偽模型。請注意，驗證模式僅適用於測試 API，或模型尚未準備就緒的情況。
params

map (key: string, value: value (Value format))

建議的其他網域專屬參數。

接受的值：

  • returnDocument：布林值，如果設為 true，相關聯的 Document 物件會傳回 RecommendResponse.RecommendationResult.document。
  • returnScore：布林值，如果設為 true，系統會在 RecommendResponse.RecommendationResult.metadata 中設定與每個傳回的 Document 對應的建議分數。這個分數代表在特定使用者情境和記錄下，文件轉換的機率。
  • strictFiltering：布林值，預設為 True。如果設為 false，當篩選器封鎖所有建議結果時，服務會傳回一般 (未篩選) 熱門文件，而非空白結果。
  • diversityLevel：字串。預設為空白。如果設為非空白，則必須是下列其中一項：
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity 這項功能可提供要求層級的控制權，並根據文件類別調整建議結果。
  • attributeFilteringSyntax：布林值，預設為 False。如果設為 true，系統會根據新的屬性式語法解讀 filter 欄位。
userLabels

map (key: string, value: string)

套用於資源的使用者標籤必須符合下列規定：

  • 每項資源可以有多個標籤，上限為 64 個。
  • 每個標籤都必須是鍵/值組合。
  • 鍵的長度必須至少為 1 個字元，最多 63 個字元，且不能空白。值可以空白，長度上限為 63 個字元。
  • 鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼，且可使用國際字元。
  • 標籤中的鍵部分不得重複，但可讓多個資源使用相同的鍵。
  • 鍵的開頭必須是小寫字母或國際字元。

詳情請參閱標籤規定。

回應主體

如果成功，回應主體會包含 RecommendResponse 的執行個體。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite

詳情請參閱Authentication Overview。

IAM 權限

需要 servingConfig 資源的下列 IAM 權限：

  • discoveryengine.servingConfigs.recommend

詳情請參閱 IAM 說明文件。