Konfigurasi penelusuran penyimpanan data

Anda dapat memengaruhi hasil penelusuran yang diambil dari alat penyimpanan data Dialogflow CX dengan mengonfigurasi spesifikasi penguatan dan filter. Hal ini memungkinkan Anda memiliki interaksi yang lebih dipersonalisasi dan kontekstual saat agen menggunakan penyimpanan data untuk menemukan informasi.

Secara opsional, Anda dapat menyertakan ekspresi dinamis untuk menyesuaikan hasil berdasarkan konteks percakapan. Misalnya, agen Anda telah mengambil informasi yang menunjukkan bahwa pengguna akhir memiliki "ponsel". Anda dapat mengonfigurasi alat penyimpanan data untuk meningkatkan dokumen yang terkait dengan ponsel saat menjawab kueri umum nanti dalam percakapan seperti "Bagaimana cara memeriksa pesan suara saya?".

Anda dapat mengonfigurasi hasil penelusuran penyimpanan data menggunakan konsol, API, atau integrasi Dialogflow CX Messenger.

Input kondisi penelusuran

Anda mengonfigurasi hasil penelusuran menggunakan kolom spesifikasi penguatan (BoostSpec) dan spesifikasi filter (FilterSpec) dalam objek SearchConfig. Konfigurasi ini berlaku per penyimpanan data dalam alat, sehingga Anda dapat mengontrol perilaku setiap penyimpanan data yang terhubung.

Anda dapat mengonfigurasi kondisi penelusuran dengan salah satu dari dua cara: menggunakan konsol atau dengan mengirimkan panggilan API langsung.

Ada perbedaan penting antara keduanya:

• Panggilan API: Anda mengirim BoostSpec dan FilterSpec dalam SearchConfig menggunakan panggilan API DetectIntent. Anda harus memberikan objek SearchConfig lengkap dalam permintaan. SearchConfig yang dikirim melalui panggilan API langsung selalu menggantikan SearchConfig yang dikirim menggunakan konsol. Ekspresi dinamis dan referensi parameter tidak didukung.

• Konsol: Konsol menggunakan konfigurasi BoostSpec dan FilterSpec Anda untuk membuat objek SearchConfig yang dikirim bersama permintaan penelusuran. Jika perlu, Anda dapat menyertakan referensi parameter dan ekspresi dinamis untuk menyesuaikan hasil dengan data konteks yang direkam dari percakapan. Anda hanya perlu memberikan objek ConditionBoostSpec dan daftar string filter untuk membuat FilterSpecs, bukan objek SearchConfig lengkap.

Informasi pengguna akhir disediakan sebagai JSON di detectIntentRequest. Tidak ada skema yang diharapkan, sehingga Anda dapat menentukan properti objek.

Spesifikasi penguatan (Spesifikasi penguatan)

Spesifikasi penguatan memungkinkan Anda mengubah peringkat hasil penelusuran dengan menerapkan nilai penguatan ke dokumen tertentu. Anda dapat menambahkan beberapa spesifikasi penguatan ke satu penyimpanan data.

Anda memasukkan setiap Boost Spec sebagai string JSON yang mewakili satu objek ConditionBoostSpec.

Kolom utama:

• condition: (String) Ekspresi yang menentukan kapan penguatan harus diterapkan. Ini menggunakan sintaksis ekspresi filter standar. Anda dapat menggunakan ekspresi Dialogflow CX untuk membuat hasilnya dinamis, seperti $session.params.YOUR_PARAM_NAME atau $request.end-user-metadata.YOUR_KEY.
• boost: (Angka) Nilai antara -1,0 dan 1,0 yang menentukan kekuatan penguatan.
  • Nilai positif akan mempromosikan dokumen yang cocok. Nilai 1.0 memberikan promosi yang kuat.
  • Nilai negatif akan mendemosikan dokumen yang cocok. Nilai -1.0 memberikan penurunan peringkat yang kuat.
  • Nilai 0.0 tidak menerapkan penguatan dan tidak diizinkan.
• boostControlSpec: Memberikan lebih banyak kontrol untuk penentuan peringkat yang disesuaikan daripada kombinasi dasar kondisi dan penguatan. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi kolom ini, lihat dokumentasi referensi.

Contoh input konsol:

Jika Anda mengonfigurasi agen di konsol, berikan daftar ConditionBoostSpecs dalam format berikut:

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

Catatan: Dalam contoh ini, dokumen dengan URI yang cocok dengan nilai parameter sesi $session.params.doc_id akan diperkuat dengan kekuatan 0.5.

Contoh input API:

Jika Anda memanggil API secara langsung, Anda harus memberikan ConditionBoostSpecs dalam objek SearchConfig lengkap. Konfigurasi penelusuran berikut menjelaskan spesifikasi penguatan:

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

Catatan: DATASTORE_ID adalah nama lengkap penyimpanan data: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
CONDITION harus mengikuti sintaksis ekspresi filter Agent Search,
dan nilai penguatan harus antara -1.0 dan 1.0.

Spesifikasi Filter (Spesifikasi filter)

Spesifikasi filter membatasi hasil penelusuran hanya untuk menyertakan dokumen yang sesuai dengan kriteria yang ditentukan. Anda dapat menambahkan beberapa spesifikasi filter ke satu penyimpanan data.

Setiap Spesifikasi Filter harus dimasukkan sebagai ekspresi string. String harus sesuai dengan sintaksis ekspresi filter standar. Anda dapat menggunakan ekspresi Dialogflow CX dalam string ini untuk membuat hasilnya dinamis, seperti $session.params.YOUR_PARAM_NAME atau $request.end-user-metadata.YOUR_KEY.

Contoh string Spesifikasi Filter Konsol:

Jika mengonfigurasi agen menggunakan konsol, Anda harus memberikan daftar string filter untuk membentuk objek FilterSpec.

Dalam contoh ini, filter hanya menampilkan dokumen dengan numeric_field yang lebih besar dari atau sama dengan nilai $session.params.min_value dan dengan stock_availability adalah "IN_STOCK":

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

Contoh konfigurasi filter API:

Jika Anda memanggil API secara langsung, Anda harus menyediakan string filter dalam objek SearchConfig lengkap:

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

Catatan: DATASTORE_ID adalah nama lengkap penyimpanan data: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
dan CONDITION harus mengikuti sintaksis ekspresi filter Agent Search.

Ekspresi dinamis Dialogflow CX

Catatan: Ekspresi dinamis hanya tersedia untuk alat penyimpanan data. Fitur ini tidak tersedia untuk pengendali penyimpanan data.

Kondisi BoostSpec dan string FilterSpec dapat menggabungkan ekspresi Dialogflow CX untuk membuatnya dinamis. Hal ini memungkinkan Anda menyesuaikan perilaku penelusuran berdasarkan data konteks yang diambil dari percakapan yang sedang berlangsung. Ekspresi dinamis tidak didukung dalam panggilan API langsung dan hanya dapat digunakan jika Anda mengonfigurasi menggunakan konsol.

Anda dapat mengakses data konteks percakapan dengan dua cara:

• Parameter sesi: Nilai yang dikumpulkan selama percakapan menggunakan $session.params.YOUR_PARAMETER_ID.
• Metadata pengguna akhir: Metadata tentang pengguna akhir yang diteruskan di DetectIntentRequest menggunakan $request.end-user-metadata.YOUR_KEY. Agar opsi ini tersedia, pastikan end_user_metadata disertakan dalam QueryParameters panggilan DetectIntent Anda. Untuk mengetahui informasi selengkapnya, lihat endUserMetadata.

Untuk mengetahui informasi selengkapnya tentang fungsi sistem dan sintaksis ekspresi yang tersedia, lihat referensi kondisi dan fungsi sistem.

Kondisi penelusuran yang diterapkan saat runtime

Saat alat penyimpanan data Anda menjalankan penelusuran:

1. Evaluasi string JSON yang Anda berikan untuk spesifikasi penguatan. Setiap string JSON yang valid dikonversi menjadi objek ConditionBoostSpec. Kemudian, objek ini dikelompokkan ke dalam objek BoostSpecs untuk koneksi penyimpanan data tertentu, yang ditambahkan ke SearchConfig secara keseluruhan.
2. Evaluasi string yang Anda berikan untuk spesifikasi filter sebagai ekspresi Dialogflow CX. Setiap string filter yang dihasilkan digunakan untuk membuat objek FilterSpecs untuk penyimpanan data, yang juga ditambahkan ke SearchConfig.
3. Sertakan SearchConfig yang dibuat secara dinamis ini dalam QueryParameters permintaan penelusuran yang dikirim ke penyimpanan data.

Mengonfigurasi kondisi penelusuran

Untuk mengonfigurasi kondisi penelusuran, pastikan Anda telah menyelesaikan prasyarat berikut:

• Agen Dialogflow CX yang sudah ada.
• Alat penyimpanan data yang dikonfigurasi untuk agen Anda dengan satu atau beberapa penyimpanan data yang diaktifkan.

Konfigurasi konsol

1. Buka konsol Conversational Agents dan pilih projectGoogle Cloud .
2. Pilih agen dari menu drop-down.
3. Buka menu sebelah kiri dan klik Tools. Pilih alat penyimpanan data yang ingin Anda konfigurasi.
4. Di halaman pengeditan alat, buka bagian Penyimpanan data. Klik ikon Settings (⚙️) di samping penyimpanan data yang ingin Anda ubah.
5. Menu Configure Data Store akan muncul. Di sini, Anda dapat menambahkan Spesifikasi Penguatan dan Spesifikasi Filter untuk mengubah hasil penelusuran.
   • Untuk Spesifikasi Penguatan, berikan objek JSON yang menentukan ConditionBoostSpec. Lihat Spesifikasi Penguatan untuk mengetahui detailnya.
   • Untuk Filter Spec, berikan string yang menentukan kriteria filter. Lihat Spesifikasi Filter untuk mengetahui detailnya.
6. Setelah menambahkan dan mengonfigurasi spesifikasi, klik Konfirmasi di bagian bawah panel samping.
7. Klik Save di halaman edit alat penyimpanan data untuk menyimpan perubahan.

Konfigurasi API

Anda dapat memberikan data konfigurasi penelusuran ke Dialogflow CX saat mengirim permintaan deteksi intent. Anda harus memberikan informasi ini dalam setiap permintaan deteksi intent karena informasi tersebut tidak dipertahankan dalam sesi.

Berikan informasi ini di kolom queryParams.searchConfig dalam metode Sessions.detectIntent.

Buka referensi Session API

Pilih protokol dan versi untuk Referensi sesi:

Protokol	V3	V3beta1
REST	Resource sesi	Resource sesi
RPC	Antarmuka sesi	Antarmuka sesi
C++	SessionsClient	Tidak tersedia
C#	SessionsClient	Tidak tersedia
Go	SessionsClient	Tidak tersedia
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Tidak tersedia	Tidak tersedia
Python	SessionsClient	SessionsClient
Ruby	Tidak tersedia	Tidak tersedia

Tutup

Konfigurasi Dialogflow CX Messenger

Anda dapat memberikan data konfigurasi penelusuran ke integrasi Dialogflow CX Messenger. Untuk mengetahui informasi selengkapnya, lihat metode setContext.

Untuk menerapkan spesifikasi penelusuran atau konfigurasi penelusuran, Anda harus menambahkan cuplikan berikut ke kode Dialogflow CX Messenger saat menyematkannya ke situs:

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

Untuk mengetahui informasi selengkapnya, lihat metode setQueryParameters.

Pemecahan masalah

Solusi berikut mengatasi beberapa masalah umum yang terjadi selama konfigurasi. Uji konfigurasi Anda secara menyeluruh dengan menyimulasikan percakapan yang memicu berbagai parameter sesi dan nilai metadata pengguna akhir.

Ekspresi tidak valid

Jika kondisi Boost Spec atau string Filter Spec berisi ekspresi Dialogflow CX yang tidak valid (misalnya, sintaksis yang salah atau referensi ke parameter yang tidak ada), kompilasi ekspresi akan gagal. Error yang terkait dengan kompilasi ekspresi biasanya ditampilkan di DetectIntentResponse dalam kolom diagnostic_info sebagai SystemFunctionResults.

JSON ConditionBoostSpec tidak valid

Konsol Conversational Agents melakukan beberapa validasi pada string JSON ConditionBoostSpec saat menyimpannya untuk memeriksa apakah string tersebut adalah JSON yang valid dan strukturnya dapat dipetakan ke objek ConditionBoostSpec. Jika JSON valid, tetapi menghasilkan SearchConfig yang tidak valid menurut layanan penelusuran yang mendasarinya (misalnya, string kondisi yang tidak valid setelah substitusi parameter), layanan penelusuran akan menampilkan error.

Error penggantian runtime

Jika string JSON ConditionBoostSpec valid dan dapat diuraikan, tetapi terjadi error selama penggantian runtime ekspresi Dialogflow CX dalam kolomnya (seperti string kondisi), error ini akan dilaporkan di diagnostic_info sebagai SystemFunctionResults.

Meninjau SearchConfig yang dikompilasi

SearchConfig yang diterapkan saat kueri dijalankan tersedia di search_signals dalam respons. Meninjau SearchConfig dapat memberikan insight tentang masalah tambahan yang tidak diuraikan di sini.

Langkah berikutnya

• Untuk mengetahui informasi selengkapnya tentang struktur SearchConfig dan komponennya, lihat dokumentasi search_config.
• Untuk mengetahui informasi selengkapnya tentang sintaksis ekspresi, lihat Referensi kondisi dan fungsi sistem Dialogflow CX.
• Untuk mengetahui informasi selengkapnya tentang sintaksis ekspresi filter untuk penelusuran, lihat Memfilter dan mengurutkan hasil.