Mengimpor data pelengkapan otomatis untuk penelusuran

Pelengkapan otomatis adalah fitur untuk memprediksi sisa kata yang diketik pengguna, yang dapat meningkatkan pengalaman penelusuran pengguna. Fungsi ini dapat memberikan sugesti typeahead 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 saat pelengkapan otomatis diperlukan. Pemelajaran otomatis menyediakan set data sugesti yang didukung machine learning berdasarkan peristiwa penelusuran pengguna. Lihat Pelengkapan otomatis untuk mengetahui cara mengaktifkan pembelajaran otomatis.

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

Petunjuk ini hanya untuk mengupload data pelengkapan otomatis Anda sendiri. Perbarui terus jika Anda berencana untuk menggunakan set data pelengkapan otomatis setiap saat. Untuk mendapatkan hasil pelengkapan otomatis pada waktu kueri, lihat 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 Sebelum memulai, khususnya menyiapkan project, membuat akun layanan, dan menambahkan akun layanan ke lingkungan lokal.

Anda harus memiliki peran IAM Retail Editor untuk melakukan impor.

Praktik terbaik impor Autocomplete

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

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

• Jangan gunakan nilai placeholder.

• Sertakan sebanyak mungkin kolom.

• Perbarui set data pelengkapan otomatis Anda sendiri 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

Vertex AI Search untuk retail mendukung impor data BigQuery untuk Daftar Deny, Daftar Do Not Remove, dan Daftar Suggestion Terms. Lihat detail selengkapnya di Pelengkapan otomatis.

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

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 nanti. Untuk mempelajari lokasi set data BigQuery lebih lanjut, lihat artikel Lokasi set data dalam dokumentasi BigQuery.

Mengisi data ke BigQuery

Gunakan Vertex AI Search untuk skema pelengkapan otomatis retail untuk mengunggah data pelengkapan otomatis 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:

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

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

Menyiapkan akses ke set data BigQuery

Untuk menyiapkan akses, pastikan set data BigQuery Anda berada dalam project yang sama dengan layanan Vertex AI Search for retail dan selesaikan langkah-langkah berikut.

1. Buka halaman IAM di konsol Google Cloud.

   Buka halaman IAM

2. Pilih project Vertex AI Search untuk retail Anda.

3. Di halaman IAM & Admin, klik  Grant Access.

4. Untuk New principals, masukkan [e-mail], lalu pilih peran BigQuery > BigQuery Data Viewer.

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

5. Klik Simpan.

Memicu impor data ke Vertex AI Search untuk retail

Konsol

1. Buka halaman Controls

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 yang disarankan) dan klik Impor atau Ganti.

   Panel Impor akan terbuka.

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

   Jalur BigQuery harus berada dalam project yang sama dan skema-nya harus benar. Untuk memeriksanya, klik Jelajahi, lalu klik nama tabel untuk melihat kontennya di konsol BigQuery.

5. Di panel Impor, klik Impor.

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

cURL

1. Buat file data untuk parameter input untuk 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 Vertex AI Search untuk retail.

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

2. Impor informasi pelengkapan otomatis Anda ke Vertex AI Search untuk retail 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"

   Saat operasi selesai, objek yang ditampilkan memiliki nilai done 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. Pemisah baris adalah untuk keterbacaan; Anda harus memberikan seluruh saran dalam satu baris. Setiap saran harus berada pada barisnya masing-masing.

Kolom minimum yang diperlukan saran:

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

Atau:

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

Durasi impor data pelengkapan otomatis

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

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

Memastikan set data pelengkapan otomatis Anda selalu yang terbaru

Jika Anda berencana menggunakan set data yang diupload sendiri, sebaiknya update set data yang diupload secara rutin.

Update massal

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

Memantau kondisi impor

Memperbarui set data Anda sendiri sangat penting untuk mendapatkan hasil sugesti berkualitas tinggi saat Anda menggunakannya. Anda harus memantau rasio error impor dan mengambil tindakan jika diperlukan.

Skema pelengkapan otomatis Vertex AI Search untuk retail

Saat mengimpor set data pelengkapan otomatis dari BigQuery, gunakan skema retail Penelusuran Vertex AI di bawah untuk membuat tabel BigQuery dengan format yang benar dan memuat tabel tersebut 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 Vertex AI Search untuk retail

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 Vertex AI Search untuk retail

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 yang diizinkan

Set data ini digunakan untuk melewati proses pasca-pemrosesan (seperti koreksi ejaan dan pemfilteran hasil nol) untuk semua frasa dalam daftar yang diizinkan ini.

JSON skema daftar yang diizinkan pelengkapan otomatis Vertex AI Search untuk retail

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"
  }
]