Method: projects.locations.collections.dataStores.servingConfigs.search

Melakukan penelusuran.

Permintaan HTTP

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:search

URL menggunakan sintaks gRPC Transcoding.

Parameter jalur

Parameter
servingConfig

string

Wajib. Nama resource konfigurasi penayangan servingConfigs.search, seperti projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config, atau projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. Kolom ini digunakan untuk mengidentifikasi nama konfigurasi penayangan, kumpulan model yang digunakan untuk melakukan penelusuran.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  }
}
Kolom
branch

string

Nama resource cabang, seperti projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

Gunakan default_branch sebagai ID cabang atau biarkan kolom ini kosong, untuk menelusuri dokumen di cabang default.
query

string

Kueri penelusuran mentah.
imageQuery

object (ImageQuery)

Kueri gambar mentah.
pageSize

integer

Jumlah maksimum Document yang akan ditampilkan. Nilai maksimum yang diizinkan bergantung pada jenis data. Nilai di atas nilai maksimum akan dikonversi menjadi nilai maksimum.

  • Situs dengan pengindeksan dasar: Default 10, Maksimum 25.
  • Situs dengan pengindeksan lanjutan: Default 25, Maksimum 50.
  • Lainnya: Default 50, Maksimum 100.

Jika kolom ini negatif, INVALID_ARGUMENT akan ditampilkan.
pageToken

string

Token halaman yang diterima dari panggilan SearchService.Search sebelumnya. Berikan ini untuk mengambil halaman selanjutnya.

Saat melakukan penomoran halaman, semua parameter lain yang disediakan untuk SearchService.Search harus sesuai dengan panggilan yang memberikan token halaman. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
offset

integer

Bilangan bulat berindeks 0 yang menentukan offset saat ini (yaitu, lokasi hasil awal, di antara Document yang dianggap relevan oleh API) dalam hasil penelusuran. Kolom ini hanya dipertimbangkan jika pageToken tidak ditetapkan.

Jika kolom ini negatif, INVALID_ARGUMENT akan ditampilkan.

Offset besar dapat dibatasi hingga nilai minimum yang wajar.
oneBoxPageSize

integer

Jumlah maksimum hasil yang akan ditampilkan untuk OneBox. Hal ini berlaku untuk setiap jenis OneBox secara terpisah. Jumlah defaultnya adalah 10.
dataStoreSpecs[]

object (DataStoreSpec)

Spesifikasi yang menentukan DataStore tertentu yang akan ditelusuri, beserta konfigurasi untuk penyimpanan data tersebut. Hal ini hanya dipertimbangkan untuk Engine dengan beberapa penyimpanan data. Untuk mesin dengan satu penyimpanan data, spesifikasi langsung di bawah SearchRequest harus digunakan.
filter

string

Sintaksis filter terdiri dari bahasa ekspresi untuk membuat predikat dari satu atau beberapa kolom dokumen yang difilter. Ekspresi filter peka huruf besar/kecil.

Jika kolom ini tidak dapat dikenali, INVALID_ARGUMENT akan ditampilkan.

Pemfilteran di Vertex AI servingConfigs.search dilakukan dengan memetakan kunci filter LHS ke properti kunci yang ditentukan di backend Vertex AI servingConfigs.search -- pemetaan ini ditentukan oleh pelanggan dalam skemanya. Misalnya, pelanggan media mungkin memiliki kolom 'name' dalam skemanya. Dalam hal ini, filter akan terlihat seperti ini: filter --> name:'ANY("king kong")'

Untuk mengetahui informasi selengkapnya tentang pemfilteran, termasuk sintaksis dan operator filter, lihat Filter
canonicalFilter

string

Filter default yang diterapkan saat pengguna melakukan penelusuran tanpa mencentang filter apa pun di halaman penelusuran.

Filter yang diterapkan ke setiap permintaan penelusuran saat peningkatan kualitas seperti perluasan kueri diperlukan. Jika kueri tidak memiliki jumlah hasil yang memadai, filter ini akan digunakan untuk menentukan apakah alur perluasan kueri akan diaktifkan atau tidak. Filter asli akan tetap digunakan untuk penelusuran yang diperluas kuerinya. Kolom ini sangat direkomendasikan untuk mencapai kualitas penelusuran yang tinggi.

Untuk mengetahui informasi selengkapnya tentang sintaksis filter, lihat SearchRequest.filter.
orderBy

string

Urutan dokumen yang ditampilkan. Dokumen dapat diurutkan berdasarkan kolom dalam objek Document. Biarkan tidak disetel jika diurutkan berdasarkan relevansi. Ekspresi orderBy peka huruf besar/kecil.

Untuk mengetahui informasi selengkapnya tentang cara mengurutkan hasil penelusuran situs, lihat Mengurutkan hasil penelusuran web. Untuk mengetahui informasi selengkapnya tentang pengurutan hasil penelusuran layanan kesehatan, lihat Mengurutkan hasil penelusuran layanan kesehatan. Jika kolom ini tidak dapat dikenali, INVALID_ARGUMENT akan ditampilkan.
userInfo

object (UserInfo)

Informasi tentang pengguna akhir. Sangat direkomendasikan untuk analisis dan personalisasi. UserInfo.user_agent digunakan untuk menyimpulkan deviceType untuk analisis.
languageCode

string

Kode bahasa BCP-47, seperti "en-US" atau "sr-Latn". Untuk mengetahui informasi selengkapnya, lihat Kolom standar. Kolom ini membantu menafsirkan kueri dengan lebih baik. Jika nilai tidak ditentukan, kode bahasa kueri akan dideteksi secara otomatis, yang mungkin tidak akurat.
facetSpecs[]

object (FacetSpec)

Spesifikasi faset untuk penelusuran dengan faset. Jika kosong, tidak ada faset yang ditampilkan.

Maksimum 100 nilai yang diizinkan. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
boostSpec

object (BoostSpec)

Spesifikasi peningkat untuk meningkatkan kualitas dokumen tertentu. Untuk mengetahui informasi selengkapnya tentang promosi, lihat Promosi
params

map (key: string, value: value (Value format))

Parameter penelusuran tambahan.

Untuk penelusuran situs publik saja, nilai yang didukung adalah:

  • user_country_code: string. Default kosong. Jika disetel ke tidak kosong, hasil akan dibatasi atau ditingkatkan berdasarkan lokasi yang diberikan. Misalnya, user_country_code: "au"

Untuk kode yang tersedia, lihat Kode Negara

  • searchType: double. Default kosong. Mengaktifkan penelusuran non-halaman web bergantung pada nilainya. Satu-satunya nilai non-default yang valid adalah 1, yang mengaktifkan penelusuran gambar. Misalnya, searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

Spesifikasi perluasan kueri yang menentukan kondisi saat perluasan kueri terjadi.
spellCorrectionSpec

object (SpellCorrectionSpec)

Spesifikasi koreksi ejaan yang menentukan mode yang digunakan untuk menerapkan koreksi ejaan.
userPseudoId

string

ID unik untuk melacak pengunjung. Misalnya, hal ini dapat diterapkan dengan cookie HTTP, yang harus dapat mengidentifikasi pengunjung secara unik di satu perangkat. ID unik ini tidak boleh berubah jika pengunjung login atau logout dari situs.

Kolom ini TIDAK boleh memiliki nilai tetap seperti unknown_visitor.

ID ini harus sama dengan UserEvent.user_pseudo_id dan CompleteQueryRequest.user_pseudo_id

Kolom harus berupa string berenkode UTF-8 dengan batas panjang 128 karakter. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.
contentSearchSpec

object (ContentSearchSpec)

Spesifikasi untuk mengonfigurasi perilaku penelusuran konten.
rankingExpression

string

Opsional. Ekspresi peringkat mengontrol peringkat yang disesuaikan pada dokumen pengambilan. Tindakan ini akan menggantikan ServingConfig.ranking_expression. Sintaksis dan fitur yang didukung bergantung pada nilai rankingExpressionBackend. Jika rankingExpressionBackend tidak diberikan, nilai defaultnya adalah RANK_BY_EMBEDDING.

Jika rankingExpressionBackend tidak disediakan atau disetel ke RANK_BY_EMBEDDING, nilai tersebut harus berupa satu fungsi atau beberapa fungsi yang digabungkan dengan "+".

  • rankingExpression = function, { " + ", function };

Fungsi yang didukung:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Variabel fungsi:

  • relevanceScore: kata kunci yang telah ditentukan sebelumnya, digunakan untuk mengukur relevansi antara kueri dan dokumen.
  • embedding_field_path: kolom embedding dokumen yang digunakan dengan vektor embedding kueri.
  • dotProduct: fungsi embedding antara embedding_field_path dan vektor embedding kueri.

Contoh ekspresi peringkat:

Jika dokumen memiliki kolom penyematan doc_embedding, ekspresi peringkatnya bisa berupa 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding).

Jika rankingExpressionBackend disetel ke RANK_BY_FORMULA, jenis ekspresi berikut (dan kombinasi yang dirangkai menggunakan operator + atau *) didukung:

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0) -- transformasi peringkat timbal balik dengan argumen kedua berupa konstanta penyebut.
  • isNan(signal) -- menampilkan 0 jika sinyal adalah NaN, 1 jika tidak.
  • fillNan(signal1, signal2 | double) -- jika signal1 adalah NaN, menampilkan signal2 | ganda, jika tidak, menampilkan signal1.

Berikut beberapa contoh formula peringkat yang menggunakan jenis ekspresi peringkat yang didukung:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- sebagian besar diberi peringkat berdasarkan logaritma keywordSimilarityScore dengan sedikit penyesuaian semantic_smilarity_score.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) -- peringkat berdasarkan eksponen semanticSimilarityScore, mengisi nilai dengan 0 jika NaN, juga menambahkan penyesuaian konstanta 0,3 ke skor akhir jika semanticSimilarityScore adalah NaN.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16) -- sebagian besar diberi peringkat berdasarkan peringkat kebalikan keywordSimilarityScore dengan sedikit penyesuaian peringkat kebalikan semantic_smilarity_score.

Sinyal berikut didukung:

  • semanticSimilarityScore: penyesuaian kesamaan semantik yang dihitung menggunakan embedding yang dihasilkan oleh model Google eksklusif. Skor ini menentukan seberapa mirip kueri penelusuran dengan dokumen secara semantik.
  • keywordSimilarityScore: penyesuaian kecocokan kata kunci menggunakan fungsi pemberian peringkat Best Match 25 (BM25). Skor ini dihitung menggunakan model probabilistik untuk memperkirakan probabilitas bahwa dokumen relevan dengan kueri tertentu.
  • relevanceScore: penyesuaian relevansi semantik yang menggunakan model eksklusif Google untuk menentukan makna dan niat di balik kueri pengguna dalam konteks dengan konten dalam dokumen.
  • pctrRank: penyesuaian rasio konversi yang diprediksi sebagai penggunaan peringkat, rasio klik-tayang (pCTR) yang diprediksi untuk mengukur relevansi dan daya tarik hasil penelusuran dari perspektif pengguna. pCTR yang lebih tinggi menunjukkan bahwa hasil lebih mungkin memuaskan kueri dan niat pengguna, sehingga menjadikannya sinyal yang berharga untuk pemberian peringkat.
  • freshnessRank: penyesuaian keaktualan sebagai peringkat
  • documentAge: Waktu dalam jam yang berlalu sejak dokumen terakhir diperbarui, bilangan floating point (misalnya, 0,25 berarti 15 menit).
  • topicalityRank: penyesuaian topik sebagai peringkat. Menggunakan model Google eksklusif untuk menentukan tumpang-tindih berbasis kata kunci antara kueri dan dokumen.
  • baseRank: peringkat default hasil
rankingExpressionBackend

enum (RankingExpressionBackend)

Opsional. Backend yang akan digunakan untuk evaluasi ekspresi peringkat.
userLabels

map (key: string, value: string)

Label pengguna yang diterapkan ke resource harus memenuhi persyaratan berikut:

  • Setiap resource dapat memiliki beberapa label, hingga maksimum 64 label.
  • Setiap label harus berupa pasangan nilai kunci.
  • Kunci memiliki panjang minimum 1 karakter dan panjang maksimum 63 karakter, serta tidak boleh kosong. Nilai boleh kosong dan memiliki panjang maksimum 63 karakter.
  • Kunci dan nilai hanya boleh berisi huruf kecil, karakter numerik, garis bawah, dan tanda hubung. Semua karakter harus menggunakan encoding UTF-8, dan karakter internasional boleh digunakan.
  • Bagian kunci label harus unik. Namun, Anda dapat menggunakan kunci yang sama dengan beberapa resource.
  • Kunci harus diawali dengan huruf kecil atau karakter internasional.

Lihat Dokumen Google Cloud untuk mengetahui detail selengkapnya.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Opsional. Konfigurasi untuk kemampuan pemahaman kueri bahasa natural, seperti mengekstrak filter kolom terstruktur dari kueri. Baca dokumentasi ini untuk mengetahui informasi selengkapnya. Jika naturalLanguageQueryUnderstandingSpec tidak ditentukan, tidak ada pemahaman kueri bahasa alami tambahan yang akan dilakukan.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search saat Anda mengetik konfigurasi. Hanya didukung untuk kategori IndustryVertical.MEDIA.
displaySpec

object (DisplaySpec)

Opsional. Konfigurasi untuk fitur tampilan, seperti penyorotan kecocokan pada hasil penelusuran.
session

string

Nama resource sesi. Opsional.

Sesi memungkinkan pengguna melakukan panggilan API multi-turn /search atau koordinasi antara panggilan API /search dan panggilan API /answer.

Contoh #1 (panggilan API multi-turn /search): Panggil /search API dengan ID sesi yang dihasilkan pada panggilan pertama. Di sini, kueri penelusuran sebelumnya dipertimbangkan dalam posisi kueri. Artinya, jika kueri pertama adalah "Bagaimana kinerja Alphabet pada tahun 2022?" dan kueri saat ini adalah "Bagaimana dengan tahun 2023?", kueri saat ini akan ditafsirkan sebagai "Bagaimana kinerja Alphabet pada tahun 2023?".

Contoh #2 (koordinasi antara panggilan API /search dan panggilan API /answer): Panggil API /answer dengan ID sesi yang dibuat pada panggilan pertama. Di sini, pembuatan jawaban terjadi dalam konteks hasil penelusuran dari panggilan penelusuran pertama.

Fitur Multi-turn servingConfigs.search saat ini dalam tahap GA pribadi. Gunakan versi v1alpha atau v1beta sebelum kami meluncurkan fitur ini ke GA publik. Atau, minta agar Anda dimasukkan ke daftar yang diizinkan melalui tim Dukungan Google.
sessionSpec

object (SessionSpec)

Spesifikasi sesi.

Hanya dapat digunakan jika session disetel.
relevanceThreshold

enum (RelevanceThreshold)

Nilai minimum relevansi hasil penelusuran.

Secara default, menggunakan nilai minimum yang ditentukan Google, dengan memanfaatkan keseimbangan presisi dan perolehan untuk memberikan hasil yang sangat akurat dan cakupan komprehensif informasi yang relevan.

Fitur ini tidak didukung untuk penelusuran layanan kesehatan.
relevanceScoreSpec

object (RelevanceScoreSpec)

Opsional. Spesifikasi untuk menampilkan skor relevansi.

Isi respons

Jika berhasil, isi respons akan berisi instance SearchResponse.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.

Izin IAM

Memerlukan izin IAM berikut pada resource servingConfig:

  • discoveryengine.servingConfigs.search

Untuk mengetahui informasi selengkapnya, lihat dokumentasi IAM.