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

Membuat rekomendasi, yang memerlukan peristiwa pengguna kontekstual.

Permintaan HTTP

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

URL menggunakan sintaks gRPC Transcoding.

Parameter jalur

Parameter
servingConfig

string

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

Satu konfigurasi penayangan default dibuat bersama dengan pembuatan mesin rekomendasi Anda. ID mesin 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 diisi. 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 di-ingest ke log userEvent. Oleh karena itu, permintaan tulis userEvent terpisah diperlukan untuk logging peristiwa.

Jangan tetapkan UserEvent.user_pseudo_id atau UserEvent.user_info.user_id ke ID tetap yang sama untuk pengguna yang berbeda. Jika Anda mencoba menerima rekomendasi non-personalisasi (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 ditetapkan ke true di kolom params, 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 (tidak difilter). 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 validasi saja untuk kueri rekomendasi ini. Jika ditetapkan ke true, model palsu akan digunakan yang menampilkan ID Dokumen arbitrer. Perhatikan bahwa mode validasi saja hanya boleh digunakan untuk menguji API, atau jika model belum siap.
params

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

Parameter khusus domain tambahan untuk rekomendasi.

Nilai yang diizinkan:

  • returnDocument: Boolean. Jika ditetapkan ke true, objek Dokumen terkait akan ditampilkan di RecommendResponse.RecommendationResult.document.
  • returnScore: Boolean. Jika ditetapkan ke true, skor rekomendasi yang sesuai dengan setiap Dokumen yang ditampilkan akan ditetapkan di RecommendResponse.RecommendationResult.metadata. Skor yang diberikan menunjukkan probabilitas konversi Dokumen berdasarkan konteks dan histori pengguna.
  • strictFiltering: Boolean. Benar secara default. Jika ditetapkan ke false, layanan akan menampilkan Dokumen populer generik (tidak difilter), bukan kosong jika filter Anda memblokir semua hasil rekomendasi.
  • diversityLevel: String. Default kosong. Jika ditetapkan agar tidak kosong, nilai tersebut harus salah satu dari:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Opsi ini memberikan kontrol tingkat permintaan dan menyesuaikan hasil rekomendasi berdasarkan kategori Dokumen.
  • attributeFilteringSyntax: Boolean. Salah secara default. Jika ditetapkan ke true, kolom filter akan ditafsirkan sesuai dengan sintaksis berbasis atribut yang baru.
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 dan tidak boleh kosong. Nilai dapat kosong dan memiliki panjang maksimum 63 karakter.
  • Kunci dan nilai hanya boleh berisi huruf kecil, karakter numerik, garis bawah, dan tanda pisah. 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 guna mengetahui detail selengkapnya.

Isi respons

Jika berhasil, isi respons akan memuat instance RecommendResponse.

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.serving.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.