Kontrol penayangan (juga disebut kontrol) mengubah perilaku default cara permintaan ditayangkan saat hasil ditampilkan. Kontrol penayangan bertindak di tingkat penyimpanan data.
Misalnya, kontrol dapat meningkatkan dan menyembunyikan 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 informasi tentang penggunaan kontrol penayangan dengan rekomendasi media, lihat Membuat dan mengelola konfigurasi penayangan.
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 peningkatan, memiliki dependensi pada penyimpanan data. Jika penyimpanan data dihapus dari aplikasi, kontrol apa pun 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 boost | Mengubah urutan hasil yang ditampilkan | Menelusuri aplikasi 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 | Menelusuri aplikasi dengan penyimpanan data yang mendukung skema, seperti penyimpanan data yang berisi data terstruktur, situs (pengindeksan situs lanjutan dan penelusuran situs dasar), data tidak terstruktur dengan metadata, atau data media |
Kontrol sinonim | Mengaitkan kueri satu sama lain | Menelusuri aplikasi dengan situs (pengindeksan situs lanjutan), penyimpanan data terstruktur, tidak terstruktur, atau media |
Kontrol pengalihan | Mengalihkan ke URI yang ditentukan | Semua aplikasi penelusuran |
Tentang kondisi
Saat membuat kontrol, Anda dapat menentukan kondisi yang menentukan kapan kontrol diterapkan secara opsional. Kondisi ditentukan menggunakan kolom kondisi. Kolom kondisi berikut tersedia:
queryTerms
. Kontrol opsional yang diterapkan saat kueri tertentu ditelusuri. Saat kondisiqueryTerms
digunakan, kontrol diterapkan saat nilaiqueryTerms
cocok dengan istilah dalamSearchRequest.query
. Istilah kueri hanya dapat digunakan jikaControl.searchUseCase
ditetapkan sebagaiSOLUTION_TYPE_SEARCH
. Maksimal 10queryTerms
yang berbeda dapat ditentukan di satuControl.condition
. Jika tidak ada istilah kueri yang ditentukan, kolomqueryTerms
akan diabaikan.activeTimeRange
. Kontrol opsional yang diterapkan saat permintaan terjadi dalam rentang waktu yang ditentukan. Fungsi ini memeriksa apakah waktu permintaan diterima antaraactiveTimeRange.startTime
danactiveTimeRange.endTime
. Maksimal 10 rentangactiveTimeRange
dapat ditentukan pada satuControl.condition
. Jika kolomactiveTimeRange
tidak ditentukan, kolom tersebut akan diabaikan.
Jika kedua jenis kondisi ditentukan untuk kontrol, kontrol akan diterapkan ke permintaan penelusuran saat kedua jenis kondisi terpenuhi. Jika beberapa nilai untuk kondisi yang sama ditentukan, hanya salah satu nilai yang perlu 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 boost
Kontrol penayangan boost ditentukan sebagai kontrol dengan boostAction
.
Gunakan petunjuk berikut untuk membuat kontrol penayangan boost.
Untuk mengetahui detail kolom, lihat
referensi API engines.controls
dan
referensi API engines.controls.create
.
Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.
Di konsol Google Cloud, buka halaman Agent Builder.
Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.
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 project Google Cloud 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 menggunakan kontrol. Harus berupa string berenkode UTF-8 dengan panjang [1,128].USE_CASE
: harusSEARCH_USE_CASE_SEARCH
atauSEARCH_USE_CASE_BROWSE
. JikaSEARCH_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]
. JikaFULL_MATCH_1
adalahtrue
, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.FULL_MATCH
: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ketrue
,SearchRequest.query
harus sepenuhnya cocok denganqueryTerm.value
. Jika ditetapkan kefalse
,SearchRequest.query
harus berisiqueryTerm.value
sebagai substring.START_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.END_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
BOOST_VALUE
: bilangan floating point dalam rentang [-1,1]. Jika nilainya negatif, hasil akan diturunkan (muncul lebih rendah dalam hasil). Jika nilainya positif, hasil akan dipromosikan (muncul lebih tinggi di hasil). Untuk informasi selengkapnya, lihatboostAction
.FILTER
: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, peningkatan akan diterapkan. Jika tidak, tidak ada perubahan. Jika kolom ini kosong, pengoptimalan akan diterapkan ke semua dokumen di penyimpanan data. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Catatan: Kolom dokumentitle
tidak dapat difilter.DATA_STORE_RESOURCE_PATH
: jalur resource lengkap dari penyimpanan data yang dokumennya harus dioptimalkan oleh kontrol ini. Format jalur resource lengkap adalahprojects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID
. Penyimpanan data ini harus dilampirkan ke mesin yang ditentukan dalam permintaan.
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 di 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
.
Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.
Di konsol Google Cloud, buka halaman Agent Builder.
Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.
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 project Google Cloud 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 menggunakan kontrol. Harus berupa string berenkode UTF-8 dengan panjang [1,128].USE_CASE
: harusSEARCH_USE_CASE_SEARCH
atauSEARCH_USE_CASE_BROWSE
. JikaSEARCH_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]
. JikaFULL_MATCH_1
adalahtrue
, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.FULL_MATCH
: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ketrue
,SearchRequest.query
harus sepenuhnya cocok denganqueryTerm.value
. Jika ditetapkan kefalse
,SearchRequest.query
harus berisiqueryTerm.value
sebagai substring.START_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.END_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
FILTER
: string yang menentukan persyaratan yang harus dipenuhi oleh dokumen. Jika dokumen cocok dengan semua persyaratan, dokumen tersebut akan ditampilkan dalam hasil. Jika tidak, dokumen tidak akan ada dalam hasil. Untuk sintaksis pemfilteran, lihat Sintaksis ekspresi filter. Untuk informasi selengkapnya, lihatfilterAction
. Catatan: Kolom dokumentitle
tidak dapat difilter.
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 di 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
.
Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.
Di konsol Google Cloud, buka halaman Agent Builder.
Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.
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 project Google Cloud 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 menggunakan kontrol. Harus berupa string berenkode UTF-8 dengan panjang [1,128].USE_CASE
: harusSEARCH_USE_CASE_SEARCH
atauSEARCH_USE_CASE_BROWSE
. JikaSEARCH_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]
. JikaFULL_MATCH_1
adalahtrue
, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.FULL_MATCH
: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ketrue
,SearchRequest.query
harus sepenuhnya cocok denganqueryTerm.value
. Jika ditetapkan kefalse
,SearchRequest.query
harus berisiqueryTerm.value
sebagai substring.START_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.END_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan akhir rentang waktu.
SYNONYMS_N
: daftar string yang terkait satu sama lain, sehingga setiap string lebih cenderung menampilkan hasil yang serupa. Meskipun Anda cenderung mendapatkan hasil yang serupa, saat menelusuri setiap entri sinonim, Anda mungkin tidak menerima semua hasil yang relevan untuk semua sinonim terkait. Anda harus menentukan minimal dua sinonim dan dapat menentukan hingga 100 sinonim. Setiap sinonim harus dienkode UTF-8 dan dalam huruf kecil. String duplikat tidak diizinkan. Misalnya, Anda dapat menambahkan "pixel", "ponsel android", dan "ponsel google" sebagai sinonim. Untuk informasi selengkapnya, lihatsynonymsAction
.
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 di 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
.
Temukan ID aplikasi Anda. Jika Anda sudah memiliki ID aplikasi, lanjutkan ke langkah berikutnya.
Di konsol Google Cloud, buka halaman Agent Builder.
Di halaman Aplikasi, temukan nama aplikasi Anda dan dapatkan ID aplikasi dari kolom ID.
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 project Google Cloud 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 menggunakan kontrol. Harus berupa string berenkode UTF-8 dengan panjang [1,128].USE_CASE
: harusSEARCH_USE_CASE_SEARCH
atauSEARCH_USE_CASE_BROWSE
. JikaSEARCH_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]
. JikaFULL_MATCH_1
adalahtrue
, kolom ini dapat memiliki maksimal tiga istilah yang dipisahkan spasi.FULL_MATCH
: boolean yang menunjukkan apakah kueri penelusuran harus sama persis dengan istilah kueri. Jika ditetapkan ketrue
,SearchRequest.query
harus sepenuhnya cocok denganqueryTerm.value
. Jika ditetapkan kefalse
,SearchRequest.query
harus berisiqueryTerm.value
sebagai substring.START_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 untuk menunjukkan awal rentang waktu.END_TIMESTAMP
: stempel waktu dalam format "Zulu" UTC RFC 3339 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 informasi selengkapnya, lihatredirectAction
.
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 di langkah sebelumnya.
Langkah selanjutnya
- Untuk memahami dampak kontrol penayangan pada kualitas penelusuran aplikasi penelusuran umum, evaluasi kualitas penelusuran. Untuk informasi selengkapnya, lihat Mengevaluasi kualitas penelusuran.