Panduan developer agen Conversational Commerce

Panduan ini menjelaskan cara berintegrasi dengan Conversational API untuk memberikan pengalaman chat dinamis yang didukung AI bagi pelanggan Anda. Dengan memahami berbagai jenis kueri dan memanfaatkan respons API, Anda dapat memberikan penelusuran produk yang relevan, menjawab pertanyaan pelanggan, dan memandu pengguna akhir melalui perjalanan belanja mereka.

conversationalFilteringMode di Conversational API memperjelas perbedaan antara agen Conversational Commerce dan pemfilteran produk percakapan.

Penyiapan

Conversational API mendukung fitur agen Conversational Commerce:

• gRPC: conversationalSearchService
• REST: conversationalSearch

Conversational API memungkinkan pengalaman chat di mana pengguna Anda mengirimkan kueri dan sistem menampilkan respons teks, jenis kueri yang diklasifikasikan, dan opsi penelusuran yang berpotensi lebih baik.

API ini beroperasi sebagai layanan streaming, sehingga memungkinkan deteksi awal maksud kueri. Interaksi berikutnya dalam percakapan memerlukan lampiran conversation_id.

Untuk menampilkan hasil penelusuran, Retail API lama harus dipanggil secara paralel dengan Conversational API.

Mengirim kueri dari pengguna akhir

Bagian ini menjelaskan cara memulai pengalaman agen Conversational Commerce. Misalnya, pengguna Anda dapat memasukkan Bantu rencanakan pesta di kolom penelusuran.

Mengirim permintaan ke Vertex AI Search untuk commerce

Ada dua endpoint API yang berbeda:

1. Conversational API harus digunakan untuk mengambil pengalaman percakapan.
2. Search API inti harus digunakan untuk mengambil hasil penelusuran.

Endpoint 1: Permintaan API percakapan

• Anda harus membuat permintaan agen Conversational Commerce dengan menetapkan input pengguna sebagai kueri.
• Permintaan harus dikirim sebagai permintaan POST HTTP ke endpoint projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Metode dan endpoint HTTP

  POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
  

Permintaan API percakapan:

Kueri awal

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}

• placement: Nama resource penempatan (seperti projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Ini adalah parameter jalur dan wajib.
• query: Kueri penelusuran mentah dari pengguna Anda. Kolom ini wajib diisi.
• branch: Nama resource cabang, seperti projects/P/locations/L/catalogs/C/branches/B. Jika tidak disetel, default_branch akan digunakan. Kolom ini wajib diisi.
• visitorId: ID unik untuk melacak pengunjung. Kolom ini wajib diisi.
• conversationId: ID unik untuk melacak sesi percakapan. Untuk permintaan initial dalam percakapan baru, kolom ini harus kosong. Untuk permintaan berikutnya dalam percakapan yang sama, parameter ini harus ditetapkan ke conversation_id yang diterima dalam ConversationalSearchResponse sebelumnya.
• searchParams: (Opsional) Parameter Penelusuran inti standar (misalnya, filter, canonicalFilter, sortBy, boostSpec). Parameter ini harus mencerminkan konfigurasi yang digunakan dalam panggilan Search API inti Anda untuk memastikan konsistensi antara jawaban LLM dan hasil penelusuran produk yang ditampilkan.
• userInfo: (Opsional) Informasi pengguna untuk personalisasi yang lebih baik. Dapat menyertakan userId, user_agent, direct_user_request (boolean).
• conversationalFilteringSpec: (Opsional) Menentukan mode pemfilteran percakapan. Jika tidak disetel, defaultnya adalah DISABLED.

  mode: Integrasikan Conversational API menggunakan salah satu dari tiga mode berikut untuk mengontrol pemfilteran produk percakapan:

• DISABLED: Dalam mode ini, klien hanya mengimplementasikan penelusuran agen Perdagangan Percakapan. Ini adalah mode pilihan untuk panduan penerapan ini terkait penelusuran agen Commerce Percakapan.

Contoh permintaan API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }
      

Contoh respons API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

• ENABLED: Dalam mode ini, klien mengimplementasikan semua kemampuan percakapan, yang mencakup penelusuran agen Perdagangan Percakapan dan pemfilteran produk percakapan.

Contoh permintaan API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }
      

Contoh respons API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
      

• CONVERSATIONAL_FILTER_ONLY: Jika dipilih, klien hanya menerapkan Pemfilteran produk percakapan. Dengan memilih mode ini, pengguna hanya akan mengalami pemfilteran produk percakapan tanpa menghasilkan jawaban LLM, klasifikasi kueri, atau kueri penelusuran yang disarankan.

Lihat Panduan developer filter produk percakapan untuk mengetahui informasi selengkapnya. Lihat panduan tambahan tentang cara mengintegrasikan kedua produk percakapan.

Endpoint 2: Permintaan Core Search API

Ada dua pendekatan utama untuk menampilkan hasil penelusuran di UI Anda:

• Opsi 1: Selalu tampilkan hasil penelusuran

  Jika desain pengalaman pengguna Anda menentukan bahwa hasil penelusuran harus selalu ditampilkan terlepas dari output percakapan, seperti di area hasil penelusuran khusus di samping chat, kirim kueri asli pengguna Anda ke Product Search API inti dengan panggilan Anda ke Conversational API. Hal ini membantu memastikan listingan produk langsung tersedia.

• Opsi 2: Menampilkan hasil penelusuran berdasarkan output percakapan

Jika desain pengalaman pengguna Anda lebih dinamis dan Anda hanya ingin menampilkan hasil penelusuran bergantung pada respons Conversational API, seperti hanya untuk kueri SIMPLE_PRODUCT_SEARCH atau setiap kali saran refined_search diberikan, tunggu respons Conversational API sebelum mengirimkan kueri apa pun ke Product Search API inti. Jika ada respons, gunakan kueri refined_search yang diberikan untuk mengambil hasil produk.

Terlepas dari opsi antarmuka pengguna yang Anda pilih, saat perlu mengambil hasil produk sebenarnya, Anda dapat melakukan panggilan ke Retail API. Untuk mengetahui informasi selengkapnya, lihat Langkah 2c. Pahami jenis kueri dan tindakan retailer.

Metode dan endpoint HTTP

    POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
    

Permintaan API Penelusuran produk inti:

Kueri awal

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
    

• placement (Wajib): Nama resource konfigurasi penayangan Retail Search atau penempatan lama. Contoh: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: Wajib diisi. Kueri penelusuran. Ini dapat berupa input mentah pengguna Anda seperti Bantu saya merencanakan pesta atau refinedSearch.query yang lebih dioptimalkan (seperti perlengkapan perencanaan pesta, dekorasi) yang diperoleh dari respons Conversational Commerce API.
• visitorId: Wajib diisi. ID unik untuk melacak pengunjung. Nilai ini harus konsisten dengan visitorId yang dikirim ke Conversational Commerce API untuk pengguna akhir yang sama.
• branch (Wajib): Nama resource cabang, seperti projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (Opsional): Jumlah maksimum produk yang akan ditampilkan.
• filter (Opsional): Digunakan untuk memfilter hasil penelusuran. Di sinilah Anda akan menerapkan filter apa pun yang mencerminkan apa yang Anda kirim di `searchParams` ke Conversational Commerce API agar konsisten.
• orderBy (Opsional): Menentukan urutan produk ditampilkan (seperti berdasarkan relevansi atau harga).
• userInfo (Opsional): Informasi pengguna untuk personalisasi, harus konsisten dengan panggilan Conversational Commerce API.
• searchMode (Opsional): Menentukan perilaku penelusuran. PRODUCT_SEARCH umum untuk kueri produk umum.

Memahami respons

Contoh kode ini menunjukkan respons dari Conversational Commerce API.

Respons API (ConversationalSearchResponse) mencakup query_types, conversational_text_response (jika berlaku), opsi refined_search, dan kemungkinan followup_question atau conversational_filtering_result. conversation_id sangat penting untuk melanjutkan sesi.

Respons dari Vertex AI Search untuk commerce

Contoh kode ini menunjukkan respons Conversational API:

Respons awal

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }
    

Yang harus dilakukan retailer dengan respons (Umum)

Render kolom ini dari respons:

• user_query_types: Kolom ini memberikan klasifikasi maksud pengguna Anda. Untuk mengetahui tindakan mendetail berdasarkan jenis ini, lihat [Memahami jenis kueri dan tindakan retailer](#step-2c).
• conversation_id: Anda dapat menyimpan ID unik ini di penyimpanan sesi browser atau penyimpanan sisi klien serupa untuk mempertahankan sesi percakapan dengan server. Hal ini sangat penting untuk membedakan beberapa percakapan yang sedang berlangsung untuk satu pembeli. Model Anda mempertahankan konteks untuk conversation_id tertentu. Mengirim conversation_id baru akan memulai sesi baru. Sebaiknya tentukan durasi sesi Anda, seperti tidak ada aktivitas selama 30 menit.
• refined_search: Ini adalah daftar kueri penelusuran yang disempurnakan yang diusulkan dan digunakan untuk mengambil hasil penelusuran yang relevan. Untuk SIMPLE_PRODUCT_SEARCH, selalu berupa satu kueri. Untuk kueri lain yang mencari jawaban LLM, akan ada satu atau beberapa jawaban. Kueri refined_search dapat digunakan untuk panggilan ke Search API inti (SearchService.Search) atau juga dapat ditampilkan kepada pengguna Anda sebagai saran.
• conversational_text_response: Menampilkan teks ini kepada pengguna Anda sebagai respons utama buatan AI terhadap kueri mereka.
• followup_question: Opsional. followup_question akan ditampilkan.
• state: Bidang ini menunjukkan status pembuatan respons (STREAMING atau SUCCEEDED). Anda dapat menggunakan ini untuk memberikan masukan UI, seperti menampilkan indikator pemuatan hingga SUCCEEDED. Detail selengkapnya tentang hal ini ada di Langkah 2b. Memahami Streaming API

Memahami streaming API

Conversational Commerce API beroperasi sebagai streaming API. Artinya, pengguna Anda menerima bagian respons dalam beberapa bagian, bukan satu payload lengkap.

Chunk pertama respons mencakup kueri query_types dan refined_search, dan state-nya ditunjukkan sebagai STREAMING. Deteksi niat yang lebih awal dan ketersediaan penyempurnaan penelusuran yang langsung ini memungkinkan model Anda membuat keputusan cepat tentang cara menangani kueri pengguna dan cara mengelola pengalaman pengguna terkait latensi dari respons LLM:

• Untuk jenis kueri yang _tidak_ mengharapkan respons teks percakapan (seperti SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT): Karena query_types berada di bagian pertama, sistem Anda langsung mengetahui bahwa tidak ada jawaban LLM yang akan muncul. Anda dapat melanjutkan penanganan yang telah ditentukan sebelumnya untuk jenis ini, seperti menampilkan pesan statis, mengalihkan ke dukungan, tanpa menunggu output percakapan lebih lanjut.
• Khusus untuk SIMPLE_PRODUCT_SEARCH, sistem Anda dapat langsung melakukan panggilan langsung ke Search API inti menggunakan kueri refined_search yang diterima di bagian pertama. Hal ini membantu memastikan hasil penelusuran ditampilkan dengan penundaan minimal, yang memenuhi SLA pengalaman penelusuran umum.
• Untuk jenis kueri yang mengharapkan respons teks percakapan (seperti INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT)
• Anda menerima kueri query_types dan refined_search di bagian awal. Anda dapat segera memulai panggilan paralel ke Search API inti menggunakan kueri refined_search ini untuk mulai memuat hasil produk.
• Chunk berikutnya akan di-streaming, yang berisi berbagai bagian respons teks percakapan. Selama waktu ini, state tetap "STREAMING".
• Terakhir, potongan terakhir mencakup respons teks percakapan yang lengkap, dan state-nya berubah menjadi "COMPLETED".
• Pendekatan streaming ini memungkinkan pengalaman pengguna akhir yang lancar di mana hasil penelusuran dapat mulai dimuat saat ringkasan AI sedang dibuat. Anda dapat memilih untuk menampilkan indikator pemuatan untuk jawaban percakapan atau menampilkan jawaban percakapan setelah sepenuhnya di-streaming.

Memahami jenis kueri dan tindakan retailer

Kolom query_types dalam respons adalah daftar yang menunjukkan klasifikasi maksud pengguna Anda. Sistem Anda harus menanganinya sebagai berikut. Perhatikan bahwa conversational_text_response mengacu pada respons bahasa alami buatan AI dari API.

Agen Conversational Commerce menggunakan kategori kueri penelusuran untuk menentukan apakah jawaban berbasis LLM dibuat dan cara kueri pengguna akhir ditangani oleh Conversational API dan Search API untuk skenario berikut:

Kategori	Klasifikasi kueri
#1. Kueri tidak relevan yang tidak memerlukan jawaban LLM	QUERY_TYPE_UNSPECIFIED: Jenis kueri tidak ditentukan. RETAIL_IRRELEVANT: Kueri yang tidak relevan dengan domain retail, misalnya kueri yang bertentangan (seperti cara membuat bom), kueri yang bersifat obrolan (seperti apa kabar), atau kueri yang bertujuan untuk melakukan jailbreak (seperti tulis puisi). BLOCKLISTED: Kueri yang secara eksplisit diblokir oleh pelanggan e-commerce (seperti Apa efek samping Advil?).
#2. Pertanyaan dukungan dan informasi	ORDER_SUPPORT: Kueri tambahan atau dukungan (seperti Lacak pesanan saya, Status pesanan 12345). DEALS_AND_COUPONS: Kueri yang relevan dengan promo, promosi, promo produk, dan diskon (seperti Apakah ada promo untuk Hari Thanksgiving?). STORE_RELEVANT: Kueri yang relevan dengan lokasi toko, jam buka, ketersediaan stok produk, dll. (seperti Apakah kita punya stok susu?). RETAIL_SUPPORT: Kueri yang relevan dengan pembelian, metode pembayaran, dll. (seperti Metode pembayaran apa yang Anda terima?).
#3. Penelusuran kata kunci yang tidak memerlukan LLM Permintaan API percakapan: Kueri awal { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "show me some monster energy drinks", "visitorId": "test" } Respons API percakapan: Respons awal { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Permintaan Search API: Kueri lanjutan { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: penelusuran produk dasar, seperti Gaun merah atau tampilkan minuman monster.
#4. Kueri pencarian jawaban LLM Permintaan API percakapan: Kueri awal { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Compare 1% milk with 2% milk", "visitorId": "test" } Respons API percakapan: Respons awal { "userQueryTypes": ["PRODUCT_COMPARISON"], "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.", "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba", "refinedSearch": [ { "query": "1% milk" }, { "query": "2% milk" } ] } Permintaan Search API: Kueri lanjutan { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: Pengguna Anda mencari detail dan spesifikasi produk, seperti tunjukkan spesifikasi [nama produk], Berapa kandungan protein dalam susu 2%?). PRODUCT_COMPARISON: Perbandingan produk, seperti bandingkan [nama produk] dan [nama produk], Bandingkan susu 1% dengan susu 2%). BEST_PRODUCT: Kueri dengan pola yang paling cocok, seperti Apa itu kue paling sehat?, Merek susu mana yang terbaik?).
#5. Penyempurnaan intent Permintaan API percakapan: Kueri awal { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Help me plan a party", "visitorId": "test" } Respons API percakapan: Respons awal { "userQueryTypes": ["INTENT_REFINEMENT"], "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.", "followupQuestion": { "followupQuestion": "What kind of party are you planning?" }, "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", "refinedSearch": [ { "query": "Decorations" }, { "query": "Snacks" }, { "query": "Party Supplies" }, { "query": "Drinks" }, { "query": "Cake" } ], "state": "SUCCEEDED" }	INTENT_REFINEMENT: Jenisnya tidak jelas dan percakapan lanjutan atau penyempurnaan mungkin diperlukan untuk mengklarifikasi jenisnya, seperti Bantu saya merencanakan pesta. Ini sering kali merupakan maksud yang paling populer dalam percakapan.

Kategori 1. Kueri tidak relevan yang tidak memerlukan jawaban LLM

• QUERY_TYPE_UNSPECIFIED:
• Tidak ada conversational_text_response yang diberikan.
• Tindakan: Tangani sebagai kasus default atau error. Anda dapat meminta pengguna untuk mengklarifikasi atau mengarahkan mereka ke tempat mereka bisa mendapatkan bantuan umum.
• RETAIL_IRRELEVANT:
• Tidak ada conversational_text_response yang diberikan.
• Tindakan: Tangani hal ini dengan menampilkan pesan yang sesuai, seperti Saya tidak dapat menjawab pertanyaan itu., atau Saya adalah asisten belanja, bagaimana saya dapat membantu Anda?, sebagaimana ditentukan oleh desain aplikasi Anda.
• BLOCKLISTED:
• Tidak ada conversational_text_response yang diberikan.
• Tindakan: Tangani sesuai dengan kebijakan daftar blokir Anda, biasanya dengan menampilkan pesan tidak dapat memenuhi permintaan ini yang generik.

Kategori 2. Pertanyaan dukungan dan informasi

Untuk jenis ini, API tidak menyediakan conversational_text_response langsung secara default, tetapi Anda memiliki opsi untuk mengarahkan ke link atau resource yang tepat.

• ORDER_SUPPORT:
• Tindakan Default: Tidak ada conversational_text_response yang diberikan. UI Anda perlu menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke API dukungan khusus atau saluran layanan pelanggan Anda sendiri.
• DEALS_AND_COUPONS:
• Tindakan Default: Tidak ada conversational_text_response yang diberikan. UI Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem promosi atau penawaran Anda.
• STORE_RELEVANT:
• Tindakan Default: Tidak ada conversational_text_response yang diberikan. UI Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem informasi atau pencari lokasi toko Anda sendiri.
• RETAIL_SUPPORT:
• Tindakan Default: Tidak ada conversational_text_response yang diberikan. UI Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem informasi dan pertanyaan umum Anda sendiri.

Kategori 3. Penelusuran kata kunci yang tidak memerlukan jawaban LLM

• SIMPLE_PRODUCT_SEARCH:
• Tidak ada respons teks percakapan yang dihasilkan.
• Tindakan: Respons API selalu menampilkan satu kueri refined_search. Kueri yang dipersempit ini berfungsi sebagai istilah penelusuran yang disarankan. Lakukan panggilan langsung ke Search API inti (SearchService.Search) dan ambil hasil produk yang relevan menggunakan salah satu kueri asli atau kueri refined_search. refined_search.query mungkin tidak langsung berasal dari input pengguna akhir saat ini, tetapi juga dapat berasal dari konteks histori chat, seperti jika pengguna akhir sebelumnya menyempurnakan gaun pesta menjadi gaun merah, kueri yang disempurnakan dapat menjadi gaun pesta merah.
• Untuk antarmuka percakapan (seperti chatbot): Sangat direkomendasikan untuk menggunakan refined_search.query yang disediakan oleh API. Dalam alur percakapan, kueri bahasa alami seperti "dapatkah Anda membantu saya menemukan pisang" dioptimalkan secara otomatis oleh API menjadi istilah penelusuran produk yang tepat ("pisang"), sehingga menghasilkan hasil produk yang lebih relevan.
• Untuk pengalaman penelusuran inti (seperti halaman hasil penelusuran): Anda memiliki fleksibilitas untuk menggunakan refined_search.query dari API atau kueri asli yang diberikan oleh pengguna akhir, karena kueri asli kemungkinan besar sudah merupakan istilah penelusuran produk yang tepat. Pilih opsi yang paling sesuai dengan strategi tampilan hasil penelusuran dan UI Anda.
• Opsi pengalaman pengguna: Percakapan tidak perlu diakhiri untuk kueri SIMPLE_PRODUCT_SEARCH. Pengguna Anda dapat melanjutkan percakapan dengan meneruskan conversation_id dalam permintaan berikutnya.
• Opsi A: Mengakhiri UI percakapan: Banyak retailer memilih untuk mengalihkan pengguna Anda ke halaman hasil penelusuran standar setelah SIMPLE_PRODUCT_SEARCH terdeteksi, sehingga menutup jendela chat. Dalam skenario ini, jika pengguna akhir kemudian memasukkan kueri baru ke dalam kotak penelusuran standar tanpa conversation_id sebelumnya, kueri tersebut akan dianggap sebagai percakapan baru yang terpisah, dan conversation_id baru akan dikeluarkan.
• Opsi B: Melanjutkan UI percakapan: Retailer dapat memilih untuk tetap membuka jendela chat. Tindakan ini memungkinkan pengguna Anda kembali ke mode percakapan. Keputusan untuk menerapkan Opsi A atau B sepenuhnya bergantung pada pengalaman pengguna pilihan retailer.

Untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis lengkap dalam Vertex AI Search untuk commerce, pemberian tag peristiwa yang tepat sangat penting:

1. Mendapatkan conversation_id: Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
2. Memberi Tag Peristiwa Pengguna: Jika respons percakapan menghasilkan kueri penelusuran, seperti jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan untuk SIMPLE_PRODUCT_SEARCH, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku dan jalur konversi pengguna Anda.

Kategori 4. Kueri LLM yang mencari jawaban

Untuk jenis kueri ini, API menghasilkan conversational_text_response (jawaban LLM) dan mungkin juga memberikan satu atau beberapa kueri refined_search. Percakapan tidak berakhir, dan pengguna akhir dapat melanjutkannya.

• PRODUCT_DETAILS:
• Tindakan: conversational_text_response akan memberikan detail produk yang diminta. Sistem Anda harus menampilkan informasi ini dengan jelas kepada pengguna.
• Respons juga akan menyertakan refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
• PRODUCT_COMPARISON:
• Tindakan: conversational_text_response akan memberikan perbandingan produk yang ditentukan. Sistem Anda harus menampilkan informasi ini dengan jelas kepada pengguna.
• Respons akan mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
• BEST_PRODUCT:
• Tindakan: conversational_text_response memberikan rekomendasi atau informasi tentang produk "terbaik" berdasarkan kueri. Sistem Anda akan menampilkan informasi ini.
• Respons mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.

Kategori 5. Penyempurnaan intent

• INTENT_REFINEMENT:
• Tindakan: Respons akan menyertakan conversational_text_response, followup_question, dan refined_search (satu atau beberapa kueri penelusuran yang disarankan). Urutan tampilan yang direkomendasikan adalah sebagai berikut:
1. conversational_text_response
2. refined_search saran: Saran ini diurutkan dan diberi peringkat, jadi penting untuk menampilkannya dalam urutan yang sama dengan respons.
3. Followup_question
• Respons akan mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
• Untuk interaksi berikutnya, kirim jawaban pengguna Anda bersama dengan conversation_id.

Menampilkan kueri yang disarankan untuk produk

Berikut cara mengonfigurasi Google Penelusuran untuk menampilkan pertanyaan dan saran produk di agen Conversational Commerce.

Saat Conversational API menampilkan kueri refinedSearch, kueri ini memberikan peluang yang sangat baik untuk memandu pengguna akhir menuju produk yang relevan. Hal ini sangat berharga untuk Kategori 4 (kueri pencarian jawaban LLM) dan Kategori 5 (INTENT_REFINEMENT).

Rekomendasi

• Tampilkan: Tampilkan N kueri teratas (1-3, menunggu pengujian tentang jumlah ideal untuk UI Anda) refinedSearch kepada pengguna Anda.
• Mekanisme: Kueri yang disarankan ini harus dijalankan melalui Search API inti (SearchService.Search) di latar belakang atau saat interaksi pengguna.
• Presentasi: Tampilkan hasil sebagai carousel interaktif atau kartu yang dapat diklik, sehingga pengguna dapat menjelajahi kategori produk terkait atau item tertentu. Fitur ini memberikan nilai langsung dan membantu menjembatani kesenjangan antara interaksi percakapan dan penemuan produk.

Permintaan Search API:

Kueri lanjutan

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}
  

Peristiwa yang akan dikirim ke Vertex AI Search untuk commerce

Penting untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis lengkap dalam Vertex AI Search untuk commerce menggunakan pemberian tag peristiwa yang tepat:

1. Mendapatkan conversation_id: Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
2. Memberi tag pada peristiwa pengguna: Jika respons percakapan mengarah ke kueri penelusuran, seperti dengan menampilkan saran refined_search yang kemudian diklik pengguna akhir, atau jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku pengguna dan jalur konversi.

Lanjutkan percakapan

Bagian ini menjelaskan cara sesi agen Conversational Commerce dipertahankan oleh Conversational API dan berlanjut di langkah terakhir ini.

Conversational API menggunakan conversation_id untuk mengelola percakapan yang sedang berlangsung. Untuk memastikan konsistensi antara jawaban LLM dan hasil penelusuran, permintaan Conversational API berikutnya harus menyertakan SearchParams yang mencerminkan konfigurasi panggilan Search API inti.

Lihat tabel

Penanganan sesi	Deskripsi	Integrasi API percakapan
Memulai percakapan baru	Untuk memulai percakapan baru, klien menghilangkan conversation_id dari permintaan API.	Contoh permintaan API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Contoh respons API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Lanjutkan percakapan	Conversational API menampilkan conversation_id sebagai bagian dari respons API. ID ini dapat dikirim dalam permintaan lanjutan untuk melanjutkan percakapan yang sama. Hal ini membantu memastikan bahwa agen Conversational Commerce merespons kueri pengguna Anda berdasarkan histori percakapan dalam sesi tersebut.	Contoh permintaan API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Contoh respons API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Memastikan konsistensi hasil penelusuran	Untuk memastikan jawaban LLM konsisten dengan hasil penelusuran yang ditampilkan, klien harus menggunakan SearchParams dalam permintaan Conversational API. Parameter penelusuran ini harus memiliki konfigurasi yang sama dengan Search API inti.	Contoh permintaan API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

Penanganan sesi

• Mulai percakapan baru:
  • Deskripsi: Untuk memulai percakapan baru, klien menghilangkan conversationId dari permintaan API.
  • Kapan harus memulai percakapan baru: Klien ingin memulai percakapan baru - sehingga mendapatkan conversationId baru dari respons API - dalam beberapa skenario pengalaman pengguna umum:
    • Tab atau sesi baru: Saat pelanggan membuka situs Anda di tab browser baru atau memulai sesi yang benar-benar baru.
    • Kueri asli baru: Dalam beberapa desain UX, jika pelanggan memasukkan kueri baru yang tidak terkait, Anda dapat memilih untuk memulai ulang alur percakapan untuk memastikan konteks yang paling relevan.
    • Tombol mulai ulang percakapan: Jika UI Anda menyediakan tombol "Mulai Percakapan Baru" atau "Reset Percakapan" yang jelas, mengklik tombol ini akan memicu sesi percakapan baru.
  • Integrasi API percakapan: Respons API akan menyertakan conversationId baru yang digunakan untuk permintaan berikutnya.
• Lanjutkan Percakapan:
  • Deskripsi: Conversational API menampilkan conversation_id sebagai bagian dari respons API. ID ini harus dikirim dalam permintaan lanjutan untuk melanjutkan percakapan yang sama. Hal ini membantu memastikan bahwa agen Conversational Commerce merespons kueri pengguna Anda berdasarkan histori percakapan dalam sesi tersebut, yang mencakup query pengguna akhir, conversational_text_response, dan followup_question.
  • Integrasi API Percakapan: Klien meneruskan conversation_id dari respons sebelumnya di ConversationalSearchRequest.
• Pastikan konsistensi hasil penelusuran:
  • Deskripsi: Untuk membantu memastikan jawaban LLM konsisten dengan hasil penelusuran yang ditampilkan kepada pengguna Anda, klien harus menggunakan searchParams dalam permintaan Conversational API. Parameter penelusuran ini harus memiliki konfigurasi yang sama, seperti filter, urutan pengurutan) dengan panggilan Search API yang dilakukan untuk mengambil hasil produk.
  • Integrasi API Percakapan: Objek searchParams dalam ConversationalSearchRequest harus diisi secara identik dengan SearchRequest yang digunakan untuk penelusuran produk inti.

Mengirim permintaan ke Vertex AI Search untuk commerce

Anda dapat mengambil conversation_id dari penyimpanan sesi. Permintaan harus menyertakan query pelanggan baru, yang mungkin berupa balasan atas pertanyaan dari respons sebelumnya. Permintaan juga harus menyertakan refined_search.query terbaru dari respons sebelumnya jika pengguna akhir bertindak berdasarkan kueri yang disempurnakan. Jika tidak, kueri tersebut harus menyertakan kueri yang sama sekali baru dan tidak terkait, serta conversationId. Jangan lupa untuk selalu menyertakan searchParams.

Catatan: Apakah conversationId dipertahankan atau direset untuk kueri pengguna akhir baru bergantung pada pilihan UX spesifik Anda dan pengalaman pengguna yang dipilih. conversationId bertindak sebagai memori sistem untuk sesi percakapan tertentu.

• Skenario 1: Kotak penelusuran tunggal dan percakapan persisten: Jika antarmuka penelusuran Anda hanya memiliki satu kotak penelusuran utama atau jendela percakapan persisten, Anda tidak akan mereset conversationId, meskipun pengguna akhir mengetik kueri baru yang tampaknya tidak terkait. Sistem akan menggunakan histori percakapan yang ada (terkait dengan conversationId) untuk memberikan respons yang relevan secara kontekstual.
• Skenario 2: Jendela percakapan dan jendela kueri terpisah: Jika antarmuka penelusuran Anda menampilkan jendela chat percakapan yang berbeda dan kotak kueri penelusuran standar yang terpisah (seperti kotak penelusuran di seluruh situs), memasukkan kueri baru ke kotak penelusuran standar dapat secara implisit menandakan niat untuk memulai penelusuran baru yang tidak terkait, sehingga berpotensi menyebabkan conversationId direset untuk tindakan penelusuran tertentu tersebut. Namun, di dalam jendela percakapan khusus, conversationId harus selalu dipertahankan untuk kesinambungan.

Pada akhirnya, keputusan tentang kapan harus menggunakan kembali versus mereset conversationId adalah pilihan desain untuk mengoptimalkan pengalaman percakapan bagi pelanggan Anda.

Metode dan endpoint HTTP (sama dengan kueri awal)

POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
    

Permintaan API percakapan:

Kueri lanjutan

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}
  

Respons API percakapan:

Respons lanjutan

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}
  

Contoh pengguna akhir yang terus menerima pertanyaan:

• Pertanyaan pengguna: Bantu saya merencanakan pesta
• Jawaban sistem: Pesta seperti apa yang Anda rencanakan?
• Balasan pengguna: Pesta ulang tahun

Yang harus dilakukan retailer dengan respons

Cara merender kolom mirip dengan respons awal, tetapi perhatikan perubahan yang mencerminkan percakapan yang berlanjut:

• refined_search: Kolom ini berisi kueri yang diperbarui yang menggabungkan input terbaru pengguna akhir. Anda harus memperbarui konsol klien untuk kueri saat ini dengan tepat (seperti menampilkan kueri yang ditampilkan kepada pengguna yang telah berubah dari "dekorasi" menjadi "dekorasi pesta ulang tahun" atau "perlengkapan pesta ulang tahun"). Kueri refined_search dapat digunakan untuk panggilan ke Search API inti (SearchService.Search) atau juga dapat ditampilkan kepada pengguna akhir sebagai saran.
• conversational_text_response: Menampilkan respons teks buatan AI baru yang relevan dengan giliran terakhir.
• followup_question: Jika percakapan perlu dilanjutkan untuk penyempurnaan lebih lanjut, followup_question baru akan diberikan.

Peristiwa yang akan dikirim ke Vertex AI Search untuk commerce

Pemberian tag peristiwa penting untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis di Vertex AI Search untuk commerce.

Ada dua langkah dalam proses pemberian tag pada peristiwa:

1. Mendapatkan conversation_id: Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
2. Memberi tag pada peristiwa pengguna: Jika respons percakapan mengarah ke kueri penelusuran, seperti dengan menampilkan saran refined_search, atau jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku pengguna akhir dan jalur konversi.

Pertimbangan dan praktik terbaik tambahan

Pertimbangan dan praktik terbaik tambahan harus dipertimbangkan saat menerapkan antarmuka agen Conversational Commerce Anda:

• Konsistensi ID pengunjung: Membantu memastikan bahwa visitor_id unik dikirim secara konsisten dengan setiap permintaan untuk pengguna akhir tertentu. Hal ini sangat penting untuk personalisasi dan pelatihan model yang akurat. ID ini idealnya tetap konsisten untuk pengguna akhir di seluruh sesi dan status login atau logout.
• Pengelolaan cabang: Meskipun default_branch umum, pastikan Anda menggunakan ID cabang yang benar jika katalog produk Anda disusun dengan beberapa cabang.
• Interaksi Search API: Untuk SIMPLE_PRODUCT_SEARCH dan kasus apa pun saat refined_search diberikan, jangan lupa untuk melakukan panggilan terpisah ke Search API inti (SearchService.Search) menggunakan query dari kolom refined_search atau kueri asli untuk mendapatkan listingan produk yang sebenarnya. Conversational API terutama berfokus pada pengalaman percakapan dan pemahaman maksud pengguna, bukan langsung menampilkan hasil produk.
• Desain antarmuka pengguna: Desain UI Anda untuk menampilkan opsi conversational_text_response, followup_question, dan refined_search dengan jelas secara intuitif untuk memandu pengguna Anda.

Langkah berikutnya

Untuk mengetahui referensi dukungan tambahan, lihat FAQ fitur percakapan.