Mengimpor data pelengkapan otomatis untuk penelusuran

Pelengkapan otomatis adalah fitur untuk memprediksi sisa kata yang diketik pengguna, yang dapat meningkatkan pengalaman penelusuran pengguna. Fitur ini dapat memberikan saran pelengkapan otomatis berdasarkan set data yang Anda berikan atau berdasarkan peristiwa pengguna yang Anda berikan.

Pertimbangkan untuk mengimpor data pelengkapan otomatis hanya jika Anda ingin memiliki kontrol tambahan (Daftar Jangan Hapus, Daftar Tolak) atau jika Anda perlu menggunakan data pelengkapan otomatis Anda sendiri. Mengaktifkan pembelajaran otomatis sudah cukup untuk sebagian besar kasus yang memerlukan pelengkapan otomatis. Pembelajaran otomatis menyediakan set data saran yang didukung machine learning berdasarkan peristiwa penelusuran pengguna. Lihat Pelengkapan otomatis untuk mengetahui cara mengaktifkan pembelajaran otomatis.

Catatan: Mulai September 2022, Anda dapat menggunakan Konsol Cloud > Kontrol > UI Kontrol Pelengkapan Otomatis untuk memicu impor data.

Petunjuk ini hanya untuk mengupload data pelengkapan otomatis Anda sendiri. Pastikan data pelengkapan otomatis Anda selalu terbaru jika Anda berencana menggunakan set data pelengkapan otomatis Anda setiap saat. Untuk mendapatkan hasil pelengkapan otomatis pada waktu kueri, lihat ke CompletionService.CompleteQuery. Data pelengkapan otomatis hanya digunakan untuk penelusuran. Data ini tidak digunakan oleh rekomendasi.

Sebelum memulai

Sebelum dapat mengimpor informasi pelengkapan otomatis, Anda harus menyelesaikan petunjuk di bagian Sebelum memulai, khususnya menyiapkan project, membuat akun layanan, dan menambahkan akun layanan ke lingkungan lokal Anda.

Anda harus memiliki peran IAM Editor Retail untuk melakukan impor.

Praktik terbaik impor pelengkapan otomatis

Saat mengimpor data pelengkapan otomatis, pastikan Anda menerapkan praktik terbaik berikut:

• Baca skema BigQuery yang tercantum di bagian berikut dan dokumentasi API.

• Jangan gunakan nilai placeholder.

• Sertakan sebanyak mungkin kolom.

• Pastikan set data pelengkapan otomatis Anda sendiri selalu terbaru jika Anda berencana menggunakan set data yang diupload sendiri.

• Mengimpor data dari project lain tidak diizinkan.

Mengimpor data pelengkapan otomatis

Mengimpor data pelengkapan otomatis dari BigQuery

Penelusuran Commerce AI mendukung impor data BigQuery untuk Daftar Tolak, Daftar Jangan Hapus, dan Daftar Istilah Saran. Lihat detail selengkapnya di Pelengkapan otomatis.

Untuk mengimpor data pelengkapan otomatis dalam format yang benar dari BigQuery, gunakan skema pelengkapan otomatis Penelusuran Commerce AI untuk membuat tabel BigQuery dengan format yang benar dan memuat tabel dengan data pelengkapan otomatis Anda. Kemudian, upload data Anda ke Penelusuran Commerce AI.

Untuk mendapatkan bantuan lebih lanjut terkait tabel BigQuery, lihat Pengantar tabel. Untuk mendapatkan bantuan terkait kueri BigQuery, lihat Ringkasan pembuatan kueri data BigQuery.

Lokasi set data BigQuery

Saat pertama kali membuat set data BigQuery untuk tabel BigQuery pelengkapan otomatis, pastikan lokasi set data ditetapkan ke lokasi multi-region "US". Jika tidak ditetapkan dengan benar, permintaan impor Anda akan gagal nantinya. Untuk mempelajari lokasi set data BigQuery lebih lanjut, lihat Lokasi set data dalam dokumentasi BigQuery.

Mengisi data ke BigQuery

Gunakan skema pelengkapan otomatis Penelusuran Commerce AI untuk mengupload data pelengkapan otomatis Anda ke BigQuery.

BigQuery dapat menggunakan skema untuk memvalidasi apakah data berformat JSON memiliki nama dan jenis kolom yang benar (seperti STRING, INTEGER, dan RECORD), tetapi tidak dapat melakukan validasi seperti menentukan:

• Apakah kolom string dipetakan ke nilai enum yang dapat dikenali.
• Apakah kolom string menggunakan format yang benar.
• Apakah kolom bilangan bulat atau float memiliki nilai dalam rentang yang valid.
• Apakah kolom yang tidak ada adalah kolom wajib diisi.

Untuk memastikan kualitas data Anda dan pengalaman penelusuran pengguna akhir, pastikan Anda merujuk ke dokumentasi skema dan referensi untuk mengetahui detail tentang nilai dan format.

Menyiapkan akses ke set data BigQuery

Untuk menyiapkan akses, pastikan set data BigQuery Anda berada di project yang sama dengan layanan Penelusuran Commerce AI Anda dan selesaikan langkah-langkah berikut.

1. Buka halaman IAM di Google Cloud konsol.

   Buka halaman IAM

2. Pilih project Penelusuran Commerce AI Anda.

3. Di halaman IAM & Admin, klik  Berikan Akses.

4. Untuk Principal baru, masukkan [e-mail] dan pilih peran BigQuery > BigQuery Data Viewer.

   Jika tidak ingin memberikan peran Data Viewer ke seluruh project, Anda dapat menambahkan peran ini langsung ke set data. Pelajari lebih lanjut.

5. Klik Simpan.

Memicu impor data ke Penelusuran Commerce AI

Konsol

1. Buka halaman Kontrol

2. Buka tab Kontrol Pelengkapan Otomatis.

3. Di bagian Daftar Istilah, temukan jenis daftar yang ingin Anda impor (Daftar tolak, Daftar jangan hapus, atau Daftar istilah saran) dan klik Impor atau Ganti.

   Panel Impor akan terbuka.

4. Masukkan jalur BigQuery lokasi data Anda, atau pilih Telusuri untuk memilih lokasi.

   Jalur BigQuery harus berada di project yang sama dan skemanya harus benar. Untuk memeriksanya, klik Telusuri , lalu klik nama tabel untuk melihat kontennya di konsol BigQuery.

5. Di panel Impor, klik Impor.

   Impor akan dimulai. Anda dapat keluar dari halaman tanpa mengganggu impor.

cURL

1. Buat file data untuk parameter input impor. Nilai parameter input Anda bergantung pada apakah Anda mengimpor dari Cloud Storage atau BigQuery.

   Gunakan objek BigQuerySource untuk mengarah ke set data BigQuery Anda.

   • dataset-id: ID set data BigQuery.
   • table-id: ID tabel BigQuery yang menyimpan data Anda.
   • data-schema: Untuk properti dataSchema, gunakan nilai suggestions (default), allowlist, denylist. Gunakan skema pelengkapan otomatis Penelusuran Commerce AI .

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }

2. Impor informasi pelengkapan otomatis Anda ke Penelusuran Commerce AI dengan membuat permintaan POST ke metode REST CompletionData:import, yang memberikan nama file data (ditampilkan sebagai input.json dalam contoh di bawah).

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"

   Anda dapat memeriksa status secara terprogram menggunakan API. Anda akan menerima objek respons yang terlihat seperti ini:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }

   Kolom nama adalah ID objek operasi. Untuk meminta status objek ini, ganti kolom nama dengan nilai yang ditampilkan oleh metode impor. Setelah impor selesai, kolom done akan ditampilkan sebagai true:

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"

   Setelah operasi selesai, objek yang ditampilkan akan memiliki nilai done sebesar true, dan menyertakan objek Status yang mirip dengan contoh berikut:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }

Format data pelengkapan otomatis

File JSON Anda akan terlihat seperti contoh berikut. Ganti baris untuk memudahkan pembacaan; Anda harus memberikan seluruh saran dalam satu baris. Setiap saran harus berada di barisnya sendiri.

Kolom minimum saran yang diperlukan:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

Atau:

{
  "suggestion": "ABC",
  "frequency": "100"
}

Durasi impor data pelengkapan otomatis

Biasanya diperlukan waktu beberapa menit hingga satu jam untuk menyelesaikan satu impor dari BigQuery.

Setelah impor set data selesai, kolom done dalam objek operasi akan ditandai sebagai benar (true). Setelah itu, mungkin diperlukan waktu tambahan 1~2 hari agar data dapat diindeks dan digunakan dalam penayangan produksi.

Memastikan set data pelengkapan otomatis Anda selalu terbaru

Jika Anda berencana menggunakan set data yang diupload sendiri, sebaiknya pastikan set data yang diupload selalu terbaru secara berkala.

Update batch

Anda dapat menggunakan metode impor untuk mengupdate pelengkapan otomatis Anda secara batch. Anda melakukannya dengan cara yang sama seperti saat melakukan impor awal; ikuti langkah-langkah di bagian Mengimpor data pelengkapan otomatis. Tindakan ini akan mengganti seluruh set data yang diimpor.

Memantau kondisi impor

Memastikan set data Anda sendiri selalu terbaru penting untuk mendapatkan hasil saran berkualitas tinggi saat Anda menggunakannya. Anda harus memantau rasio error impor dan mengambil tindakan jika diperlukan.

Skema pelengkapan otomatis Penelusuran Commerce AI

Saat mengimpor set data pelengkapan otomatis dari BigQuery, gunakan skema Penelusuran Commerce AI di bawah untuk membuat tabel BigQuery dengan format yang benar dan memuatnya dengan data pelengkapan otomatis Anda.

Skema untuk saran

Set data ini digunakan untuk memberikan frasa saran pelengkapan otomatis Anda sendiri dengan skor Anda sendiri.

JSON skema saran pelengkapan otomatis Penelusuran Commerce AI

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

Skema untuk daftar tolak

Set data ini digunakan sebagai daftar tolak untuk memblokir frasa agar tidak disarankan.

JSON skema daftar tolak pelengkapan otomatis Penelusuran Commerce AI

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

Skema untuk daftar izinkan

Set data ini digunakan untuk melewati proses postingan (seperti koreksi ejaan dan pemfilteran tanpa hasil) untuk semua frasa dalam daftar izinkan ini.

JSON skema daftar izinkan pelengkapan otomatis Penelusuran Commerce AI

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]