Mengimpor data pelengkapan otomatis untuk penelusuran

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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

Pertimbangkan untuk mengimpor data pelengkapan otomatis hanya jika Anda ingin memiliki kontrol tambahan (Jangan Hapus Daftar, 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. Auto-learning 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 UI Cloud Console > Kontrol > Kontrol Autocomplete untuk memicu impor data.

Petunjuk ini hanya untuk mengupload data pelengkapan otomatis Anda sendiri. Selalu perbarui jika Anda berencana menggunakan set data pelengkapan otomatis sepanjang waktu. Untuk mendapatkan hasil pelengkapan otomatis pada waktu kueri, lihat CompletionService.CompleteQuery. Data pelengkapan otomatis hanya digunakan untuk penelusuran. Data ini tidak digunakan sebagai 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 kolom sebanyak mungkin.

• Selalu perbarui set data pelengkapan otomatis Anda sendiri jika Anda berencana menggunakan set data yang diupload sendiri.

• Dilarang mengimpor data dari project lain.

Mengimpor data pelengkapan otomatis

Mengimpor data pelengkapan otomatis dari BigQuery

Vertex AI Search untuk retail mendukung impor data BigQuery untuk Daftar Tolak, Daftar Jangan Hapus, dan Daftar Persyaratan Saran. 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 cara mengkueri 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 disetel dengan benar, permintaan impor akan gagal nantinya. Untuk mempelajari lokasi set data BigQuery lebih lanjut, baca artikel Lokasi set data dalam dokumentasi BigQuery.

Mengisi data ke BigQuery

Gunakan Vertex AI Search untuk skema pelengkapan otomatis retail guna mengupload data pelengkapan otomatis Anda ke BigQuery.

BigQuery dapat menggunakan skema tersebut 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 bidang bilangan bulat atau bidang mengambang memiliki nilai dalam rentang yang valid.
• Jika kolom belum diisi, kolom ini 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 Anda

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

1. Buka halaman IAM di konsol Google Cloud.

   Buka halaman IAM

2. Pilih Vertex AI Search Anda untuk project retail.

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 Data Viewer ke seluruh project, Anda dapat menambahkan peran ini langsung ke set data. Pelajari lebih lanjut.

5. Klik Save.

Memicu impor data ke Vertex AI Search untuk retail

Konsol

1. Buka halaman Kontrol

2. Buka tab Kontrol Pelengkapan Otomatis.

3. Di bagian Daftar Istilah, temukan jenis daftar yang ingin diimpor (Daftar yang ditolak, Daftar Jangan Hapus, atau Daftar istilah yang disarankan), lalu klik Impor atau Ganti.

   Panel Import akan terbuka.

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

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

5. Di panel Import, klik Import.

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

cURL

1. Buat file data untuk parameter input untuk impor. Parameter value 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 Vertex AI Search untuk skema pelengkapan otomatis 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, dengan memberikan nama file data (ditunjukkan sebagai input.json pada 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 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. Jeda baris ditujukan agar mudah dibaca; Anda harus memberikan seluruh saran dalam satu baris. Setiap saran harus berada di barisnya sendiri.

Saran kolom wajib diisi minimum:

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

Atau:

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

Durasi impor data pelengkapan otomatis

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

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

Selalu perbarui set data pelengkapan otomatis Anda

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

Update massal

Anda dapat menggunakan metode impor untuk memperbarui pelengkapan otomatis secara batch. Anda dapat melakukan hal ini dengan cara yang sama seperti saat Anda melakukan impor awal; ikuti langkah-langkah dalam Mengimpor data pelengkapan otomatis. Ini akan menggantikan seluruh {i>dataset<i} yang diimpor.

Memantau kondisi impor

Selalu memperbarui set data Anda sendiri sangat penting untuk mendapatkan hasil saran berkualitas tinggi saat Anda menggunakannya. Anda harus memantau tingkat error impor dan mengambil tindakan jika diperlukan.

Vertex AI Search untuk skema pelengkapan otomatis retail

Saat mengimpor set data pelengkapan otomatis dari BigQuery, gunakan Vertex AI Search untuk skema retail di bawah ini guna 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 dengan skor Anda sendiri.

JSON skema saran pelengkapan otomatis retail untuk Vertex AI Search

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.

Vertex AI Search untuk JSON skema daftar tolak pelengkapan otomatis 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 posting (seperti koreksi ejaan dan pemfilteran hasil nol) untuk semua frasa dalam daftar yang diizinkan ini.

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

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