Method: projects.locations.collections.engines.servingConfigs.recommend

Membuat rekomendasi, yang memerlukan peristiwa pengguna kontekstual.

Permintaan HTTP

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:recommend

URL menggunakan sintaks gRPC Transcoding.

Parameter jalur

Parameter
servingConfig

string

Wajib. Nama lengkap resource ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/*, atau projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Satu konfigurasi penayangan default dibuat bersamaan dengan pembuatan mesin pemberi saran Anda. ID mesin telusur digunakan sebagai ID konfigurasi penayangan default. Misalnya, untuk Engine projects/*/locations/global/collections/*/engines/my-engine, Anda dapat menggunakan projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine untuk permintaan RecommendationService.Recommend.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Kolom
userEvent

object (UserEvent)

Wajib. Konteks tentang pengguna, apa yang mereka lihat, dan tindakan apa yang mereka lakukan untuk memicu permintaan servingConfigs.recommend. Perhatikan bahwa detail peristiwa pengguna ini tidak akan diproses ke log userEvent. Oleh karena itu, permintaan penulisan userEvent terpisah diperlukan untuk pencatatan peristiwa.

Jangan menetapkan UserEvent.user_pseudo_id atau UserEvent.user_info.user_id ke ID tetap yang sama untuk pengguna yang berbeda. Jika Anda mencoba menerima rekomendasi yang tidak dipersonalisasi (tidak direkomendasikan; hal ini dapat berdampak negatif pada performa model), tetapkan UserEvent.user_pseudo_id ke ID unik acak dan biarkan UserEvent.user_info.user_id tidak ditetapkan.
pageSize

integer

Jumlah hasil maksimum dalam satu halaman. Tetapkan properti ini ke jumlah hasil rekomendasi yang diperlukan. Jika nol, layanan akan memilih default yang wajar. Nilai maksimum yang diizinkan adalah 100. Nilai di atas 100 ditetapkan ke 100.
filter

string

Filter untuk membatasi hasil rekomendasi dengan batas panjang 5.000 karakter. Saat ini, hanya ekspresi filter pada atribut filterTags yang didukung.

Contoh:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

Jika attributeFilteringSyntax disetel ke benar (true) di kolom params, maka ekspresi berbasis atribut akan diharapkan, bukan sintaksis berbasis tag yang dijelaskan di atas. Contoh:

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

Jika filter Anda memblokir semua hasil, API akan menampilkan Dokumen populer generik (tanpa filter). Jika Anda hanya menginginkan hasil yang benar-benar cocok dengan filter, tetapkan strictFiltering ke true di RecommendRequest.params untuk menerima hasil kosong.

Perhatikan bahwa API tidak pernah menampilkan Document dengan storageStatus sebagai EXPIRED atau DELETED, terlepas dari pilihan filter.
validateOnly

boolean

Gunakan mode hanya validasi untuk kueri rekomendasi ini. Jika disetel ke true, model palsu yang menampilkan ID Dokumen arbitrer akan digunakan. Perhatikan bahwa mode hanya validasi hanya boleh digunakan untuk menguji API, atau jika model belum siap.
params

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

Parameter tambahan khusus domain untuk rekomendasi.

Nilai yang diizinkan:

  • returnDocument: Boolean. Jika disetel ke true, objek Dokumen terkait akan ditampilkan di RecommendResponse.RecommendationResult.document.
  • returnScore: Boolean. Jika disetel ke benar (true), skor rekomendasi yang sesuai dengan setiap Dokumen yang ditampilkan akan disetel di RecommendResponse.RecommendationResult.metadata. Skor yang diberikan menunjukkan probabilitas konversi Dokumen berdasarkan konteks dan histori pengguna.
  • strictFiltering: Boolean. Benar secara default. Jika disetel ke false, layanan akan menampilkan Dokumen populer generik (tanpa filter), bukan kosong, jika filter Anda memblokir semua hasil rekomendasi.
  • diversityLevel: String. Default kosong. Jika ditetapkan agar tidak kosong, maka harus berupa salah satu dari:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Hal ini memberikan kontrol tingkat permintaan dan menyesuaikan hasil rekomendasi berdasarkan Kategori dokumen.
  • attributeFilteringSyntax: Boolean. False secara default. Jika disetel ke benar (true), kolom filter ditafsirkan sesuai dengan sintaksis baru berbasis atribut.
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 Persyaratan untuk label untuk mengetahui detail selengkapnya.

Isi respons

Jika berhasil, isi respons akan berisi instance RecommendResponse.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

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

Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.

Izin IAM

Memerlukan izin IAM berikut pada resource servingConfig:

  • discoveryengine.servingConfigs.recommend

Untuk mengetahui informasi selengkapnya, lihat dokumentasi IAM.