篩選建議

本頁說明如何使用產品屬性篩選建議結果。

您可以在預測要求中指定篩選運算式，篩選預測結果。篩選器運算式是針對每項產品評估的邏輯運算式。回應中的產品清單會縮小範圍，只列出運算式評估結果為 true 的產品。

建議篩選功能有兩個版本：

• 建議使用版本 2。
• 第 1 版已淘汰，但可能仍在使用中。

本操作指南中的章節僅適用於第 2 版篩選功能，這項功能會使用產品屬性篩選建議。

建議篩選器，第 2 版

第 2 版使用產品屬性。篩選運算式以產品屬性為依據。這些可以是預先定義的系統屬性，例如 categories 和 colors，也可以是您定義的自訂屬性，例如 attributes.styles。將產品屬性設為可篩選後，系統就能自動將這些屬性做為最佳化建議的篩選標記，不必手動新增篩選標記。

使用屬性篩選產品時，預測回應會傳回主要產品，其中至少包含一個主要或子類產品，且該產品的屬性值符合篩選運算式。如要進一步瞭解主要產品和子類產品，請參閱「產品層級」。

下列篩選器運算式範例也會篩選出設為「新品上市」但未設為促銷活動的紅色或藍色產品：

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

如要使用第 2 版的建議篩選功能，請按照下列程序操作。本頁稍後會說明各項程序。

1. 為模型啟用建議篩選功能，以便提供篩選後的建議。
2. 針對要篩選的產品屬性，開啟建議篩選功能。
3. 在預測要求中使用可篩選的產品屬性。

建議篩選器，第 1 版 (已淘汰)

第 1 版使用手動建立的篩選標記。篩選器運算式是以篩選器標記為依據，您必須手動將篩選器標記新增至目錄中要篩選的產品。

以下篩選運算式範例使用篩選標記，指定標記為「Red」或「Blue」的產品，以及標記「New-Arrival」，且未標記為「promotional」：

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

請參閱 Product.tags[] 欄位的 API 參考說明文件。

標記運算式可包含布林值運算子 OR 或 NOT，且必須以一或多個空格與標記值分隔。標記值也可以立即加上破折號 (-)，這等同於 NOT 運算子。使用布林運算子的標記運算式必須以括號括住。

除了標記，你也可以依 filterOutOfStockItems 篩選。 filterOutOfStockItems 旗標會篩除所有含有 stockState 的產品， OUT_OF_STOCK。

你可以合併標記篩選器和缺貨篩選器，這樣系統只會傳回符合所有指定篩選器運算式的項目。

篩選字串範例如下：

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

以下範例只會傳回有現貨且有 spring-sale 或 exclusive 標記 (或兩者都有)，但沒有 items-to-exclude 標記的項目。

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

屬性篩選器和標記篩選器相容性

如果模型同時有手動建立的標記和可篩選的產品屬性，則可使用任一版本的篩選條件來處理預測要求。不過，您無法在同一個預測要求中同時加入第 1 版和第 2 版的篩選運算式。

建議篩選限制

手動新增篩選條件，限制傳回給使用者的建議組合。 使用 Vertex AI Search for Commerce 套用業務規則，微調消費者能看見的資訊，包括依據產品供應情形、自訂代碼和其他條件進行篩選的選項。

每個可篩選的屬性都會在每個模型中耗用一些記憶體。下列限制有助於避免對放送成效造成負面影響：

• 你最多可以在目錄中將 10 個自訂屬性設為可篩選。

• 目錄中最多可有 100,000,000 個可篩選的屬性值。

  如要估算目錄中的屬性值總數，請將目錄中的產品數量乘以可篩選的屬性數量。

  舉例來說，如果目錄有 1,000 項產品，且有 3 個屬性設為可篩選，則屬性值的總數估計為 3*1000=3000。

  如果您同時使用第 1 版和第 2 版的建議篩選功能，篩選標記的數量會計入配額。請確認加到屬性值總數的篩選標記數量少於 100,000,000 個。

如果超出限制，您就無法將其他屬性設為可篩選。如需超出這些限制，請申請提高配額。

模型訓練期間會計算標記總數。如果總數超過上限，模型訓練就會失敗。如果在模型訓練期間找到超過 10 個可篩選的自訂屬性，系統只會使用 10 個。

建議篩選運算式語法

搜尋和建議的篩選運算式語法類似。不過，建議功能有幾項限制。

建議篩選運算式語法可歸納為下列 EBNF：

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  literal = double-quoted string;

  textual_field = see the tables below;

篩選器語法限制

相關限制如下：

• 括號中嵌入 AND 和 OR 運算子的深度有限。篩選器中的邏輯運算式必須採用合取正規形式 (CNF)。支援的最複雜邏輯運算式可以是僅包含 OR 運算子的子句 AND 連接清單，例如：(... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• 您可以使用 NOT 關鍵字或 - 否定運算式。這項功能僅適用於單一引數的 ANY() 運算式，且不包含廣告空間相關屬性。
• availability 限制必須位於頂層。無法做為 OR 子句或否定 (NOT) 的一部分。
• 由於標準建議篩選功能僅支援文字欄位，因此不支援小於、大於和範圍檢查作業。小於和大於運算子只能用於建議提升或隱藏控制條件，這些條件支援部分數值欄位 (請參閱「提升/隱藏支援的欄位」)。
• 頂層 AND 子句中的字詞數量上限為 20 個。
• OR 子句最多可有 100 個引數，這些引數會納入 ANY() 運算式。如果 OR 子句有多個 ANY() 運算式，這些運算式的引數都會計入上限。舉例來說，colors: ANY("red", "green") OR colors: ANY("blue") 有三個引數。

下表列出有效的篩選器運算式範例，以及無效範例和無效原因。

依商品目錄相關屬性篩選

系統會根據產品的即時狀態，篩選與商品目錄相關的屬性。如果是 availability: ANY("IN_STOCK") 篩選，預測回應會傳回主要產品，其中主要產品或子類產品具有相符的 IN_STOCK 值。如要進一步瞭解主要產品和子類產品，請參閱「產品層級」。系統不支援 Primary only 或 Variant only 篩選。

建議篩選條件第 2 版僅支援 IN_STOCK 這個 availability 屬性值。

商品目錄相關屬性可用於 AND 子句，但無法用於 OR 子句。

支援的欄位

下表匯總了支援的文字欄位。

推薦內容的升降級功能支援其他欄位，標準推薦內容篩選功能則不支援。如需這類欄位的清單，請參閱「支援的升級/隱藏欄位」。

支援提高/降低排名的欄位

升級/埋藏功能支援標準建議篩選器不支援的部分額外欄位，包括數值欄位。

除了「支援的欄位」中列出的欄位外，建議的升級/埋藏功能還支援下列欄位：

文字欄位

數值欄位

為模型設定建議篩選條件

如要啟用建議篩選功能，請使用 Search for commerce 控制台或 Models API 資源。

您可以在控制台中建立啟用建議篩選功能的新模型。您也可以更新現有模型的這個選項。

使用 Models API 資源，您可以建立啟用建議篩選功能的新模型，或使用 models.Patch 更新現有模型的這項設定。

請注意，如果傳回預測結果的放送設定已啟用類別比對，則篩選器無法使用「類別」屬性，因為回應只會傳回與情境產品共用類別的產品結果。

使用控制台設定模型的篩選條件

使用 Search for commerce 控制台建立模型時，選取「自動產生標記」選項，即可為該模型啟用建議篩選功能。

請仔細檢查是否與 diversity-level 和 category-match-level 等其他設定相容，因為系統會合併所有效果，並在最後進行篩選。

• 舉例來說，結合以規則為準的 diversity-level 和 category attribute filtering，經常會導致輸出內容空白。
  • diversity-level=high-diversity 會強制模型限制相同類別字串的結果數量上限。也就是說，類別 1 有 1 個結果，類別 2 有 1 個結果，依此類推。
  • 使用類別中繼資料 (Product.categories = ANY ("category2")) 篩選屬性時，模型會捨棄不相符的項目。
  • 最終輸出結果少於三項。
• 對於 similar-items 模型，預設 category-match-level = relaxed-category-match 已包含額外的類別關聯性提升功能。切換至 category-match-level=no-category-match 即可停用這項行為，並使用自訂篩選規則。

如需瞭解如何使用控制台建立建議模型，請參閱建立建議模型。

現有模型的這項設定無法在控制台中更新。如要更新模型的這項設定，請使用 models.Patch API 方法。

使用 API 設定模型篩選條件

建立新模型時，可以使用 models.Create 為模型啟用建議篩選功能；更新現有模型時，則可以使用 models.Patch。

如要允許篩選，請為模型設定 filteringOption 欄位。這個欄位允許的值如下：

• RECOMMENDATIONS_FILTERING_DISABLED (預設)：模型會關閉篩選功能。
• RECOMMENDATIONS_FILTERING_ENABLED：主要產品的篩選功能已開啟。

以下 curl 範例會建立新的模型，並啟用建議篩選功能。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

以下 curl 範例會更新現有模型的篩選選項設定。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

將屬性設為可篩選

如要篩選建議產品，請為篩選運算式中使用的產品屬性啟用篩選功能。你可以使用「搜尋」商務控制台或 Attributes API 資源更新這項設定。

請勿將過多屬性設為可篩選。可篩選的屬性數量設有限制。

使用控制台將屬性設為可篩選

您可以在「Search for commerce」控制台的控制項頁面中，將屬性設為可篩選。

1. 前往 Search for commerce 控制台的「Controls」頁面。
   
   前往「Controls」(控制項) 頁面

2. 前往「屬性控制項」分頁標籤。

   這個分頁會顯示所有產品屬性的表格，您可以在網站層級設定控管選項。

3. 按一下「修改控制項」edit。

4. 將產品屬性的「可篩選」設為「True」。

5. 按一下「儲存控制項」。

下一個模型訓練週期完成後，你就可以開始使用這項屬性進行篩選。

使用 API 將屬性設為可篩選

AttributesConfig 代表目錄的屬性清單。

為 CatalogAttribute 設定 AttributesConfig.filteringOption 欄位。這個欄位可用的值如下：

• RECOMMENDATIONS_FILTERING_DISABLED (預設)：系統會關閉屬性的篩選功能。
• RECOMMENDATIONS_FILTERING_ENABLED：已為屬性啟用篩選功能。

下列 curl 範例會查詢現有的產品屬性。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

以下 curl 範例會將產品屬性 categories 設為可篩選。

更新現有屬性時，請保留 indexableOption、dynamicFacetableOption 和 searchableOption 的原始屬性值，因為這些值會出現在上一個步驟中。如果查看 attributesConfig 時，所選屬性未如上例所示，請使用下列範例所示的預設設定。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

下一個模型訓練週期完成後，你就可以開始使用這項屬性進行篩選。這項作業通常至少需要八小時。

在預測要求中使用可篩選的屬性

模型重新訓練完成後，即可在預測要求中使用可篩選的產品屬性。

將要求參數值 filterSyntaxV2 設為 true，即可啟用第 2 版建議篩選功能。如果未設定這個參數，系統仍會啟用第 1 版的篩選功能。如果模型同時有手動建立的標記和可篩選的產品屬性，則可使用任一版本的篩選條件來處理預測要求。不過，您無法在同一個預測要求中同時加入第 1 版和第 2 版的篩選運算式。

以下部分 curl 範例顯示 filterSyntaxV2 設為 true，以及使用產品屬性 colors 和 categories 的篩選運算式。這個範例假設 colors 和 categories 設為可篩選。

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

以下 curl 範例顯示完整的預測要求。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

除了篩選器，放送設定的多元化設定也會影響回應傳回的結果數量。