Pertanyaan umum (FAQ) tentang Conversational Analytics API

Halaman ini menjawab pertanyaan umum (FAQ) tentang Conversational Analytics API.

Dapatkah Conversational Analytics API mengubah atau menghapus data saya?

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

Berikut cara penanganan keamanan data untuk berbagai sumber data:

  • BigQuery: API memblokir pernyataan Bahasa Definisi Data (DDL) dan Bahasa Pengolahan Data (DML). Secara khusus, sistem menjalankan uji coba pada SQL yang dibuat dan hanya mengizinkan kueri jenis SELECT.
  • Looker: API 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 mencakup operasi penghapusan atau pelepasan.
  • Data Studio (untuk CSV dan Google Spreadsheet): Data Studio menggunakan format terstruktur untuk menentukan dan mengambil data untuk visualisasi dan laporan. Semua kueri 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 dengan percaya diri: Membahas keamanan dalam Analisis Percakapan Looker.

Bagaimana cara menangani error autentikasi dan izin?

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

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

    • Kemungkinan Penyebab: Pesan ini sering menunjukkan masalah pada Google Cloud peran IAM. Pengguna atau akun layanan yang mencoba menggunakan API tidak memiliki izin yang diperlukan di project Google Cloud .
    • Pemecahan masalah:
      • Google Cloud Pemilik project harus memastikan bahwa pengguna atau akun layanan memiliki peran IAM yang benar yang ditetapkan dalam Google Cloud project. Google Cloud 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 Pengguna mencoba memulai percakapan 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 dapat menampilkan pesan error umum, seperti 503 Connection reset by peer atau 500 Internal error.

Error umum ini terjadi karena streaming API mengirimkan header HTTP 200 OK segera setelah streaming dibuka. Jika agen data mengalami error fatal selama streaming (seperti waktu tunggu habis untuk kueri yang berjalan lama atau penolakan izin yang tiba-tiba), agen data akan menghentikan streaming dan menyertakan kode error tertentu dalam cuplikan 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 gunakan library klien (SDK) Google Cloud resmi, seperti Python SDK. SDK berbasis gRPC ini mem-parsing trailer HTTP/2 dan menampilkan kode error tertentu, seperti DEADLINE_EXCEEDED atau PERMISSION_DENIED), 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 Google Cloud untuk berinteraksi dengan geminidataanalytics.googleapis.com API. Peran IAM yang salah dikonfigurasi sering kali menyebabkan error PERMISSION_DENIED.
    • Peran khusus yang diperlukan dapat bergantung pada tindakan, tetapi peran umum seperti Editor Project mungkin diperlukan untuk operasi tertentu.

  2. Izin dan peran Looker:

    • Izin tingkat model: Untuk menggunakan Analisis Percakapan 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 Google Cloud project 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 Data QnA API versi eksperimental 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 telah Anda masukkan untuk data_agent.name akan diabaikan. Saat melakukan operasi get, update, atau delete, data_agent.name lengkap 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 telah Anda masukkan untuk data_agent.name akan digantikan dengan projects/<project>/locations/<location>/dataAgents/TestID.
  • Jika Anda menentukan data_agent_id dengan FQN, Anda akan menerima error "nama salah bentuk".

Apa format ID yang diterima di Create Agent atau Create Conversation?

Untuk agen data:

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

{data_agent} adalah ID resource. Panjangnya harus 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 lewati setelan kolom ini selama pembuatan agen karena akan disimpulkan secara otomatis dan diganti dengan {parent}/dataAgents/{data_agent_id}.

Untuk percakapan:

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

{conversation_id} adalah ID resource dan tidak boleh lebih dari 63 karakter serta 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 Anda melewati penetapan kolom ini selama pembuatan percakapan karena Analisis Percakapan akan otomatis mengidentifikasi, lalu menggantinya dengan {parent}/conversations/{conversation_id}.

Bagaimana cara menggunakan Masker Pembaruan?

Dalam Update Data Agent flow, parameter updateMask menggunakan string format FieldMask yang menentukan kolom dataAgent mana yang akan diganti dalam resource dataAgent oleh update. Parameter updateMask adalah kolom 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 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 percakapan di beberapa sesi. Solusi 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 yang eksplisit.

Apakah agen data API Analisis Percakapan akan memberikan jawaban yang sama setiap kali saya mengajukan pertanyaan yang sama?

  • Respons bahasa alami dari agen data Conversational Analytics API tidak deterministik, sehingga jawaban bahasa alami yang diberikan oleh agen dapat bervariasi meskipun untuk pertanyaan yang kata-katanya sama.
  • Respons kueri data: Namun, untuk pertanyaan tertentu yang mencari data, kueri yang dihasilkan di bawahnya (kueri SQL atau Looker) diharapkan bersifat deterministik. Data yang diambil harus sama, dengan asumsi bahwa data pokok 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.
  • Untuk sumber data BigQuery, Anda dapat memberikan konteks yang dibuat melalui kolom konteks terstruktur — seperti deskripsi tingkat tabel dan tingkat kolom, sinonim, tag, dan contoh kueri — dan melalui petunjuk sistem. Memberikan konteks ini juga membantu meningkatkan akurasi respons dan memungkinkan agen mengutip sumber dalam responsnya. Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data BigQuery.
  • 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 unggulan 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 akurasi dan pemahaman data agen.

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

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

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

Jika Anda telah mengaktifkan analisis lanjutan dengan Python, agen data Anda mungkin menampilkan kode Python. Kode Python yang ditampilkan oleh agen data dirancang untuk dieksekusi dalam sandbox yang aman dan dikelola Google. Mengeksekusi kode ini di lingkungan lokal atau lingkungan tidak terverifikasi lainnya akan melewati perlindungan keamanan sandbox dan dapat mengekspos sistem Anda terhadap risiko keamanan, seperti eksekusi kode berbahaya.

Untuk memeriksa dan menangani kode Python yang dihasilkan 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 belum diverifikasi 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?

Dengan mengintegrasikan Conversational Analytics API dengan aplikasi pihak ketiga, pengguna dapat berinteraksi dengan data mereka secara langsung dalam alat yang mereka gunakan setiap hari.

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

Untuk membuat integrasi, lihat repositori Panduan Memulai Analisis Percakapan untuk mengetahui contoh atau library. Anda juga dapat membuka Forum Developer Google untuk menelusuri contoh dari pengguna lain.

Berapa biaya Conversational Analytics API?

Conversational Analytics API tersedia di Ketersediaan Umum (GA). Untuk mengetahui informasi selengkapnya tentang harga, lihat panduan harga.

Selain itu, kueri yang dijalankan agen data terhadap sumber data seperti BigQuery dapat menimbulkan biaya dari layanan tersebut. Untuk BigQuery, Anda dapat mengelola biaya dengan menetapkan kuota atau membatasi byte yang ditagih per kueri menggunakan parameter bigquery_max_billed_bytes.

Sumber data apa yang didukung Conversational Analytics API?

Conversational Analytics API mendukung sumber data berikut:

  • BigQuery (termasuk tabel atau grafik)
  • 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 umum Conversational Analytics API?

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

Kuota apa yang perlu saya ketahui untuk Google Cloud proyek?

Tidak ada batasan pada Google Cloud pemilihan project atau lokasi. 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 residensi data?

Ya, Conversational Analytics API mendukung residensi data. Untuk mengontrol tempat pemrosesan dan penyimpanan data Anda, tentukan endpoint layanan regional atau multiregional saat membuat permintaan API. Untuk mengetahui informasi mendetail tentang dukungan lokasi tertentu dan detail konfigurasi, lihat Residensi data.

Apakah Conversational Analytics API mendukung bahasa selain bahasa Inggris?

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