Mengonfigurasi kontrol penyajian untuk penelusuran

Kontrol penayangan (juga disebut kontrol) mengubah perilaku default cara permintaan ditayangkan saat hasil ditampilkan. Kontrol penayangan berfungsi di tingkat penyimpanan data.

Misalnya, kontrol dapat meningkatkan dan memendam hasil, memfilter entri dari hasil yang ditampilkan, mengaitkan string satu sama lain sebagai sinonim, atau mengalihkan hasil ke URI yang ditentukan.

Halaman ini menjelaskan kontrol penayangan untuk aplikasi penelusuran. Untuk mengetahui informasi tentang cara menggunakan kontrol penayangan dengan rekomendasi media, lihat Membuat dan mengelola konfigurasi penayangan media.

Tentang kontrol inferensi

Untuk mengubah hasil permintaan, buat kontrol penayangan terlebih dahulu. Kemudian, lampirkan kontrol tersebut ke konfigurasi penayangan aplikasi penelusuran. Konfigurasi penayangan mengonfigurasi metadata yang digunakan untuk menghasilkan hasil waktu penayangan, seperti hasil penelusuran atau jawaban. Kontrol penayangan hanya memengaruhi permintaan yang ditayangkan oleh aplikasi jika kontrol dilampirkan ke konfigurasi penayangan aplikasi.

Beberapa kontrol, seperti kontrol peningkat, memiliki dependensi pada penyimpanan data. Jika penyimpanan data dihapus dari aplikasi, semua kontrol yang bergantung pada penyimpanan data juga akan dihapus dari aplikasi tersebut dan menjadi tidak aktif, tetapi tidak dihapus.

Jenis kontrol penayangan

Jenis kontrol penayangan berikut tersedia:

Kontrol	Deskripsi	Tersedia untuk
Kontrol peningkatan	Mengubah urutan hasil yang ditampilkan	Aplikasi penelusuran dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur, situs dengan data terstruktur (pengindeksan situs lanjutan), data tidak terstruktur dengan metadata, atau data media
Kontrol filter	Menghapus entri dari hasil yang ditampilkan	Aplikasi penelusuran dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur, situs (pengindeksan situs lanjutan), data tidak terstruktur dengan metadata, atau data media
Kontrol sinonim	Mengaitkan kueri satu sama lain	Menelusuri aplikasi dengan penyimpanan data situs (pengindeksan situs lanjutan), terstruktur, tidak terstruktur, atau media
Kontrol pengalihan	Mengarahkan ke URI yang ditentukan	Semua aplikasi penelusuran
Kontrol promosi	Mempromosikan link tertentu untuk kueri	Semua aplikasi penelusuran

Tentang kondisi

Saat membuat kontrol, Anda dapat secara opsional menentukan kondisi yang menentukan kapan kontrol diterapkan. Kondisi ditentukan menggunakan kolom kondisi. Kolom kondisi berikut tersedia:

• Istilah kueri (queryTerms). Kontrol opsional yang diterapkan saat kueri tertentu dicari. Jika kondisi queryTerms digunakan, kontrol diterapkan saat nilai queryTerms cocok dengan istilah di SearchRequest.query. Istilah kueri hanya dapat digunakan jika Control.searchUseCase ditetapkan sebagai SOLUTION_TYPE_SEARCH. Hingga 10 queryTerms berbeda dapat ditentukan pada satu Control.condition. Jika tidak ada istilah penelusuran yang ditentukan, kolom queryTerms akan diabaikan.

  Untuk kontrol penayangan promosi, queryTerms tidak dapat ditentukan jika Anda menentukan kondisi queryRegex, yang hanya berlaku untuk penelusuran situs dasar. Selain itu, kolom fullMatch untuk penelusuran situs dasar, harus ditetapkan ke true jika queryTerms ditentukan. Untuk semua aplikasi penelusuran lainnya, hanya queryTerms yang didukung dan fullMatch dapat ditetapkan ke true atau false.

• Rentang waktu (activeTimeRange). Kontrol opsional yang diterapkan saat permintaan terjadi dalam rentang waktu tertentu. Kebijakan ini memeriksa bahwa waktu permintaan diterima adalah antara activeTimeRange.startTime dan activeTimeRange.endTime. Hingga 10 rentang activeTimeRange dapat ditentukan pada satu Control.condition. Jika kolomactiveTimeRange tidak ditentukan, kolom akan diabaikan.

• queryRegex. Hanya tersedia untuk kontrol penayangan promosi khusus untuk penelusuran situs dasar. Ini adalah kondisi opsional yang menerapkan kontrol saat kueri cocok dengan ekspresi reguler yang ditentukan. Kondisi ini tidak dapat ditentukan jika Anda menentukan kondisi queryTerms.

Jika beberapa kondisi ditentukan untuk kontrol, kontrol akan diterapkan ke permintaan penelusuran jika kedua jenis kondisi terpenuhi. Jika beberapa nilai untuk kondisi yang sama ditentukan, hanya satu nilai yang harus cocok agar kondisi tersebut terpenuhi.

Misalnya, pertimbangkan kondisi berikut dengan dua istilah kueri yang ditentukan:

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

Kondisi akan terpenuhi untuk permintaan dengan SearchRequest.query="gShoe" atau permintaan dengan SearchRequest.query="gBoot", tetapi tidak akan terpenuhi dengan SearchRequest.query="gSandal" atau string lainnya.

Jika tidak ada kondisi yang ditentukan, kontrol akan selalu diterapkan.

Untuk mengetahui informasi selengkapnya, lihat kolom Condition dalam referensi API.

Membuat dan melampirkan kontrol penayangan peningkat

Kontrol penayangan peningkat mengurutkan ulang hasil dengan mempromosikan atau menurunkan peringkatnya berdasarkan kondisi yang diterapkan. Peningkatan berfungsi dengan menerapkan faktor pengali pada peringkat dokumen yang memenuhi kondisi peningkatan.

Untuk membuat dan melampirkan kontrol peningkatan, lakukan hal berikut:

Konsol

1. Di konsol Google Cloud , buka halaman AI Applications.

   Aplikasi AI

2. Pilih aplikasi yang ingin Anda buat kontrol peningkatannya.

3. Di halaman ringkasan aplikasi, pilih Naikkan/Turunkan yang tercantum di tahap Sinyal.

4. Di halaman Sinyal, klik Buat kontrol.

5. Di panel Create control, lakukan hal berikut:

   1. Masukkan nama untuk kontrol naikkan/tenggelamkan Anda, lalu klik Lanjutkan.

   2. Tetapkan kondisi berikut yang memicu kontrol. Jika tidak ada kondisi yang dikonfigurasi, kontrol akan selalu berlaku:

      1. Tambahkan Istilah kueri kecocokan parsial. Kontrol berlaku saat istilah kueri ini cocok sebagian.

      2. Tambahkan Istilah kueri pencocokan persis. Kontrol berlaku saat istilah kueri ini cocok persis.

      3. Untuk menambahkan rentang waktu aktif, klik Tambahkan rentang waktu, lalu tetapkan Waktu mulai 1 dan Waktu berakhir 1. Ini menentukan periode saat kondisi aktif. Anda dapat menambahkan maksimal 10 rentang waktu.

      4. Klik Lanjutkan.

   3. Tentukan tindakan yang ingin Anda picu dengan kontrol ini:

      1. Pilih penyimpanan data dari daftar. Jika Anda ingin tindakan diterapkan ke beberapa penyimpanan data, buat kontrol untuk setiap penyimpanan data.

      2. Tambahkan filter.

         Ini adalah string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Kondisi peningkatan hanya diterapkan jika dokumen cocok dengan semua persyaratan. Jika tidak, tidak ada perubahan. Jika Anda tidak menentukan filter, peningkatannya akan diterapkan ke semua dokumen di penyimpanan data.

         Untuk memahami cara menulis ekspresi filter, lihat Sintaksis ekspresi filter dan Contoh ekspresi filter.

      3. Pilih nilai naik/turun dalam rentang [-1, 1] menggunakan penggeser. Penggeser bergerak dalam langkah 0,01.

      4. Klik Lanjutkan.

   4. Jika Anda ingin menerapkan kontrol segera setelah dibuat, aktifkan Publikasikan kontrol ini segera, lalu klik Lanjutkan.

6. Klik Kirim.

7. Untuk mengubah konfigurasi kontrol, lakukan hal berikut:

   1. Di halaman Sinyal, dalam daftar kontrol naik/turun aplikasi, klik untuk kontrol yang ingin Anda ubah, lalu klik Edit.

   2. Edit kontrol di panel Edit kontrol.

8. Untuk mengaktifkan atau menonaktifkan kontrol, di halaman Sinyal, dalam daftar kontrol naik/turun aplikasi, klik untuk kontrol yang ingin Anda aktifkan atau nonaktifkan, lalu klik Aktifkan atau Nonaktifkan.

9. Untuk menghapus kontrol, di halaman Sinyal, dalam daftar kontrol promosi/penyembunyian aplikasi, klik untuk kontrol yang ingin Anda hapus, lalu klik Hapus.

REST

Kontrol penayangan peningkat ditentukan sebagai kontrol dengan boostAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan peningkat.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

   1. Di konsol Google Cloud , buka halaman AI Applications.

      Buka Aplikasi

   2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": [
     "USE_CASE"
   ],
   "conditions": {
    "queryTerms": [
      {
        "value": "VALUE",
        "fullMatch": FULL_MATCH
      }
    ],
    "activeTimeRange": [
      {
        "startTime": "START_TIMESTAMP",
        "endTime": "END_TIMESTAMP"
      }
    ]
   },
   "boostAction": {
     "boost": BOOST_VALUE,
     "filter": "FILTER",
     "dataStore": "DATA_STORE_RESOURCE_PATH"
    }
   }'

   Ganti kode berikut:

   • PROJECT_ID: nomor atau ID Google Cloud project Anda.
   • APP_ID: ID aplikasi Vertex AI Search.
   • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, angka, tanda hubung, dan garis bawah.
   • DISPLAY_NAME: nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string berenkode UTF-8 dengan panjang [1,128].
   • USE_CASE: harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
   • CONDITION: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
     • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki paling banyak tiga istilah yang dipisahkan dengan spasi.
     • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
     • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
     • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
   • BOOST_VALUE: bilangan floating point dalam rentang [-1,1]. Jika nilainya negatif, hasil akan diturunkan (hasil muncul lebih rendah dalam hasil). Jika nilainya positif, hasil akan dipromosikan (muncul lebih tinggi dalam hasil). Untuk informasi selengkapnya, lihat boostAction.
   • FILTER: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen memenuhi semua persyaratan, maka peningkatan diterapkan. Jika tidak, tidak ada perubahan. Jika kolom ini kosong, maka peningkatan diterapkan ke semua dokumen di penyimpanan data. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Catatan: Kolom dokumen title tidak dapat difilter.
   • DATA_STORE_RESOURCE_PATH: jalur resource lengkap dari penyimpanan data yang dokumennya harus ditingkatkan oleh kontrol ini. Format jalur resource lengkap adalah projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.

3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
   -d '{
    "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
   }'

   Ganti BOOST_ID_N dengan ID kontrol yang Anda buat pada langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan filter

Kontrol penayangan filter ditentukan sebagai kontrol dengan filterAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan filter.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

   1. Di konsol Google Cloud , buka halaman AI Applications.

      Buka Aplikasi

   2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "filterAction": {
     "filter": "FILTER"
    }
   }'

   Ganti kode berikut:

   • PROJECT_ID: nomor atau ID Google Cloud project Anda.
   • APP_ID: ID aplikasi Vertex AI Search.
   • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, angka, tanda hubung, dan garis bawah.
   • DISPLAY_NAME: nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string berenkode UTF-8 dengan panjang [1,128].
   • USE_CASE: harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
   • CONDITION: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
     • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki paling banyak tiga istilah yang dipisahkan dengan spasi.
     • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
     • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
     • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
   • FILTER: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, dokumen akan ditampilkan dalam hasil. Jika tidak, dokumen tidak akan ada dalam hasil. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Untuk mengetahui informasi selengkapnya, lihat filterAction. Catatan: Kolom dokumen title tidak dapat difilter.

3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
   -d '{
     "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
   }'

   Ganti FILTER_ID_N dengan ID kontrol yang Anda buat pada langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan sinonim

Kontrol penayangan sinonim ditentukan sebagai kontrol dengan synonymsAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan sinonim.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

   1. Di konsol Google Cloud , buka halaman AI Applications.

      Buka Aplikasi

   2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "synonymsAction": {
     "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
    }
   }'

   Ganti kode berikut:

   • PROJECT_ID: nomor atau ID Google Cloud project Anda.
   • APP_ID: ID aplikasi Vertex AI Search.
   • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, angka, tanda hubung, dan garis bawah.
   • DISPLAY_NAME: nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string berenkode UTF-8 dengan panjang [1,128].
   • USE_CASE: harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
   • CONDITION: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
     • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki paling banyak tiga istilah yang dipisahkan dengan spasi.
     • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
     • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
     • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
   • SYNONYMS_N: daftar string yang terkait satu sama lain, sehingga masing-masing string lebih cenderung menampilkan hasil yang serupa. Meskipun Anda lebih mungkin mendapatkan hasil yang serupa, saat Anda menelusuri setiap entri sinonim, Anda mungkin tidak menerima semua hasil yang relevan untuk semua sinonim terkait. Anda harus menentukan minimal dua sinonim dan Anda dapat menentukan hingga 100 sinonim. Setiap sinonim harus berenkode UTF-8 dan dalam huruf kecil. Tidak boleh ada string duplikat. Misalnya, Anda dapat menambahkan "pixel", "ponsel android", dan "ponsel google" sebagai sinonim. Untuk mengetahui informasi selengkapnya, lihat synonymsAction.

3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
   -d '{
     "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
   }'

   Ganti SYNONYMS_ID_N dengan ID kontrol yang Anda buat pada langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan pengalihan

Kontrol penayangan pengalihan memungkinkan pengalihan pengguna ke URI yang disediakan. Kontrol pengalihan ditentukan sebagai kontrol dengan redirectAction.

Gunakan petunjuk berikut untuk membuat kontrol penayangan pengalihan.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

   1. Di konsol Google Cloud , buka halaman AI Applications.

      Buka Aplikasi

   2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": FULL_MATCH
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ]
   },
   "redirectAction": {
     "redirectURI": "REDIRECT_URI"
    }
   }'

   Ganti kode berikut:

   • PROJECT_ID: nomor atau ID Google Cloud project Anda.
   • APP_ID: ID aplikasi Vertex AI Search.
   • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, angka, tanda hubung, dan garis bawah.
   • DISPLAY_NAME: nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string berenkode UTF-8 dengan panjang [1,128].
   • USE_CASE: harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
   • CONDITION: kolom opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
     • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000]. Jika FULL_MATCH_1 adalah true, kolom ini dapat memiliki paling banyak tiga istilah yang dipisahkan dengan spasi.
     • FULL_MATCH: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika disetel ke true, SearchRequest.query harus cocok sepenuhnya dengan queryTerm.value. Jika disetel ke false, SearchRequest.query harus berisi queryTerm.value sebagai substring.
     • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
     • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
   • REDIRECT_URI_N: URI tempat Anda dialihkan. Dapat memiliki panjang maksimum 2.000 karakter. Misalnya, jika nilai istilah kueri adalah "dukungan", Anda dapat menetapkan pengalihan ke halaman dukungan teknis, bukan menampilkan (atau gagal menampilkan) hasil penelusuran untuk "dukungan". Dalam contoh ini, URI pengalihan menjadi "https://www.example.com/support". Untuk mengetahui informasi selengkapnya, lihat redirectAction.

3. Lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
   -d '{
     "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
   }'

   Ganti REDIRECT_ID_N dengan ID kontrol yang Anda buat pada langkah sebelumnya.

Membuat dan melampirkan kontrol penayangan promosi

Kontrol penayangan promosi memungkinkan Anda menampilkan link sebagai hasil yang dipromosikan dan tersedia untuk jenis penyimpanan data penelusuran berikut:

• Penyimpanan data situs dengan penelusuran situs dasar: Untuk penyimpanan data ini, Anda tidak perlu melampirkan kontrol promosi ke konfigurasi penayangan aplikasi. Membuat dan mengaktifkan kontrol promosi akan mengaktifkan kontrol promosi. Anda dapat mengaktifkan atau menonaktifkan kontrol promosi dengan mengaktifkan atau menonaktifkannya.

• Penyimpanan data dengan data terstruktur dan tidak terstruktur, data situs dengan pengindeksan situs lanjutan, dan aplikasi penelusuran gabungan: Untuk penyimpanan data ini, Anda harus melampirkan kontrol promosi ke konfigurasi penayangan.

Kontrol promosi ditentukan menggunakan promoteAction.

Agar berhasil membuat kontrol promosi, salah satu kolom berikut diperlukan dalam permintaan pembuatan:

• queryTerms: Kondisi ini tidak dapat ditentukan jika Anda menentukan kondisi queryRegex, yang hanya berlaku untuk penelusuran situs dasar. Untuk penelusuran situs dasar, fullMatch harus disetel ke true jika queryTerms ditentukan. Untuk semua aplikasi penelusuran lainnya, hanya queryTerms yang didukung dan fullMatch dapat disetel ke true atau false.
• queryRegex. Hanya tersedia untuk kontrol penayangan promosi khusus untuk penelusuran situs dasar. Kondisi ini menerapkan kontrol saat kueri cocok dengan ekspresi reguler yang ditentukan. Kondisi ini tidak dapat ditentukan jika Anda menentukan kondisi queryTerms.

Artinya, untuk penelusuran situs dasar, Anda harus menentukan kolom queryTerms dengan fullMatch yang ditetapkan ke true atau menentukan kolom queryRegex. Untuk semua jenis penelusuran lainnya, tentukan kolom queryTerms dengan fullMatch yang ditetapkan ke true atau false.

Gunakan petunjuk berikut untuk membuat kontrol penayangan promosi.

Untuk mengetahui detail kolom, lihat referensi API engines.controls dan referensi API engines.controls.create.

1. Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.

   1. Di konsol Google Cloud , buka halaman AI Applications.

      Buka Aplikasi

   2. Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.

2. Jalankan perintah curl berikut untuk membuat kontrol Anda.

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
   -d '{
   "displayName": "DISPLAY_NAME",
   "solutionType": "SOLUTION_TYPE_SEARCH",
   "useCases": ["USE_CASE"],
   "conditions": {
     "queryTerms": [
       {
         "value": "VALUE",
         "fullMatch": true
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ],
     "queryRegex": "VALUE_REGEX"
   },
   "promoteAction": {
     "dataStore": "DATA_STORE_RESOURCE_PATH",
     "searchLinkPromotion": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   Ganti kode berikut:

   • PROJECT_ID: nomor atau ID Google Cloud project Anda.
   • APP_ID: ID aplikasi Vertex AI Search.
   • CONTROL_ID: ID unik untuk kontrol. ID dapat berisi [1-63] karakter yang dapat berupa huruf, angka, tanda hubung, dan garis bawah.
   • DISPLAY_NAME: nama yang dapat dibaca manusia untuk kontrol. Google merekomendasikan agar nama ini memberikan indikasi kapan atau mengapa kontrol harus digunakan. Harus berupa string berenkode UTF-8 dengan panjang [1,128].
   • USE_CASE: harus SEARCH_USE_CASE_SEARCH atau SEARCH_USE_CASE_BROWSE. Jika SEARCH_USE_CASE_BROWSE ditentukan, Condition.queryTerms tidak dapat digunakan dalam kondisi.
   • Condition: objek opsional yang menentukan kapan kontrol harus diterapkan. Berisi kolom berikut:
     • queryTerms: Tidak dapat digunakan dengan kolom queryRegex.
       • VALUE: nilai kueri tertentu yang akan dicocokkan. Ini adalah string UTF-8 huruf kecil dengan panjang [1, 5000].
     • activeTimeRange:
       • START_TIMESTAMP: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.
       • END_TIMESTAMP: stempel waktu dalam format RFC 3339 UTC "Zulu" untuk menunjukkan akhir rentang waktu.
     • queryRegex: hanya tersedia untuk penyimpanan data dengan penelusuran situs dasar. Kolom ini tidak dapat digunakan dengan kolom queryTerms.
       • VALUE_REGEX: ekspresi reguler untuk mencocokkan kueri.
   • DATA_STORE_RESOURCE_PATH: jalur resource lengkap penyimpanan data yang hasil penelusurannya berisi URL yang dipromosikan. Format jalur resource lengkap adalah projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.
   • DOCUMENT_RESOURCE_PATH: kolom untuk menentukan jalur resource dokumen dari dokumen yang akan dipromosikan:
     • Untuk penyimpanan data penelusuran dengan data terstruktur dan tidak terstruktur, Anda harus memberikan jalur resource dokumen di kolom DOCUMENT_RESOURCE_PATH, URI di kolom URI, atau keduanya. Format jalur resource lengkap adalah projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
     • Untuk penyimpanan data situs, kolom ini harus dibatalkan dan kolom URI harus disetel.
   • TITLE: kolom wajib diisi untuk menentukan judul dokumen atau halaman web yang akan dipromosikan. Judul ini ditampilkan di hasil penelusuran.
   • URI: kolom wajib diisi untuk menentukan link URI tempat hasil penelusuran mengarahkan pengguna. URI ini tidak perlu disertakan dalam penyimpanan data.
     • Untuk penyimpanan data penelusuran dengan data terstruktur dan tidak terstruktur, Anda harus memberikan jalur resource dokumen di kolom DOCUMENT_RESOURCE_PATH, URI di kolom URI, atau keduanya.
     • Untuk penyimpanan data situs, kolom ini wajib diisi dan Anda harus menyetelnya.
   • DESCRIPTION: kolom opsional untuk mendeskripsikan dokumen atau halaman web yang akan dipromosikan, yang ditampilkan di hasil penelusuran.
   • ENABLED_TRUE|FALSE: kolom boolean opsional untuk menunjukkan apakah kontrol promosi diaktifkan dan dilampirkan ke aplikasi. Kolom ini hanya berlaku untuk penyimpanan data situs dengan penelusuran situs dasar. Jika Anda menyetel kolom ini ke false, kontrol penayangan promosi akan dinonaktifkan dan agar kontrol diterapkan, Anda harus memperbarui kontrol dengan mengaktifkannya, seperti yang dijelaskan pada langkah berikutnya. Untuk mengetahui informasi selengkapnya, lihat promoteAction.

   Respons

   Anda akan melihat respons JSON seperti berikut:

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

3. Untuk semua aplikasi penelusuran kecuali penelusuran situs dasar, lampirkan kontrol ke konfigurasi penayangan aplikasi menggunakan metode engines.servingConfigs.patch. Urutan lampiran promoteControlIds dalam permintaan berikut adalah urutan hasil promosi ditampilkan.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
   -d '{
     "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
   }'

   Ganti PROMOTE_ID_N dengan ID kontrol yang Anda buat pada langkah sebelumnya.

4. Opsional: Untuk penelusuran situs dasar, Anda tidak perlu melampirkan kontrol ke konfigurasi penayangan aplikasi. Namun, untuk penelusuran situs dasar, Anda dapat mengaktifkan atau menonaktifkan kontrol promosi setelah kontrol dibuat, dengan memanggil metode engines.control.patch.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
   -d '{
   "promoteAction": {
     "searchLinkPromotion": {
        "enabled": ENABLED_TRUE|FALSE,
     }
   }
   }'

Contoh

Saat Anda mengirim permintaan penelusuran ke aplikasi dengan kueri yang cocok dengan kueri atau ekspresi reguler kueri yang ditentukan untuk kontrol promosi, link yang dipromosikan akan muncul dalam respons.

Misalnya, Anda membuat kontrol promosi dengan konfigurasi berikut di penyimpanan data dengan penelusuran situs dasar:

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

Kemudian, Anda mengirim permintaan search berikut:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Anda akan menerima respons JSON yang mirip dengan respons yang dipangkas berikut. Respons berisi kolom searchLinkPromotions yang berisi link promosi.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Langkah berikutnya

• Untuk memahami dampak kontrol penayangan pada kualitas penelusuran aplikasi penelusuran kustom, evaluasi kualitas penelusuran. Untuk mengetahui informasi selengkapnya, lihat Mengevaluasi kualitas penelusuran.