關於產品屬性

AI Commerce Search 可使用產品屬性進行索引、動態 facet、可搜尋性、篩選和模型品質。本頁說明如何設定產品屬性，以及系統如何根據您使用的方法和設定處理這些屬性。

屬性類型

產品屬性的預設設定和允許的選項會因類型而異。

• 系統屬性：預先定義的系統屬性是現有的Product欄位，可提供產品的更多資訊。包括品牌、供應情形、顏色和尺寸等產品屬性。如要查看產品的所有可用系統屬性，請參閱Product參考文件。

• 自訂屬性：自訂屬性是您使用 Product.attributes 欄位定義的額外屬性。例如商店名稱、供應商或風格。如需自訂屬性的範例和限制，請參閱Product.attributes參考文件。

  以下列舉前 20 項自訂屬性的範例：

  • 這項產品所屬的產品系列
  • 這項產品的店內銷售量
  • 服飾場合
  • 適用於這項產品的特惠和優待券
  • 整個網站產品熱銷程度
  注意： 系統每月會更新前 20 個所選自訂屬性。所選屬性會顯示在 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search「控制項」頁面。如要存取，請點選「控制項」頁面上的「屬性控制項」分頁標籤。

• 商品目錄層級屬性：系統或自訂屬性，可提供產品的商店層級資訊。如果產品的屬性在商店和區域之間差異很大，例如雜貨商品，或是產品有商店專屬的促銷活動，你可能會使用店內屬性。

  inventories.price 和 inventories.originalPrice 是 AI Commerce Search 預先定義的數值系統屬性。您可以建立自訂的商品目錄層級屬性，這些屬性可以是文字或數字。廣告空間層級屬性預設為可建立索引。系統不支援為庫存層級屬性設定可搜尋和動態商情項目使用。

注意： 強烈建議在 Product 中提供預先定義的系統屬性值，例如品牌、顏色和尺寸。你也可以加入使用 Product.attributes 定義的自訂屬性。

可用的屬性設定

屬性設定會影響整個網站的搜尋和推薦行為。

設定	說明	系統屬性	自訂屬性	廣告空間層級屬性
可搜尋性	這個屬性可透過搜尋查詢搜尋，有助於提高該屬性的回想率 (僅限文字屬性)。	一律開啟 (僅限文字)	預設為停用 (可啟用，但僅限文字)	不支援
可索引性	搜尋功能可使用這項屬性進行篩選和 facet。	一律開啟	預設為啟用 (可停用)	系統：一律開啟 自訂：預設為開啟 (可停用)。
動態 facet 處理	根據過去的使用者行為 (例如 facet 點擊和瀏覽次數)，搜尋功能可自動將這項屬性做為動態 facet 使用 (僅限文字屬性)。	預設為啟用 (如果 indexability = True) (可以停用)。	預設為啟用 (如果 indexability = True) (可以停用)。	不支援
可篩選 (預先發布版)	這項屬性可用於 Recommendations AI 篩選運算式。這項控制項僅適用於文字屬性。	預設為停用 (可為文字啟用，但 FulfillmentInfo 和 Title 除外)。	預設為停用 (可為文字啟用)	僅支援 availability=IN_STOCK
完全比對	這項屬性僅適用於文字自訂屬性。如要啟用可精確搜尋的項目，必須將可建立索引的項目設為啟用。	不支援	預設為停用 (可啟用)	不支援

搜尋功能會使用下列屬性設定：

• 可建立索引：搜尋功能可使用這項屬性篩選及建立 facet。
• 動態 facet 處理：搜尋功能可根據過去的使用者行為 (例如點擊和瀏覽 facet)，自動將這個屬性做為動態 facet 使用。如要為屬性啟用動態分面，必須將該屬性的 Indexable 設為 true。
• 可供搜尋：這個屬性可透過搜尋查詢搜尋，有助於提高該屬性的召回率。這項控制項僅適用於文字屬性。
• 可擷取：如果設為 true，搜尋功能會在搜尋查詢的回應中傳回這項屬性。如果所有屬性都將「可擷取」設為 false，搜尋結果只會顯示產品名稱，或是 (如果是子類) 產品名稱和顏色資訊。產品的 REST 欄位 RetrievableFields 已淘汰。請改用可擷取的整個網站控制項。

建議會使用下列屬性設定：

• 可篩選 (公開測試版)：這個屬性可用於建議篩選運算式。這項控制項僅適用於文字屬性。

可建立索引

如果屬性設為可建立索引，搜尋功能就能使用該屬性進行篩選和 facet。

• 系統屬性：預先定義的系統屬性一律會啟用索引功能。系統屬性無法停用這項設定。
• 自訂屬性：預設為啟用。您可以停用任何自訂屬性的索引功能。如果您打算將自訂屬性設為可編入索引，就必須遵循 [a-zA-Z0-9][a-zA-Z0-9_]* 規則運算式模式。例如 key0LikeThis 或 KEY_1_LIKE_THIS。
• 庫存層級屬性：系統庫存層級屬性一律會啟用這項設定，且無法變更。自訂庫存層級屬性預設為啟用，但可以關閉這項設定。
• 依附元件：不適用

匯入目錄資料後，索引設定變更會立即生效。否則變更最多可能需要 12 小時才會生效。您可以在「評估」頁面測試變更是否已套用。

動態 facet 處理

為屬性啟用動態 facet 處理後，搜尋功能就能將該屬性做為動態 facet。系統會根據使用者過去的行為 (例如點擊和瀏覽的分類) 自動將動態分類加入搜尋結果。

• 系統屬性：如果可索引性設為 true，系統預設會啟用這項屬性。你可以停用任何系統屬性的動態商情項目。
• 自訂屬性：如果可建立索引設為 true，系統預設會啟用這項功能。您可以針對任何自訂屬性停用動態 facet 處理。
• 目錄層級屬性：不支援。
• 依附元件：如要為屬性啟用動態切面，必須先為該屬性啟用索引功能。

屬性的動態 facet 處理設定一律為全域設定。你套用至該屬性的動態 facet 處理設定，會用於目錄中所有使用該屬性的產品。

動態商情項目設定變更最多需要兩天才能生效。您可以在「評估」頁面測試變更是否已套用。

如果是數值自訂屬性，則必須在要求中指定範圍。系統不會自動將數值分組。

可供搜尋

如果屬性設為可供搜尋，搜尋查詢中該屬性的召回率會提高。

只有文字屬性值可以啟用搜尋功能。不適用於數值屬性。

• 系統屬性：Product 的預先定義文字系統屬性，其可搜尋性設定由 AI Commerce Search 設定。這些設定無法變更。
• 自訂屬性：預設為停用。您可以為任何文字自訂屬性啟用這項設定。
• 目錄層級屬性：不支援。
• 依附元件：不適用
• 可精確搜尋：針對與目錄中任何產品相符的搜尋查詢，傳回目標搜尋結果。這個選項很適合序號。進一步瞭解可精確搜尋的選項。

雖然設為可供搜尋的產品較有可能顯示在該屬性的搜尋結果中，但並不保證一定會顯示。

篩選建議

預先發布版： 這項功能為公開預先發布版。

雖然系統最多只能從變體匯總 10 個可篩選的屬性，並納入建議的主要產品，但如果屬性已啟用建議篩選功能，就能在建議篩選運算式中使用，篩選預測中的產品。

• 系統屬性：預設為關閉。您可以為任何預先定義的系統文字屬性啟用這項設定 (Product 除外)，但 FulfillmentInfo 和 title 除外。不支援數值屬性。
• 自訂屬性：預設為關閉。你可以為任何自訂文字屬性開啟這項設定 Product。不支援數值屬性。
• 店內商品目錄層級屬性：僅支援 availability 值 IN_STOCK。
• 依附元件：不適用

可精確搜尋的選項

您可以為特定字串查詢的 exact-searchable 選項 (目錄屬性欄位) 提供特定值。如果查詢與目錄中的任何產品相符，且該欄位的值是查詢中提供的字串，系統就會在搜尋查詢中傳回該產品。這個選項很適合用於序號，讓消費者獲得精準的搜尋體驗。

通常對於自訂屬性，ExactSearchableOption 欄位適用於具有確切值的產品屬性 (例如 ModelId 或 ManufacturerId)。product_id 等屬性是主要索引欄位，預設可進行確切搜尋。系統一律會為完全比對啟用 item_id 欄位，且無法停用。

• 為避免在搜尋結果中傳回不相關的項目，請勿將可搜尋選項設為一般值，例如 battery。
• 為避免搜尋查詢服務不足，請勿將 tag 等特殊欄位設為可完全搜尋，因為這類欄位可能含有「iphone」等字串值。這麼做可能會導致這些查詢限制產品目錄中所有 iPhone 的結果。

詳情請參閱「關於產品屬性」。

屬性設定最佳做法

請務必瞭解這些最佳做法，因為當中會說明如何正確為自訂屬性建立索引，並提醒你某些語言剖析機制可能會影響屬性的可搜尋性。

• 處理英數字元 (零件編號或 SKU)：由於預設語言分析會針對自然語言進行最佳化，因此可能會從零件編號中移除連字號 (-) 等特殊字元 (例如將 part-123 轉換為 part 和 123)。如要讓這些字元可供搜尋，請務必使用 exact-searchable 屬性標記。
• n-gram 解決方法：如果型號非常複雜，含有特殊字元，最佳做法是在擷取前，先在自己的資料管道中將字串分成 n-gram，然後將原始字串儲存在標示為 exact searchable: true 的自訂屬性中。這會強制對 n 元片段進行嚴格比對。
• 自訂屬性鍵限制：自訂屬性鍵不得包含連字號或特殊字元。如要建立索引，鍵必須嚴格符合規則運算式模式 [a-zA-Z0-9][a-zA-Z0-9_]*。詳情請參閱「關於產品屬性」頁面。
• UTF-8 規定：所有字串屬性和值都必須是有效的 UTF-8 編碼字串。

屬性行為

使用主要和子類產品標示建構產品目錄時，請瞭解系統如何處理產品屬性以進行篩選。他們的行為取決於您使用的是搜尋或建議，以及目錄分類的設定方式。

為確保篩選行為可預測且準確，請在主要和子類產品中，維持可篩選屬性定義的一致性和完整性。這種做法有助於精確篩選，進而提升產品探索和搜尋關聯性。

搜尋與推薦功能中的主要變體行為

雖然搜尋和推薦結果只會顯示主要項目，但 AI Commerce Search 會盡量提供高品質的搜尋和推薦結果。

• 對於搜尋模型，變體屬性會用於搜尋索引中的主要產品。搜尋結果會根據主要產品的子類屬性，顯示多種選項。

• 如果是推薦模型，產品詳細資料和屬性不會從主要產品繼承至子類產品。為確保推薦內容品質，主要產品和子類產品的product.categories、product.title、product.attributes 和 product.prices 等主要屬性，必須提供完整且正確的詳細資料。

在建立索引和篩選期間處理屬性

如果主要和子類中定義了相同屬性，子類中的屬性就會成為篩選條件。舉例來說，假設你為主要產品及其子類 (顏色或尺寸) 定義了屬性，子類屬性值主要用於篩選，系統會檢查主要子類是否有任何屬性值相符。以產品供應情形為例：主要產品可以標示為 out-of-stock，但如果至少有一個子類標示為 in-stock，只要套用 in-stock 篩選器，主要產品就會顯示在搜尋結果中。

• 篩選時會優先採用子類屬性。如果主要產品及其子類都定義了屬性，系統會使用子類的屬性進行篩選。舉例來說，如果主要產品有預留位置顏色，但子類有實際顏色，系統應填入子類的顏色，並用於篩選。

• 如果是供應情形等與庫存相關的屬性，如果主要產品有子類，主要產品的供應情形應設為 OUT_OF_STOCK，而實際供應情形 (例如 IN_STOCK) 應設於子類層級。這樣一來，只要至少有一個子類別有現貨，主要產品就會視為有現貨。如果是這樣，availability: ANY("IN_STOCK") 等篩選器會正確傳回主要產品。

• 使用篩選運算式時，預測回應會傳回至少有一個主要或子類產品符合篩選器屬性值的主要產品。

用於篩選的選用屬性

請確保 categories 欄位乾淨，並針對分類方式進行最佳化。如需更多篩選條件，請根據廣泛類別使用個別自訂屬性實作，而非在 categories 欄位中實作。這樣做也能避免對類別建議的自動完成訓練造成負面影響。

舉例來說，假設您通常會設定 [lvl1, lvl1>lvl2, lvl1>lvl2>lvl3] 等類別來篩選。自動完成功能會計算特定查詢最常出現的類別，因此建議的類別會是 lvl1 和 lvl2 (所有產品)。

屬性行為最佳做法

如果目錄包含主要產品和子類產品，且兩者都定義了相同屬性，系統會以子類產品的屬性進行篩選。

• 正確填寫屬性：請確保主要產品和子類產品的屬性詳細資料完整且正確，尤其是用於篩選的屬性，以發揮最大效益。

• 使用內建欄位：請勿只使用自訂屬性。將產品資訊對應至內建的 Product 欄位 (brands、colors、sizes 和必填欄位)。內建欄位對可搜尋性、可索引性及關聯性最佳化有較大影響。自訂屬性 (Product.attributes) 適用於不符合預先定義系統屬性的產品資料。

• 設定整個網站可擷取的欄位控制項：API 支援變體的 variantRollupKeys，可讓您在搜尋回應中擷取詳細資料。

  注意： 如果您使用搜尋功能，Product.retrievableFields (搜尋回應中包含產品屬性) 已淘汰。使用可擷取的整個網站控制項。

• 目錄語言一致：產品目錄應僅使用一種語言，且搜尋查詢應以相同語言傳送。如果目錄中有多種語言，可能會降低模型效能。如果未設定語言代碼，可能會影響拼字修正等功能。

• 價格資訊：請正確填寫主要和子類產品的價格資訊，確保系統提供準確的建議和篩選功能。如果產品缺少產品層級的價格，且僅依賴店面商品目錄價格，請填寫主要產品的價格，並以商品目錄層級價格的中位數為準。

設定模式

設定模式會決定屬性設定的處理方式，以及您可以設定的屬性設定。

• 目錄層級設定模式 (預設)：在這個模式中，目錄層級的屬性設定會做為事實來源。
• 產品層級設定模式 (已淘汰)：在這個模式中，系統會使用產品層級的屬性設定做為可靠資料來源。

先前預設模式為產品層級設定。如果目前仍處於產品層級設定模式，但需要切換至目錄層級設定模式，請與支援團隊聯絡。切換後，搜尋服務不支援返回產品層級設定模式。

如要查看設定模式，請前往 Gemini Enterprise for Customer Experience 控制台的「AI Commerce Search」 「控制項」頁面。如果「可編入索引」選項顯示在「整個網站控制項」分頁的資料欄中，表示設定模型為目錄層級。如果「全網站控制項」分頁中沒有「可編入索引」欄，表示設定模型為產品層級。

設定方法

您可以透過下列方式設定屬性：

• Gemini Enterprise for Customer Experience 控制台中的 AI Commerce Search：在 Gemini Enterprise for Customer Experience 控制台中使用 AI Commerce Search，在目錄層級設定屬性設定。這項設定會為所有產品設定全域屬性。管理控制台提供的設定取決於設定模式。如要進一步瞭解如何在管理中心設定屬性，請參閱下一節。

• AttributeConfig API 方法：使用 API 在目錄層級設定屬性。這會設定所有產品的屬性。

• Product API 方法 (已淘汰)：使用 Product API 方法在產品層級設定自訂屬性。新使用者無法使用這個方法設定屬性，因此不建議使用。

在控制台中設定屬性

如要為所有產品全域設定屬性選項，請前往 Gemini Enterprise for Customer Experience 控制台的 AI Commerce Search 「控制項」頁面，然後點選「整個網站控制項」分頁標籤。如要進一步瞭解如何在管理中心中設定這項功能，請參閱「管理整個網站屬性控制項」。

如要使用這項功能，設定模式必須為目錄層級。

如為可建立索引和可供搜尋的項目，屬性設定變更會在擷取目錄時立即生效。否則，變更最多可能需要 12 小時才會生效。您可以在「評估」頁面測試變更是否已套用。

使用 AttributesConfig 設定屬性

AttributesConfig API 資源可讓您在目錄層級管理屬性設定。

下列欄位會在目錄層級設定屬性選項：

• CatalogAttribute.indexableOption：為屬性設定可建立索引的選項。
• CatalogAttribute.dynamicFacetableOption：為屬性設定動態切面選項。
• CatalogAttribute.searchableOption：為屬性設定可搜尋的選項。
• CatalogAttribute.recommendationsFilteringOption (公開測試版)：設定屬性的建議篩選選項。

如要擷取所有屬性設定，請使用 GetAttributesConfig 方法。

更新多個屬性

使用 updateAttributesConfig 方法，在目錄層級更新多個屬性。

要求中包含的目錄屬性會在目錄中更新，或在不存在時插入。如果目錄屬性欄位沒有值，系統會指派預設值。

要求中允許的目錄屬性數量上限為 1000 個。

更新個別屬性

下列方法可用來更新個別目錄屬性：

• AddCatalogAttribute：將個別屬性設定新增至目錄屬性。

  請參閱 AddCatalogAttribute 的 API 參考文件。

• ReplaceCatalogAttribute：修改個別屬性設定。 這會更新目錄屬性，以相同 CatalogAttribute.key 取代 AttributesConfig 中的指定 CatalogAttribute。

  請參閱 ReplaceCatalogAttribute 的 API 參考文件。

• RemoveCatalogAttribute：從 AttributesConfig 移除個別屬性設定。

  只有產品未使用的 CatalogAttributes 才能刪除。如果正在使用 CatalogAttribute，RemoveCatalogAttribute 不會刪除該項目，但會將其設定屬性重設為預設值。如果任何產品使用該屬性，CatalogAttribute.inUse 會設為 True。

  請參閱 RemoveCatalogAttribute 的 API 參考文件。

已淘汰

使用 Product 方法設定屬性

新使用者無法使用這種方法設定屬性，因此不建議採用。

下列欄位會使用 Product API 方法，為特定產品設定可建立索引和可搜尋的設定：

• Product.attributes.indexable。
• Product.attributes.searchable。僅適用於自訂屬性。

命名及建構自訂屬性的最佳做法

將產品資料擴展至預先定義的結構定義時，自訂屬性的命名和格式會直接影響 AI 商務搜尋的索引、擷取和分類產品能力。

請按照下列最佳做法操作，確保搜尋成效達到最佳狀態，並避免驗證錯誤：

1. 優先使用原生系統屬性。建立自訂屬性前，請確認是否有適用於資料的預設系統屬性 (例如 brands、colorInfo、sizes 或 materials)。後端 AI 模型比自訂屬性更瞭解預設欄位，並會將這些欄位納入關聯性和召回率最佳化作業。

   • 示例：請勿將品牌資訊做為 Product.attributes.brand 傳遞。而是直接對應至預設的 Product.brands 欄位。儲存專屬特定資料的自訂屬性，例如 Product.attributes.sleeve_length。

2. 嚴格遵守可索引性的命名慣例。如要使用自訂屬性進行篩選、分面或提升，必須將其標示為 Indexable。如要建立索引，自訂屬性鍵必須符合規則運算式模式 [a-zA-Z0-9][a-zA-Z0-9_]*。

   • 有效命名：sleeve_length 或 KEY_1_LIKE_THIS。
   • 命名無效：sleeve-length (不允許使用連字號，否則無法建立索引)。
   • 限制：屬性鍵必須是 UTF-8 編碼的字串，長度上限為 128 個字元。單一產品最多可有 200 個自訂屬性。

3. 定義明確的值類型 (文字或數字)。AI Commerce Search 嚴格規定自訂屬性值必須定義為文字 (text) 或數值 (numbers)。您必須為指定鍵設定其中一種型別，如果嘗試為相同屬性同時填入 text 和 numbers，系統會傳回 INVALID_ARGUMENT 錯誤。

   • 文字屬性：每個屬性最多可有 400 個值。不得使用空字串 ("")。每個值都必須是不含空白字元的 UTF-8 字串，長度上限為 256 個半形字元。
   • 數值屬性：每個屬性最多可有 400 個值。
   • 分面考量：如要將數值屬性做為 dynamicFacet，必須先在資料管道中將數值型資料類型轉換為 Text 字串，再進行擷取 (例如將 10.99 做為 "10.99" 傳遞)。否則，數值屬性只能做為靜態分面，您必須在搜尋要求中手動明確定義間隔值區。

4. 善用完全比對。可精確搜尋的設定適用於沒有語言意義的特定英數字串，例如 model_name (如 "WA2300AH3000") 或 part_number。

   • 範例：如果自訂屬性包含常見的英文名詞或熱門品牌，請不要套用完全比對。這麼做會限制搜尋結果，導致產品召回率偏低，並對點閱率造成負面影響。