Pertanyaan umum (FAQ) tentang Conversational Analytics API

Dapatkah Conversational Analytics API mengubah atau menghapus data saya?

Conversational Analytics API dirancang dengan perlindungan untuk mencegah perubahan atau penghapusan data Anda.

Berikut cara keamanan data ditangani untuk berbagai sumber data:

  • BigQuery: API ini memblokir pernyataan Bahasa Definisi Data (DDL) dan Bahasa Manipulasi Data (DML). Secara khusus, sistem menjalankan uji coba pada SQL yang dihasilkan dan hanya mengizinkan kueri jenis SELECT.
  • Looker: API ini berinteraksi dengan Looker menggunakan metode seperti run_inline_query, yang dibatasi untuk operasi baca seperti pilihan, filter, dan batas. Metode ini tidak mendukung operasi DDL atau DML dan tidak menyertakan operasi penghapusan atau penghilangan.
  • Data Studio (untuk CSV dan Google Spreadsheet): Data Studio menggunakan format terstruktur untuk menentukan dan mengambil data untuk visualisasi dan laporan. Kueri apa pun yang dijalankan dengan metode ini bersifat hanya baca dan tidak mendukung mutasi data.
  • Database: Sistem hanya mengizinkan kueri jenis SELECT. Untuk mencegah perubahan atau penghapusan data, pastikan akun layanan atau pengguna yang berinteraksi dengan Conversational Analytics API memiliki izin hanya baca ke database Anda.

Conversational Analytics API dirancang agar hanya dapat dibaca di seluruh sumber data ini. Untuk mengetahui informasi selengkapnya tentang keamanan Conversational Analytics API, lihat postingan blog Chat with confidence: Membahas keamanan dalam Analisis Percakapan Looker.

Bagaimana cara menangani error autentikasi dan izin?

Berikut beberapa error autentikasi dan izin umum yang mungkin Anda temui saat menggunakan Conversational Analytics API:

  1. Error: PERMISSION_DENIED atau 403 Write access to project ... was denied

    • Kemungkinan Penyebab: Pesan ini sering menunjukkan masalah dengan Google Cloud peran IAM. Pengguna atau akun layanan yang mencoba menggunakan API tidak memiliki izin yang diperlukan di Google Cloud project.
    • Pemecahan masalah:
      • Pemilik Google Cloud project harus memastikan bahwa pengguna atau akun layanan memiliki peran IAM yang benar yang ditetapkan di Google Cloud project. Peran seperti Project Editor mungkin diperlukan untuk operasi tertentu, seperti mengaktifkan API atau menguji fungsinya.
      • Jika Anda mengalami error 403 seperti Write access to project 'us-gcp-project-name' was denied saat beralih region, verifikasi konfigurasi IAM project Anda.

  2. Error: 500 Internal Server Error saat pengguna Looker dengan peran User mencoba melakukan chat dengan agen data.

Mengapa saya melihat error 503 atau 500 saat melakukan streaming respons?

Jika Anda menggunakan klien HTTP atau REST dasar (seperti library requests Python) untuk memanggil endpoint streaming :chat, API mungkin menampilkan pesan error umum, seperti 503 Connection reset by peer atau 500 Internal error.

Error umum ini terjadi karena streaming API mengirim header HTTP 200 OK segera setelah streaming dibuka. Jika agen data mengalami error fatal selama streaming (seperti waktu tunggu untuk kueri yang berjalan lama atau penolakan izin yang tiba-tiba), streaming akan dihentikan dan kode error tertentu akan disertakan dalam trailer HTTP/2. Klien HTTP atau REST standar tidak dapat mengurai header akhir ini dan malah menafsirkan penghentian mendadak sebagai error soket.

Untuk menangani error yang terjadi selama streaming, sebaiknya gunakanlibrary klien (SDK) resmi, seperti Python SDK. Google Cloud SDK berbasis gRPC ini mengurai trailer HTTP/2 dan menampilkan kode error tertentu, seperti DEADLINE_EXCEEDED atau PERMISSION_DENIED) dan bukan error jaringan umum.

Apa saja persyaratan Looker untuk menggunakan Conversational Analytics API?

Untuk menggunakan Conversational Analytics API, Anda memerlukan izin yang sesuai di Google Cloud IAM dan dalam Looker, bergantung pada sumber data dan tindakan yang ingin Anda lakukan:

  1. Google Cloud Peran IAM:

    • Anda memerlukan peran IAM yang memadai di project untuk berinteraksi dengan geminidataanalytics.googleapis.com API. Google Cloud Peran IAM yang salah konfigurasi sering kali menyebabkan error PERMISSION_DENIED.
    • Peran tertentu yang diperlukan dapat bergantung pada tindakan, tetapi peran umum seperti Project Editor mungkin diperlukan untuk operasi tertentu.

  2. Izin dan peran Looker:

    • Izin tingkat model: Untuk menggunakan Conversational Analytics dan Conversational Analytics API, pengguna Looker harus diberi peran Looker yang berisi izin gemini_in_looker untuk model yang berinteraksi dengannya.

Untuk mempelajari lebih lanjut izin dan peran yang diperlukan untuk menggunakan Conversational Analytics API, lihat halaman dokumentasi Memberikan peran dan izin IAM Conversational Analytics API untuk mengetahui informasi selengkapnya.

Selain itu, instance Looker Anda harus memenuhi persyaratan tertentu:

Untuk menggunakan Conversational Analytics API dengan Data Studio Pro, langganan Pro Anda harus berada di luar perimeter VPC-SC.

Apa saja persyaratan database untuk menggunakan Conversational Analytics API?

Untuk menggunakan Conversational Analytics API dengan database seperti AlloyDB untuk PostgreSQL, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL, Anda harus memastikan autentikasi dan pengaktifan IAM yang tepat:

  1. Google Cloud Peran IAM:

    • Akun layanan atau pengguna harus memiliki peran IAM yang diperlukan untuk terhubung ke dan membuat kueri database tertentu. Hal ini biasanya melibatkan peran dengan akses baca ke database.

  2. Pengaktifan API:

    • Pastikan Cloud AI Companion API diaktifkan di project Google Cloud Anda.

Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan autentikasi IAM, lihat dokumentasi untuk setiap database:

Bagaimana cara bermigrasi dari Data QnA API ke Conversational Analytics API?

Jika Anda menggunakan versi eksperimental Data QnA API yang lebih lama (dataqna.googleapis.com), lihat panduan migrasi untuk mengetahui cara bermigrasi ke endpoint resmi baru untuk Conversational Analytics API (geminidataanalytics.googleapis.com).

Apa perbedaan antara nama agen data dan ID-nya?

ID agen data, yang ditentukan sebagai nilai untuk data_agent_id, adalah ID unik untuk agen data. Nama agen data, data_agent.name, diturunkan secara otomatis dari data_agent_id sebagai nama yang sepenuhnya memenuhi syarat (FQN), yang berbentuk projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Saat membuat agen data, nilai apa pun yang mungkin Anda masukkan untuk data_agent.name akan diabaikan. Saat melakukan operasi get, update, atau delete, data_agent.name lengkap akan diperlakukan sebagai ID unik agen data.

Saat menggunakan Conversational Analytics API untuk membuat agen data, skenario berikut berlaku:

  • Jika Anda tidak menentukan data_agent_id, ID unik akan dibuat secara otomatis.
  • Jika Anda menentukan data_agent_id sebagai, misalnya, TestID, nilai apa pun yang mungkin Anda masukkan untuk data_agent.name akan ditimpa dengan projects/<project>/locations/<location>/dataAgents/TestID.
  • Jika Anda menentukan data_agent_id dengan FQN, Anda akan menerima error "nama tidak valid".

Apa format yang diterima untuk ID di Buat Agen atau Buat Percakapan?

Untuk agen data:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} adalah ID resource. ID ini harus terdiri dari 63 karakter atau kurang dan harus cocok dengan format yang dijelaskan di https://google.aip.dev/122#resource-id-segments.

Contoh: projects/1234567890/locations/us-central1/dataAgents/my-agent

Sebaiknya jangan tetapkan kolom ini selama pembuatan agen karena kolom ini akan disimpulkan secara otomatis dan ditimpa dengan {parent}/dataAgents/{data_agent_id}.

Untuk percakapan:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} adalah ID resource dan harus terdiri dari 63 karakter atau kurang dan harus cocok dengan format yang dijelaskan di https://google.aip.dev/122#resource-id-segments.

Contoh: projects/1234567890/locations/us-central1/conversations/my-conversation.

Sebaiknya jangan tetapkan kolom ini selama pembuatan percakapan karena Conversational Analytics akan otomatis mengidentifikasi, lalu menimpanya dengan {parent}/conversations/{conversation_id}.

Bagaimana cara menggunakan Mask Update?

Dalam alur Update Agen Data, parameter updateMask menggunakan string format FieldMask yang menentukan kolom dataAgent mana yang akan ditimpa di resource dataAgent oleh update. Parameter updateMask adalah kolom yang wajib diisi dan divalidasi sebagai berikut:

  • Jika updateMask kosong, BadRequestException akan ditampilkan dan tidak ada kolom yang akan diperbarui.
  • Jika semua kolom di updateMask adalah kolom dataAgent yang valid, hanya kolom tersebut yang akan diperbarui.
  • Jika campuran kolom yang valid dan tidak valid diberikan, kolom yang tidak valid akan diabaikan, dan hanya kolom yang valid yang akan diperbarui.

Bagaimana cara menggunakan getIAMPolicy dan setIAMPolicy untuk menetapkan kebijakan IAM untuk agen data?

Anda dapat menggunakan metode getIamPolicy dan metode setIamPolicy untuk menetapkan peran IAM kepada pengguna untuk agen tertentu.

Contoh kode berikut menunjukkan cara mengambil kebijakan IAM untuk agen data:

Contoh kode berikut menunjukkan cara menetapkan IAM ke agen data:

Apa saja kemampuan memori agen data Conversational Analytics API?

  • Dalam satu sesi: Conversational Analytics API mendukung percakapan multi-giliran, yang berarti API ini dapat mereferensikan bagian sebelumnya dari percakapan saat ini.
  • Di beberapa sesi: Conversational Analytics API menyertakan fitur untuk histori percakapan terkelola, yang memungkinkan pengguna melakukan chat di beberapa sesi. API ini juga mendukung agen stateful dengan percakapan multi-giliran yang dikelola Google.
  • Memori jangka panjang: Agen data Conversational Analytics API tidak mendukung kemampuan memori jangka panjang eksplisit.

Apakah agen data Conversational Analytics API akan memberikan jawaban yang sama setiap kali saya mengajukan pertanyaan yang sama?

  • Respons bahasa alami dari agen data Conversational Analytics API tidak bersifat deterministik, sehingga jawaban bahasa alami yang diberikan oleh agen dapat bervariasi meskipun pertanyaannya sama.
  • Respons kueri data: Namun, untuk pertanyaan spesifik yang mencari data, kueri yang mendasarinya (kueri SQL atau Looker) diharapkan bersifat deterministik. Data yang diambil harus sama, dengan asumsi data yang mendasarinya tidak berubah.

Bagaimana cara meningkatkan akurasi respons dari agen data Conversational Analytics API?

Salah satu cara untuk meningkatkan akurasi respons agen data adalah dengan memberikan informasi kontekstual yang kuat kepada agen data. Anda dapat menambahkan konteks dengan cara berikut:

  • Di lapisan semantik Looker, Anda dapat memberikan konteks dalam definisi LookML. Untuk mengetahui informasi dan contoh selengkapnya, lihat halaman dokumentasi Memandu perilaku agen dengan konteks yang dibuat di Looker.
  • Di sumber data AlloyDB untuk PostgreSQL, Cloud SQL untuk MySQL, Cloud SQL untuk PostgreSQL, dan Spanner, Anda dapat memberikan konteks dengan menambahkan deskripsi tabel, kolom, skema, dan batasan sebagai panduan untuk data dan cara menafsirkan data tersebut.

  • Saat membuat agen data, Anda dapat memberikan petunjuk sistem, kueri terverifikasi, dan konteks lanjutan:

    • Petunjuk sistem, yang merupakan panduan yang ditentukan pengguna yang dapat membentuk perilaku agen data. Panduan ini mencakup logika khusus bisnis, pemformatan respons, atau presentasi data.
    • Anda dapat memberikan kueri terverifikasi (juga disebut sebagai kueri emas bergantung pada sumber data), yang merupakan contoh pertanyaan bahasa alami yang dipasangkan dengan kueri SQL atau Looker yang benar.
    • Untuk sumber data AlloyDB, Cloud SQL untuk MySQL, Cloud SQL untuk PostgreSQL, dan Spanner, Anda dapat memberikan konteks lanjutan, yang membantu Anda mengoptimalkan pemahaman dan akurasi data agen.

    Untuk mengetahui informasi selengkapnya, lihat Memandu perilaku agen dengan konteks yang dibuat.

Lihat halaman Mengajukan pertanyaan yang efektif untuk mendapatkan panduan tentang cara mengajukan pertanyaan untuk mendapatkan respons yang lebih efektif dan akurat.

Bagaimana cara memeriksa dan menangani kode Python yang dibuat agen dengan aman?

Jika Anda telah mengaktifkan analisis lanjutan dengan Python, agen data Anda mungkin menampilkan kode Python. Kode Python yang ditampilkan agen data dirancang untuk dijalankan dalam sandbox terkelola Google yang aman. Menjalankan kode ini di lingkungan lokal atau lingkungan lain yang tidak terverifikasi akan melewati perlindungan keamanan sandbox dan dapat mengekspos sistem Anda ke risiko keamanan, seperti eksekusi kode berbahaya.

Untuk memeriksa dan menangani kode Python yang dibuat agen dengan aman, ikuti panduan berikut:

  • Periksa kode yang dihasilkan secara manual sebelum menjalankannya. Cari pola yang mencurigakan seperti permintaan jaringan yang tidak terduga (misalnya, socket, requests, atau urllib), perintah tingkat sistem (misalnya, os.system atau subprocess), atau literal dan variabel string yang sangat di-obfuscate.
  • Jangan pernah menjalankan kode yang tidak terverifikasi secara langsung di komputer lokal atau dalam lingkungan produksi. Gunakan sandbox yang aman dan terisolasi — seperti notebook Colaboratory, container Docker sementara, atau mesin virtual — yang tidak memiliki akses ke kredensial sensitif, jaringan internal, atau sistem file lokal.
  • Jika memungkinkan, sebelum menjalankan kode, Anda harus menjalankan alat analisis statis atau linter pada kode untuk menandai operasi yang berpotensi tidak aman atau pola berbahaya yang diketahui.

Dapatkah saya mengintegrasikan Conversational Analytics API dengan aplikasi pihak ketiga?

Mengintegrasikan Conversational Analytics API dengan aplikasi pihak ketiga memungkinkan pengguna berinteraksi dengan data mereka secara langsung dalam alat yang mereka gunakan setiap hari.

Aplikasi pihak ketiga yang berinteraksi dengan endpoint geminidataanalytics.googleapis.com API harus dapat mengirim pesan pengguna dari aplikasi ke agen dan menampilkan respons.

Untuk membuat integrasi, lihat repositori Conversational Analytics Quickstarts untuk contoh atau library. Anda juga dapat mengunjungi Forum Developer Google untuk menelusuri contoh dari pengguna lain.

Berapa biaya Conversational Analytics API?

Conversational Analytics API berada dalam fase Pratinjau, dan Google tidak mengenakan biaya untuk produk dalam Pratinjau. Kami akan memberikan pemberitahuan lanjutan tentang perubahan harga di masa mendatang.

Sumber data apa yang didukung oleh Conversational Analytics API?

Conversational Analytics API mendukung sumber data berikut:

  • BigQuery
  • Eksplorasi Looker
  • Data Studio
  • AlloyDB untuk PostgreSQL
  • GoogleSQL untuk Spanner
  • Cloud SQL dan Cloud SQL untuk PostgreSQL

Anda juga dapat terhubung ke sumber seperti SAP dan Salesforce melalui BigQuery, serta ke CSV dan Google Spreadsheet melalui Data Studio.

Apa saja batasan Conversational Analytics API yang diketahui?

Untuk mempelajari lebih lanjut batasan Conversational Analytics API yang diketahui, lihat halaman dokumentasi Batasan Conversational Analytics API yang diketahui.

Kuota apa yang perlu saya ketahui untuk Google Cloud project?

Tidak ada batasan pada Google Cloud pemilihan atau lokasi project. Anda dapat membuat agen data untuk membuat kueri sumber data yang didukung yang termasuk dalam project atau region mana pun.

Apakah Conversational Analytics API mendukung regionalisasi data?

Karena Conversational Analytics API belum mendukung residensi data (DRZ), Anda belum dapat menghosting agen di region geografis tertentu. Regionalisasi data tidak didukung.

Apakah Conversational Analytics API mendukung bahasa selain bahasa Inggris?

Satu-satunya bahasa yang didukung secara resmi untuk Conversational Analytics API adalah bahasa Inggris. Meskipun model Gemini yang mendasarinya mendukung banyak bahasa, dan beberapa pengguna telah melaporkan keberhasilan anekdot dengan kueri non-bahasa Inggris, Conversational Analytics API tidak secara resmi mendukung bahasa selain bahasa Inggris.