Memfilter rekomendasi

Halaman ini menjelaskan cara memfilter hasil untuk rekomendasi menggunakan atribut produk.

Anda dapat memfilter hasil prediksi dengan menentukan ekspresi filter dalam permintaan prediksi. Ekspresi filter adalah ekspresi logis yang dievaluasi untuk setiap produk. Daftar produk dalam respons dipersempit menjadi produk yang ekspresinya bernilai benar.

Catatan: Pembaruan ekspresi tag dapat memerlukan waktu hingga delapan jam agar tersedia untuk digunakan dalam memfilter prediksi dengan v1 dan v2, termasuk untuk konfigurasi atribut untuk pemfilteran dan perubahan metadata tingkat produk. Hanya kolom Availability yang memiliki pembaruan real-time.

Ada dua versi pemfilteran untuk rekomendasi:

• Versi 2 direkomendasikan.
• Versi 1 tidak digunakan lagi, tetapi mungkin masih digunakan.

Bagian dalam panduan cara ini hanya berlaku untuk pemfilteran versi 2, yang memfilter rekomendasi menggunakan atribut produk.

Pemfilteran rekomendasi, versi 2

Versi 2 menggunakan atribut produk. Ekspresi filter didasarkan pada atribut produk. Atribut ini dapat berupa atribut sistem yang telah ditentukan, seperti categories dan colors, atau atribut kustom yang Anda tentukan, seperti attributes.styles. Saat Anda menetapkan atribut produk sebagai dapat difilter, rekomendasi kemudian dapat otomatis menggunakan atribut tersebut sebagai tag untuk pemfilteran rekomendasi, sehingga Anda tidak perlu menambahkan tag filter secara manual.

Saat Anda menggunakan atribut untuk memfilter produk, respons prediksi akan menampilkan produk utama yang berisi setidaknya satu produk utama atau varian yang memiliki nilai atribut yang cocok dengan ekspresi filter. Untuk mengetahui informasi selengkapnya tentang produk utama dan varian, lihat Tingkat produk.

Contoh ekspresi filter berikut juga memfilter produk merah atau biru yang ditetapkan sebagai "New-Arrival" dan tidak ditetapkan sebagai promosi:

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

Untuk menggunakan pemfilteran versi 2 untuk rekomendasi, ikuti prosedur berikut. Setiap prosedur akan diberikan nanti di halaman ini.

1. Aktifkan pemfilteran rekomendasi untuk model yang akan menayangkan rekomendasi yang difilter.
2. Aktifkan pemfilteran rekomendasi untuk atribut produk yang akan Anda filter.
3. Gunakan atribut produk yang dapat difilter dalam permintaan prediksi.

Pemfilteran rekomendasi, versi 1 (tidak digunakan lagi)

Versi 1 menggunakan tag filter yang dibuat secara manual. Ekspresi filter didasarkan pada tag filter, yang harus Anda tambahkan secara manual ke produk mana pun dalam katalog yang akan Anda filter.

Contoh ekspresi filter berikut menggunakan tag filter untuk menentukan produk yang diberi tag sebagai "Red" atau "Blue", serta tag "New-Arrival", dan tidak diberi tag sebagai "promotional":

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

Lihat dokumentasi referensi API untuk kolom Product.tags[].

Ekspresi tag dapat berisi operator boolean OR atau NOT, yang harus dipisahkan dari nilai tag dengan satu atau beberapa spasi. Nilai tag juga dapat langsung diawali dengan tanda hubung (-), yang setara dengan operator NOT. Ekspresi tag yang menggunakan operator boolean harus diapit tanda kurung.

Selain tag, Anda dapat memfilter berdasarkan filterOutOfStockItems. Flag filterOutOfStockItems memfilter produk apa pun dengan stockState OUT_OF_STOCK.

Anda dapat menggabungkan filter tag dan filter produk yang tidak tersedia sehingga hanya item yang memenuhi semua ekspresi filter yang ditentukan yang akan ditampilkan.

Beberapa contoh string filter:

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

"filter": "filterOutOfStockItems"

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

Contoh berikut hanya menampilkan item yang tersedia yang memiliki tag spring-sale atau exclusive (atau keduanya) dan juga tidak memiliki tag items-to-exclude.

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

Kompatibilitas filter atribut dan filter tag

Jika model memiliki tag yang dibuat secara manual dan atribut produk yang dapat difilter, model tersebut dapat menayangkan permintaan prediksi menggunakan salah satu versi pemfilteran. Namun, Anda tidak dapat menyertakan ekspresi pemfilteran v1 dan pemfilteran v2 dalam permintaan prediksi yang sama.

Batas pemfilteran rekomendasi

Tambahkan kriteria filter secara manual untuk membatasi kumpulan rekomendasi yang ditampilkan kepada pengguna akhir. Gunakan AI Commerce Search untuk menerapkan aturan bisnis guna menyesuaikan apa yang dilihat pelanggan, termasuk opsi untuk memfilter berdasarkan ketersediaan produk, tag khusus, dan kriteria lainnya.

Setiap atribut yang dapat difilter menggunakan sejumlah memori di setiap model Anda. Batas berikut membantu mencegah efek buruk pada performa penayangan:

• Maksimal 10 atribut kustom dapat ditetapkan sebagai dapat difilter di katalog Anda.

• Maksimal 100.000.000 nilai atribut yang dapat difilter dapat ada di katalog Anda.

  Jumlah total nilai atribut di katalog Anda dapat diperkirakan dengan mengalikan jumlah produk di katalog Anda dengan jumlah atribut yang dapat difilter.

  Misalnya, jika Anda memiliki katalog dengan 1.000 produk dan 3 atribut yang ditetapkan sebagai dapat difilter, jumlah total nilai atribut dapat diperkirakan sebagai 3*1000=3000.

  Jika Anda menggunakan pemfilteran rekomendasi versi 1 bersama dengan versi 2, jumlah tag filter akan dihitung dalam kuota Anda. Pastikan jumlah tag filter yang ditambahkan ke jumlah total nilai atribut kurang dari 100.000.000.

Jika Anda melampaui batas, Anda tidak dapat menetapkan atribut tambahan sebagai dapat difilter. Jika Anda perlu melampaui batas ini, minta penambahan kuota.

Jumlah total tag dihitung selama pelatihan model. Jika jumlah total melebihi batas, pelatihan model akan gagal. Jika lebih dari 10 atribut kustom yang dapat difilter ditemukan selama pelatihan model, hanya 10 yang akan digunakan.

Sintaksis ekspresi filter rekomendasi

Sintaksis ekspresi filter untuk penelusuran dan rekomendasi serupa. Namun, rekomendasi memiliki beberapa batasan.

Sintaksis ekspresi filter rekomendasi dapat diringkas dengan EBNFberikut:

  # 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;

Batasan sintaksis filter

Berlaku batasan berikut:

• Kedalaman penyematan operator AND dan OR dalam tanda kurung dibatasi. Ekspresi logis dalam filter harus dalam bentuk normal konjungtif (CNF). Ekspresi logis yang paling kompleks yang didukung dapat berupa daftar klausa yang terhubung AND yang hanya berisi operator OR, seperti: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• Ekspresi dapat dinegasikan dengan kata kunci NOT atau dengan -. Hal ini hanya berfungsi dengan ekspresi ANY() dengan satu argumen yang tidak menyertakan atribut terkait inventaris.
• Batasan berbasis availability harus berada di tingkat atas. Batasan tersebut tidak dapat digunakan sebagai bagian dari klausa OR atau negasi (NOT).
• Karena pemfilteran rekomendasi standar hanya mendukung kolom teks, operasi kurang dari, lebih dari, dan pemeriksaan rentang tidak didukung untuk pemfilteran rekomendasi standar. Operasi kurang dari dan lebih dari dapat digunakan hanya dengan kondisi kontrol rekomendasi boost atau bury, yang mendukung beberapa kolom numerik (lihat Kolom yang didukung boost/bury).
• Jumlah maksimum istilah dalam klausa AND tingkat atas adalah 20.
• Klausa OR dapat memiliki hingga 100 argumen yang disertakan dalam ekspresi ANY(). Jika klausa OR memiliki beberapa ekspresi ANY(), semua argumennya akan dihitung dalam batas ini. Misalnya, colors: ANY("red", "green") OR colors: ANY("blue") memiliki tiga argumen. Untuk kasus penggunaan AI Commerce Search, Anda dapat menganggap argumen sebagai nilai atribut yang setara.

Tabel berikut menunjukkan contoh ekspresi filter yang valid, serta contoh yang tidak valid dan alasan mengapa contoh tersebut tidak valid.

Ekspresi	Valid	Catatan
colors: ANY("red", "green")	Ya
NOT colors: ANY("red")	Ya
NOT colors: ANY("red", green")	Tidak	Menegasikan `ANY()` dengan lebih dari satu argumen.
colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")	Ya
(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")	Ya
(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")	Tidak	Tidak dalam bentuk normal konjungtif.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")	Ya
(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))	Tidak	Menggabungkan availability dalam ekspresi OR dengan kondisi lain.

Pemfilteran atribut terkait inventaris

Pemfilteran pada atribut terkait inventaris didasarkan pada status real-time produk Anda. Untuk pemfilteran availability: ANY("IN_STOCK"), respons prediksi akan menampilkan produk utama yang produk utama atau variannya memiliki nilai IN_STOCK yang cocok. Untuk mengetahui informasi selengkapnya tentang produk utama dan varian, lihat Tingkat produk. Kami tidak mendukung pemfilteran Primary only atau Variant only.

IN_STOCK adalah satu-satunya nilai atribut availability yang didukung oleh pemfilteran rekomendasi versi 2.

Atribut terkait inventaris dapat digunakan dalam klausa AND, tetapi tidak dalam klausa OR.

Tips: Meskipun Search API mendukung pemfilteran menurut status stok inventaris lokal, Recommendations API tidak mendukungnya. Solusi untuk memfilter respons Rekomendasi menurut status stok di tingkat inventaris lokal adalah menambahkan langkah pascapemrosesan, tempat Anda memfilter daftar produk menggunakan metode Anda sendiri sebelum mengirim daftar produk ke klien.

Kolom yang didukung

Kolom teks yang didukung diringkas dalam tabel berikut.

Boost atau bury untuk rekomendasi mendukung kolom tambahan yang tidak didukung oleh pemfilteran rekomendasi standar. Untuk mengetahui daftar kolom tersebut, lihat Kolom yang didukung boost/bury.

kolom	deskripsi
"productId"	ID produk (segmen terakhir Product.name).
"brands"	Product.brands.
"categories"	Product.categories.
"genders"	Audience.genders.
"ageGroups"	Audience.age_groups.
"colorFamilies"	ColorInfo.color_families.
"colors"	ColorInfo.colors.
"sizes"	Product.sizes.
"materials"	Product.materials.
"patterns"	Product.patterns.
"conditions"	Product.conditions.
"attributes.key"	Atribut kustom teks dalam objek Produk. Kunci dapat berupa kunci apa pun dalam the Product.attributes map, jika nilai atributnya berupa teks.

Kolom yang didukung boost/bury

Boost/bury mendukung beberapa kolom tambahan yang tidak didukung oleh pemfilteran rekomendasi standar, termasuk kolom numerik.

Selain kolom yang tercantum di Kolom yang didukung, boost/bury untuk rekomendasi mendukung kolom berikut:

Kolom teks

kolom	deskripsi
"tags"	Product.tags[]. Tag kustom yang terkait dengan produk.

Kolom numerik

kolom	deskripsi
"price"	PriceInfo.price. Harga produk.
"discount"	Diskon produk. Kolom ini dihitung menggunakan nilai kolom harga dan harga asli dari PriceInfo.
"rating"	Product.rating. Jumlah total rating untuk produk.
"ratingCount"	rating.ratingCount. Jumlah total rating untuk produk.

Menetapkan pemfilteran rekomendasi untuk model

Anda dapat mengaktifkan pemfilteran untuk rekomendasi menggunakan AI Commerce Search di konsol Gemini Enterprise for Customer Experience atau resource Models API.

Dari konsol, Anda dapat membuat model baru yang mengaktifkan pemfilteran rekomendasi. Anda juga dapat memperbarui opsi ini untuk model yang ada.

Dengan menggunakan resource Models API, Anda dapat membuat model baru dengan pemfilteran rekomendasi diaktifkan atau memperbarui setelan ini untuk model yang ada menggunakan models.Patch.

Perhatikan bahwa jika konfigurasi penayangan yang menampilkan prediksi mengaktifkan pencocokan kategori, pemfilteran tidak akan berfungsi untuk atribut "categories" karena respons hanya menampilkan hasil produk yang memiliki kategori yang sama dengan produk konteks.

Menetapkan pemfilteran untuk model menggunakan konsol

Dengan menggunakan AI Commerce Search di konsol Gemini Enterprise for Customer Experience, pilih opsi Auto generate tags selama pembuatan model untuk mengizinkan pemfilteran rekomendasi untuk model tersebut.

Periksa kembali kompatibilitas dengan setelan lain seperti diversity-level dan category-match-level karena efek totalnya digabungkan dan pemfilteran terjadi terakhir.

• Misalnya, menggabungkan diversity-level berbasis aturan dan category attribute filtering sering kali menghasilkan output kosong.
  • diversity-level=high-diversity memaksa model untuk membatasi hasil maksimum untuk string kategori yang sama. Misalnya, 1 hasil untuk kategori1, 1 hasil untuk kategori2, dll.
  • Pemfilteran atribut menggunakan metadata kategori (Product.categories = ANY ("category2")) menyebabkan model membuang item yang tidak cocok.
  • Output akhir memiliki kurang dari tiga hasil.
• Untuk model similar-items, model ini sudah berisi peningkatan relevansi kategori tambahan dengan category-match-level = relaxed-category-match default. Beralihlah ke category-match-level=no-category-match untuk menonaktifkan perilaku dan menggunakan aturan pemfilteran kustom.

Lihat Membuat model rekomendasi untuk mengetahui petunjuk cara membuat model rekomendasi menggunakan konsol.

Setelan ini tidak dapat diperbarui di konsol untuk model yang ada. Untuk memperbarui setelan ini untuk model, gunakan models.Patch metode API.

Menetapkan pemfilteran untuk model menggunakan API

Anda dapat mengaktifkan pemfilteran rekomendasi untuk model menggunakan models.Create saat membuat model baru atau models.Patch saat memperbarui model yang ada.

Untuk mengizinkan pemfilteran, tetapkan kolom filteringOption untuk model Anda. Nilai yang diizinkan untuk kolom ini adalah:

• RECOMMENDATIONS_FILTERING_DISABLED (default): Pemfilteran dinonaktifkan untuk model.
• RECOMMENDATIONS_FILTERING_ENABLED: Pemfilteran diaktifkan untuk produk utama.

Contoh curl berikut membuat model baru yang mengaktifkan pemfilteran rekomendasi.

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"

Contoh curl berikut memperbarui setelan opsi pemfilteran untuk model yang ada.

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"

Menetapkan atribut sebagai dapat difilter

Untuk memfilter produk yang direkomendasikan, aktifkan pemfilteran untuk atribut produk yang akan Anda gunakan dalam ekspresi filter. Anda dapat memperbarui setelan ini menggunakan AI Commerce Search di konsol Gemini Enterprise for Customer Experience atau menggunakan resource Attributes API.

Jangan membuat lebih banyak atribut yang dapat difilter daripada yang diperlukan. Ada batasan jumlah atribut yang dapat difilter.

Menetapkan atribut sebagai dapat difilter menggunakan konsol

Anda dapat menetapkan atribut sebagai dapat difilter di halaman Kontrol di konsol AI Commerce Search di Gemini Enterprise for Customer Experience.

1. Buka halaman Kontrol di konsol AI Commerce Search di Gemini Enterprise for Customer Experience.
   
   Buka halaman Kontrol

2. Buka tab Kontrol atribut.

   Tab ini menampilkan tabel semua atribut produk yang dapat Anda tetapkan kontrol di seluruh situs.

3. Klik Ubah Kontrol.

4. Tetapkan Dapat difilter ke Benar untuk atribut produk.

5. Klik Simpan Kontrol.

Anda dapat mulai menggunakan atribut untuk pemfilteran setelah siklus pelatihan model berikutnya selesai.

Menetapkan atribut sebagai dapat difilter menggunakan API

AttributesConfig mewakili daftar atribut untuk katalog.

Tetapkan kolom AttributesConfig.filteringOption untuk CatalogAttribute. Nilai yang diizinkan untuk kolom ini adalah:

• RECOMMENDATIONS_FILTERING_DISABLED (default): Pemfilteran dinonaktifkan untuk atribut.
• RECOMMENDATIONS_FILTERING_ENABLED: Pemfilteran diaktifkan untuk atribut.

Contoh curl berikut mengirim kueri ke atribut produk Anda yang ada.

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"

Contoh curl berikut menetapkan atribut produk categories sebagai dapat difilter.

Saat memperbarui atribut yang ada, pertahankan nilai asli atribut untuk indexableOption, dynamicFacetableOption, dan searchableOption seperti yang muncul pada langkah sebelumnya. Jika atribut yang Anda pilih tidak muncul saat melihat attributesConfig seperti pada contoh sebelumnya, gunakan setelan default seperti yang ditunjukkan dalam contoh berikut.

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"

Anda dapat mulai menggunakan atribut untuk pemfilteran setelah siklus pelatihan model berikutnya selesai. Proses ini biasanya memerlukan waktu minimal delapan jam.

Menggunakan atribut yang dapat difilter dalam permintaan prediksi

Setelah model Anda dilatih ulang, Anda dapat menggunakan atribut produk yang dapat difilter dalam permintaan prediksi.

Tetapkan nilai parameter permintaan filterSyntaxV2 ke benar untuk mengaktifkan pemfilteran rekomendasi versi 2. Jika parameter tidak ditetapkan, pemfilteran versi 1 akan tetap aktif. Jika model memiliki tag yang dibuat secara manual dan atribut produk yang dapat difilter, model tersebut dapat menayangkan permintaan prediksi menggunakan salah satu versi pemfilteran. Namun, Anda tidak dapat menyertakan ekspresi pemfilteran v1 dan pemfilteran v2 dalam permintaan prediksi yang sama.

Contoh curl sebagian berikut menunjukkan filterSyntaxV2 yang ditetapkan ke benar, dan ekspresi filter menggunakan atribut produk colors dan categories. Contoh ini mengasumsikan colors dan categories ditetapkan sebagai dapat difilter.

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

Contoh curl berikut menunjukkan permintaan prediksi lengkap.

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"

Selain filter, setelan diversifikasi konfigurasi penayangan juga dapat memengaruhi jumlah hasil yang ditampilkan oleh respons.