Retail diganti namanya menjadi Vertex AI Search untuk retail. Kami sedang dalam proses memperbarui konten untuk mencerminkan branding baru ini.

Filter rekomendasi

Halaman ini menjelaskan hasil pemfilteran 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 ke produk yang ekspresinya bernilai benar (true).

Ada dua versi pemfilteran untuk rekomendasi:

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

Bagian dalam panduan cara kerja 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. Ini dapat berupa atribut sistem yang telah ditentukan sebelumnya, seperti categories dan colors, atau atribut khusus yang Anda tentukan, seperti attributes.styles. Jika Anda menetapkan atribut produk sebagai dapat difilter, rekomendasi dapat secara otomatis menggunakan atribut tersebut sebagai tag untuk pemfilteran rekomendasi, bukan mengharuskan Anda menambahkan tag filter secara manual.

Jika 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 informasi selengkapnya tentang produk utama dan varian, lihat Tingkat produk.

Contoh ekspresi filter berikut juga memfilter produk berwarna 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 rekomendasi versi 2, ikuti prosedur berikut. Setiap prosedur akan dibahas nanti di halaman ini.

Aktifkan pemfilteran rekomendasi untuk model yang akan menayangkan rekomendasi yang difilter.
Aktifkan pemfilteran rekomendasi untuk atribut produk yang akan Anda filter.
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 di katalog yang akan difilter.

Contoh ekspresi filter berikut menggunakan tag filter untuk menentukan produk yang diberi tag "Merah" atau "Biru", serta tag "Baru-Arrival", dan tidak diberi tag sebagai "promosi":

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 segera diawali dengan tanda hubung (-), yang setara dengan operator NOT. Ekspresi tag yang menggunakan operator boolean harus diapit dalam tanda kurung.

Selain tag, Anda dapat memfilter menurut filterOutOfStockItems. Flag filterOutOfStockItems akan memfilter produk apa pun dengan stockState bernilai OUT_OF_STOCK.

Anda dapat menggabungkan filter tag dan filter stok habis sehingga hanya item yang memenuhi semua ekspresi filter tertentu 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 pemfilteran v1 dan ekspresi pemfilteran v2 dalam permintaan prediksi yang sama.

Batas pemfilteran Rekomendasi

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

Maksimal 10 atribut khusus dapat ditetapkan sebagai dapat difilter di katalog Anda.
Dapat memiliki hingga 100.000.000 nilai atribut yang dapat difilter di katalog Anda.

Jumlah total nilai atribut dalam 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*1.000=3.000.

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

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

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

Sintaksis ekspresi filter Rekomendasi

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

Sintaksis ekspresi filter rekomendasi dapat diringkas oleh EBNF berikut:

  # 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 string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

Filter batasan sintaksis

Berlaku batasan berikut:

Kedalaman penyematan operator AND dan OR dalam tanda kurung dibatasi. Ekspresi logis dalam filter harus dalam bentuk normal konjungtif (CNF). Ekspresi logika paling kompleks yang didukung dapat berupa daftar klausa yang terhubung dengan AND yang hanya berisi operator OR, seperti: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Ekspresi dapat diabaikan dengan kata kunci NOT atau dengan -. Ini hanya berfungsi dengan ekspresi ANY() dengan satu argumen yang tidak menyertakan atribut terkait inventaris.
Pembatasan berbasis availability harus berada di tingkat atas. Klausa ini tidak boleh digunakan sebagai bagian dari OR-klausa atau negasi (NOT).
Karena pemfilteran rekomendasi standar hanya mendukung kolom tekstual, operasi kurang dari, lebih besar dari, dan pemeriksaan rentang tidak didukung untuk pemfilteran rekomendasi standar. Operasi lebih kecil dari dan lebih besar dari hanya dapat digunakan dengan kondisi kontrol peningkatan/pengurangan rekomendasi, yang mendukung beberapa kolom numerik (lihat Tingkatkan/pengurangan kolom yang didukung).
Jumlah maksimum istilah dalam klausa AND tingkat teratas adalah 20.
Klausa OR dapat memiliki hingga 100 argumen yang disertakan dalam ekspresi ANY(). Jika klausa OR memiliki beberapa ekspresi ANY(), semua argumennya akan diperhitungkan dalam batas ini. Misalnya, colors: ANY("red", "green") OR colors: ANY("blue") memiliki tiga argumen.

Tabel berikut menunjukkan contoh ekspresi filter yang valid, serta contoh yang tidak valid dan alasannya tidak valid.

Ekspresi	Valid	Notes
`colors: ANY("red", "green")`	Ya
`NOT colors: ANY("red")`	Ya
`NOT colors: ANY("red", green")`	Tidak	Menegaskan `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.

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.

Kolom yang didukung

Kolom tekstual yang didukung dirangkum dalam tabel berikut.

Tingkatkan/hambat untuk rekomendasi mendukung kolom tambahan yang tidak didukung oleh pemfilteran rekomendasi standar. Untuk daftar kolom tambahan yang didukung oleh boost/hampir untuk mendapatkan rekomendasi, lihat Boost/pengisian kolom yang didukung.

kolom	deskripsi
"IDproduk"	ID produk (segmen terakhir dari Product.name).
"merek"	{i>Product.brands<i}.
"kategori"	{i>Product.category<i}.
"gender"	Audience.genders.
"ageGroups"	Audience.age_groups.
"colorKeluarga"	ColorInfo.color_families.
"warna"	ColorInfo.colors.
"ukuran"	{i>Product.sizes<i}.
"bahan"	Product.materials.
"pola"	{i>Product.patterns<i}.
"conditions"	{i>Product.conditions<i}.
"attribute.key"	Atribut khusus tekstual dalam objek Produk. Kunci dapat berupa kunci apa pun dalam peta Product.attributes, jika nilai atribut bersifat tekstual.

Tingkatkan/hapus kolom yang didukung

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

Selain kolom yang tercantum di Kolom yang didukung, peningkatan/pengurangan untuk rekomendasi mendukung kolom berikut:

Kolom tekstual

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

Bidang numerik

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

Menyetel pemfilteran rekomendasi untuk model

Anda dapat mengaktifkan pemfilteran rekomendasi menggunakan Search for Retail console atau resource Models API.

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

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

Perlu diperhatikan bahwa jika konfigurasi penayangan yang menampilkan prediksi telah mengaktifkan pencocokan kategori, pemfilteran tidak akan berfungsi pada atribut "category" karena respons hanya menampilkan hasil produk yang memiliki kategori yang sama dengan produk konteks.

Menyetel pemfilteran untuk model menggunakan konsol

Dengan menggunakan konsol Penelusuran Retail, pilih opsi Otomatis buat tag selama pembuatan model guna memungkinkan pemfilteran rekomendasi untuk model tersebut.

Lihat Membuat model rekomendasi untuk mendapatkan petunjuk tentang cara membuat model rekomendasi menggunakan konsol.

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

Menyetel 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 sudah ada.

Untuk mengizinkan pemfilteran, setel 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 Search for Retail console atau menggunakan resource Attributes API.

Jangan membuat atribut yang dapat difilter melebihi yang diperlukan. Ada batas jumlah atribut yang dapat difilter.

Tetapkan atribut sebagai dapat difilter menggunakan konsol

Anda dapat menetapkan atribut sebagai halaman Kontrol yang dapat difilter di Search for Retail console.

Buka halaman Controls di Search for Retail console.

Buka halaman Kontrol
Buka tab Kontrol atribut.

Tab ini menampilkan tabel semua atribut produk yang dapat Anda tetapkan kontrolnya di seluruh situs.
Klik Ubah Kontrol.
Tetapkan Filterable ke True untuk atribut produk.
Klik Save Controls.

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

Menyetel 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 mengkueri atribut produk Anda yang sudah 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 karena nilai tersebut muncul di langkah sebelumnya. Jika atribut yang Anda pilih tidak muncul saat melihat attributesConfig seperti dalam 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.

Menggunakan atribut yang dapat difilter dalam permintaan prediksi

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

Setel filterSyntaxV2 nilai parameter permintaan ke benar (true) 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 pemfilteran v1 dan ekspresi pemfilteran v2 dalam permintaan prediksi yang sama.

Contoh curl parsial berikut menunjukkan filterSyntaxV2 yang ditetapkan ke true, dan ekspresi filter menggunakan atribut produk colors dan categories. Contoh ini mengasumsikan bahwa 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\")',
        useMostRecentServingConfig: true
     }" \
     "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.