Conversational Analytics API memungkinkan Anda mengaktifkan atau menonaktifkan logging percakapan untuk agen data dan memilih tabel BigQuery yang menyimpan log-nya. Untuk meninjau pertanyaan pengguna dan jawaban agen, buat kueri tabel tersebut.
Sebelum memulai
Sebelum mengonfigurasi logging percakapan untuk agen data, selesaikan tugas-tugas berikut:
- Dalam project Google Cloud , aktifkan API yang diperlukan untuk Conversational Analytics API dan BigQuery.
- Pastikan Anda memiliki peran Identity and Access Management (IAM) yang diperlukan.
- Pastikan Anda memiliki agen data yang sumber datanya merujuk ke tabel BigQuery. Untuk konfigurasi agen yang tidak dicatat ke dalam log, lihat Batasan.
- Rencanakan set data BigQuery dalam project agen data yang hanya menyimpan log. Semua agen data dalam project menggunakan satu agen layanan yang sama, dan set data khusus membatasi akses tulisnya ke log Anda.
- Tentukan siapa yang dapat membaca log. Log ini berisi pertanyaan lengkap pengguna dan jawaban agen. Jika pengguna melakukan chat dengan agen melalui aplikasi Anda sendiri, Anda bertanggung jawab atas pemberitahuan, pengungkapan, atau izin yang berlaku untuk percakapan yang dicatat ke dalam log. Untuk mengetahui informasi selengkapnya, lihat Privasi, tata kelola data, dan keamanan.
Peran yang diperlukan
Untuk mendapatkan izin yang Anda perlukan guna mengonfigurasi logging percakapan untuk agen data dan membuat kueri log, minta administrator untuk memberi Anda peran IAM berikut:
-
Buat set data log:
BigQuery User (
roles/bigquery.user) di project Anda -
Beri agen layanan akses ke set data log:
BigQuery Data Owner (
roles/bigquery.dataOwner) di set data log -
Mengubah setelan logging percakapan agen data:
Gemini Data Analytics Data Agent Editor (
roles/geminidataanalytics.dataAgentEditor) di agen data atau project Anda -
Buat kueri log:
- BigQuery Data Viewer (
roles/bigquery.dataViewer) di set data log - BigQuery Job User (
roles/bigquery.jobUser) di project Anda
- BigQuery Data Viewer (
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Jika Anda membuat set data log, Anda akan otomatis diberi peran BigQuery Data Owner di set data tersebut. Jika Anda membuat agen data, Anda akan otomatis diberi
peran Pemilik Agen Data Gemini Data Analytics
(roles/geminidataanalytics.dataAgentOwner) di agen data tersebut, yang mencakup izin untuk
mengubah setelan logging percakapannya.
Pengguna yang melakukan chat dengan agen data tidak memerlukan peran tambahan untuk logging percakapan. Jika percakapan tidak dicatat ke dalam log untuk beberapa pengguna, lihat Memecahkan masalah logging percakapan.
Peran agen layanan
Agen layanan Analisis Percakapan API
(service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.)
menulis log. Ganti PROJECT_NUMBER dengan nomor
project yang berisi agen data.
Untuk memastikan bahwa agen layanan Analisis Percakapan API memiliki izin yang diperlukan untuk membuat tabel log dan menulis log percakapan ke dalamnya, minta administrator Anda untuk memberikan peran IAM BigQuery Data Editor (roles/bigquery.dataEditor) kepada agen layanan Analisis Percakapan API di set data log.
Administrator Anda mungkin juga dapat memberikan izin yang diperlukan kepada agen layanan Analisis Percakapan API melalui peran khusus atau peran bawaan lainnya.
Aktifkan logging percakapan
Logging percakapan memerlukan set data yang dapat ditulis oleh agen layanan. Buat set data dan berikan akses terlebih dahulu, lalu aktifkan logging untuk agen data.
Membuat set data log
Buat set data di project agen data untuk menyimpan log. Agen layanan
membuat tabel log dalam set data ini pada giliran pertama yang dicatat ke dalam log. Untuk membuat set data, gunakan perintah bq mk --dataset di alat command line bq. Anda dapat menjalankan perintah alat bq di
Cloud Shell atau di terminal lokal tempat Google Cloud CLI
diinstal.
bq --location=LOCATION mk --dataset PROJECT_ID:LOG_DATASET
Ganti nilai contoh sebagai berikut:
- LOCATION: Lokasi BigQuery untuk set data log, seperti
US. - PROJECT_ID: ID project yang berisi agen data.
- LOG_DATASET: ID set data yang akan dibuat.
Untuk mengetahui cara lain membuat set data, lihat Membuat set data.
Memberi agen layanan akses ke set data
Berikan peran BigQuery Data Editor (roles/bigquery.dataEditor) kepada agen layanan hanya pada set data log.
Pilih salah satu opsi berikut:
Konsol
Di konsol Google Cloud , buka halaman BigQuery.
Di panel Explorer, luaskan project Anda, klik Datasets, lalu pilih set data log.
Klik Share > Manage permissions.
Klik Add principal.
Di kolom New principals, masukkan alamat email agen layanan:
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics..Ganti
PROJECT_NUMBERdengan nomor project yang berisi agen data.Di daftar Select a role, pilih BigQuery Data Editor.
Klik Simpan.
SQL
Di editor kueri BigQuery, tetapkan lokasi kueri ke lokasi set data log, lalu jalankan pernyataan GRANT berikut:
GRANT `roles/bigquery.dataEditor`
ON SCHEMA `PROJECT_ID`.LOG_DATASET
TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.";
Ganti nilai contoh sebagai berikut:
- PROJECT_ID: ID project yang berisi agen data dan set data log.
- LOG_DATASET: ID set data log.
- PROJECT_NUMBER: Nomor project yang berisi agen data.
Untuk mengetahui cara lain dalam memberikan akses, lihat Memberikan akses ke set data. Jika pemberian gagal karena agen layanan tidak ada, lihat Pemberian akses set data gagal karena agen layanan tidak ada.
Mengaktifkan logging untuk agen data
Untuk mengaktifkan logging bagi agen data yang ada, tetapkan kolom bigquery_agent_analytics_enabled dan bigquery_agent_analytics_table agen (bigqueryAgentAnalyticsEnabled dan bigqueryAgentAnalyticsTable dalam permintaan HTTP), dan sertakan kedua kolom tersebut dalam update mask. Update hanya mengubah kolom di mask update. Agen layanan hanya menulis baris log saat Anda mengaktifkan logging dan menetapkan tabel log.
Jalankan contoh berikut di lingkungan Python yang Anda siapkan di
Mengonfigurasi setelan dan menginisialisasi
klien
(Python SDK) atau Mengonfigurasi setelan awal dan
autentikasi
(HTTP), seperti notebook Colaboratory. Contoh Python SDK di halaman ini memerlukan google-cloud-geminidataanalytics versi 0.13.4 atau yang lebih baru.
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = True
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(
paths=["bigquery_agent_analytics_enabled", "bigquery_agent_analytics_table"]
)
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
Ganti nilai contoh sebagai berikut:
- DATA_AGENT_ID: ID agen data.
- LOG_DATASET: ID set data log.
- LOG_TABLE: ID tabel log, seperti
agent_events. Jika tabel tidak ada, agen layanan akan membuatnya pada giliran pertama yang dicatat ke dalam log.
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsEnabled": True,
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {
"updateMask": "bigqueryAgentAnalyticsEnabled,bigqueryAgentAnalyticsTable"
}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
if body.get("bigqueryAgentAnalyticsEnabled") and body.get(
"bigqueryAgentAnalyticsTable"
):
print("Conversation logging is turned on.")
else:
print("Logging isn't turned on. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Ganti nilai contoh sebagai berikut:
- DATA_AGENT_ID: ID agen data.
- LOG_DATASET: ID set data log.
- LOG_TABLE: ID tabel log, seperti
agent_events. Jika tabel tidak ada, agen layanan akan membuatnya pada giliran pertama yang dicatat ke dalam log.
Metode ini menampilkan agen data yang diperbarui. Pastikan logging diaktifkan dan tabel log ditetapkan.
Untuk mengaktifkan logging saat membuat agen data, sertakan kolom yang sama dalam permintaan pembuatan Anda. Untuk permintaan pembuatan, lihat Membuat agen data (Python SDK atau HTTP). Dalam isi permintaan HTTP, kolomnya terlihat seperti berikut:
"bigqueryAgentAnalyticsEnabled": true,
"bigqueryAgentAnalyticsTable": {
"projectId": "PROJECT_ID",
"datasetId": "LOG_DATASET",
"tableId": "LOG_TABLE"
}
Ganti nilai contoh sebagai berikut:
- PROJECT_ID: ID project yang berisi agen data.
- LOG_DATASET: ID set data log.
- LOG_TABLE: ID tabel log.
Memastikan bahwa percakapan dicatat ke dalam log
- Mengirim permintaan chat ke agen data. Untuk mengetahui contohnya, lihat Menggunakan API untuk mengajukan pertanyaan (Python SDK atau HTTP).
Tunggu sekitar 10 detik setelah agen menjawab. Kemudian, di Cloud Shell atau terminal, jalankan perintah
bq queryberikut untuk melihat pertanyaan dan jawaban terbaru. Anda juga dapat menjalankan SQL di editor kueri BigQuery.bq query --use_legacy_sql=false ' SELECT timestamp, event_type, JSON_VALUE(content, "$.text_summary") AS text FROM `PROJECT_ID.LOG_DATASET.LOG_TABLE` WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) AND event_type IN ("USER_MESSAGE_RECEIVED", "AGENT_RESPONSE") ORDER BY timestamp DESC LIMIT 20'Ganti nilai contoh sebagai berikut:
- PROJECT_ID: ID project yang berisi agen data.
- LOG_DATASET: ID set data log.
- LOG_TABLE: ID tabel log.
Jika kueri menampilkan pertanyaan Anda dan jawaban agen, logging percakapan berfungsi dengan benar. Jika tabel tidak ada atau kosong, lihat Memecahkan masalah logging percakapan.
Mengubah tabel tujuan
Untuk menulis log ke tabel lain, perbarui kolom bigquery_agent_analytics_table agen data (bigqueryAgentAnalyticsTable dalam permintaan HTTP), dan sertakan kolom tersebut dalam update mask. Tabel baru harus berada dalam project agen data, dan agen layanan harus memiliki peran BigQuery Data Editor di set data tabel baru.
Jalankan contoh berikut di lingkungan yang sama seperti di Mengaktifkan logging untuk agen data.
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_table"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
Ganti nilai contoh sebagai berikut:
- DATA_AGENT_ID: ID agen data.
- NEW_LOG_DATASET: ID set data log baru.
- NEW_LOG_TABLE: ID tabel log baru.
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {"updateMask": "bigqueryAgentAnalyticsTable"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
table = body.get("bigqueryAgentAnalyticsTable", {})
if table.get("datasetId") == log_dataset and table.get("tableId") == log_table:
print("Log table updated.")
else:
print("The log table didn't change. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Ganti nilai contoh sebagai berikut:
- DATA_AGENT_ID: ID agen data.
- NEW_LOG_DATASET: ID set data log baru.
- NEW_LOG_TABLE: ID tabel log baru.
Baris yang sudah dicatat ke dalam log akan tetap berada di tabel sebelumnya. Perubahan akan diterapkan pada giliran berikutnya.
Menonaktifkan logging percakapan
Untuk menonaktifkan logging percakapan bagi agen data, tetapkan kolom bigquery_agent_analytics_enabled agen (bigqueryAgentAnalyticsEnabled dalam permintaan HTTP) ke false, dan sertakan kolom tersebut dalam update mask.
Jalankan contoh berikut di lingkungan yang sama seperti di Mengaktifkan logging untuk agen data.
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = False
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_enabled"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
except Exception as e:
print(f"Error updating data agent: {e}")
Ganti DATA_AGENT_ID dengan ID agen data.
HTTP
data_agent_id = "DATA_AGENT_ID"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {"bigqueryAgentAnalyticsEnabled": False}
params = {"updateMask": "bigqueryAgentAnalyticsEnabled"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
print("Conversation logging is turned off.")
print(json.dumps(data_agent_response.json(), indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
Ganti DATA_AGENT_ID dengan ID agen data.
Perubahan akan diterapkan pada giliran berikutnya. Giliran yang sudah berjalan akan selesai dengan setelan yang berlaku saat giliran tersebut dimulai.
Untuk menghentikan logging bagi semua agen data yang menulis ke set data log, cabut peran BigQuery Data Editor agen layanan pada set data tersebut. Logging tetap diaktifkan untuk setiap agen, tetapi agen layanan tidak dapat lagi menulis baris.
Menonaktifkan logging akan mempertahankan baris yang sudah di-log. Untuk menghapus data yang dicatat ke dalam log, hapus baris, partisi, atau tabel log.
Memecahkan masalah logging percakapan
Gunakan informasi berikut untuk memecahkan masalah umum terkait logging percakapan analisis percakapan di BigQuery. Karena error logging tidak pernah menggagalkan giliran percakapan dan tidak dilaporkan dalam chat, dalam respons API, atau di Cloud Logging, tabel tujuan yang kosong atau tidak ada adalah sinyal utama masalah konfigurasi atau izin.
Tabel log tidak ada atau kosong
Jika tabel tujuan tidak dibuat atau tetap kosong setelah giliran percakapan, periksa kemungkinan penyebab berikut:
Logging percakapan tidak diaktifkan. Pastikan bahwa logging percakapan diaktifkan dan tabel tujuan dikonfigurasi pada agen data.
Set data tujuan tidak ada atau berada di project lain. Pastikan set data tujuan sudah ada di project yang sama dengan agen data. Anda dapat memverifikasi bahwa set data ada dengan menjalankan
bq show PROJECT_ID:LOG_DATASET. GantiPROJECT_IDdengan ID project yang berisi agen data, danLOG_DATASETdengan ID set data tujuan. Agen layanan membuat tabel log pada giliran pertama yang dicatat ke dalam log, tetapi tidak membuat set data.Set data tujuan adalah set data hanya baca, seperti set data tertaut. Set data tertaut BigQuery sharing atau set data eksternal (misalnya, set data gabungan AWS Glue) bersifat hanya baca dan tidak dapat menyimpan log percakapan. Untuk memeriksa jenis set data, jalankan
bq show --format=prettyjson PROJECT_ID:LOG_DATASETdan periksa kolom"type"("LINKED"atau"EXTERNAL"). Pilih set data standar yang dapat ditulis dalam project yang sama dengan agen data.Izin agen layanan atau CMEK tidak ada. Pastikan bahwa agen layanan Analisis Percakapan API (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics., menggunakan nomor project agen, bukan project ID) memiliki peran BigQuery Data Editor (roles/bigquery.dataEditor) di set data log. Jika set data menggunakan kunci Cloud KMS yang dikelola pelanggan (CMEK), pastikan akun layanan enkripsi BigQuery (bq-PROJECT_NUMBER@bigquery-encryption.) memiliki peranroles/cloudkms.cryptoKeyEncrypterDecrypterpada kunci tersebut.Perimeter Kontrol Layanan VPC memblokir penulisan. Agen layanan Analisis Percakapan API menulis ke tabel log dari infrastruktur yang dikelola Google, sehingga memberikan
roles/bigquery.dataEditorsaja tidak cukup jika perimeter layanan membatasibigquery.googleapis.com. Tidak seperti penyebab lain dalam daftar ini, pemblokiran perimeter mencatat log audit Policy Denied di Cloud Logging dalam project agen; filter menurutlog_id("cloudaudit.googleapis.com/policy")di bagianbigquery.googleapis.com(untuk pencarian atau pembuatan tabel) danbigquerystorage.googleapis.com(untuk penambahan baris) untuk mengonfirmasi pemblokiran. Pastikangeminidataanalytics.googleapis.comdanbigquery.googleapis.comberada di perimeter, dan tambahkan aturan ingress untuk agen layanan dibigquery.googleapis.com. Untuk contoh aturan ingress, lihat Kontrol akses, enkripsi, dan keamanan jaringan. Untuk panduan penyiapan perimeter umum, lihat Mengonfigurasi keamanan perimeter dengan Kontrol Layanan VPC.Platform percakapan atau konfigurasi agen tidak didukung. Percakapan di panel Preview BigQuery Studio dan panggilan API stateless tanpa agen data tidak akan dicatat ke dalam log. Untuk menguji, kirim permintaan chat ke agen data melalui API. Agen yang menggunakan cakupan penelusuran, bukan tabel BigQuery tertentu, yang hanya mengonfigurasi grafik properti BigQuery (tanpa tabel BigQuery) sebagai sumber pengetahuan, atau yang tidak mendeklarasikan tabel BigQuery apa pun, tidak akan dicatat ke dalam log. Untuk mengetahui informasi selengkapnya, lihat Batasan.
Tabel sumber pengetahuan menggunakan kebijakan akses. Jika ada tabel sumber pengetahuan (tabel BigQuery di sumber data agen) yang menggunakan kebijakan akses tingkat baris, keamanan tingkat kolom (tag kebijakan), atau penyamaran data dinamis, giliran tidak akan dicatat ke dalam log.
Konflik skema pada tabel tujuan yang ada. Jika Anda mengonfigurasi tabel yang ada sebagai tujuan dan kolom memiliki nama yang sama dengan kolom skema log percakapan, tetapi memiliki jenis atau mode yang berbeda, BigQuery tidak akan menulis baris ke tabel tersebut.
Baris biasanya muncul dalam beberapa detik setelah giliran selesai. Jika baris masih belum muncul setelah Anda menunggu beberapa menit, muat ulang set data.
Percakapan beberapa pengguna tidak dicatat ke dalam log
Penyebab
Sebelum setiap giliran, pemeriksaan privasi menggunakan kredensial pengguna yang melakukan chat untuk memverifikasi bahwa tabel sumber pengetahuan agen tidak memiliki kebijakan keamanan tingkat baris, keamanan tingkat kolom, atau penyamaran data. Jika pengguna tidak memiliki izin untuk menjalankan pemeriksaan ini, gilirannya tidak akan dicatat ke dalam log.
Resolusi
Berikan peran BigQuery Data
Viewer
(roles/bigquery.dataViewer) kepada semua pengguna chat di tabel sumber pengetahuan dan peran
BigQuery Job User
(roles/bigquery.jobUser) pada project yang menjalankan kueri mereka, atau berikan
peran khusus dengan izin bigquery.tables.get dan
bigquery.rowAccessPolicies.list pada tabel sumber pengetahuan.
Pembuatan atau pembaruan agen gagal dengan error INVALID_ARGUMENT
Pesan error
The BigQuery Agent Analytics table must be in the same project as the agent (agent project: ..., table project: ...).BigQuery Agent Analytics can only be enabled on agents whose datasource is BigQuery. Remove bigquery_agent_analytics_enabled and bigquery_agent_analytics_table, or point the agent at a BigQuery datasource.
Penyebab
Set data tujuan berada di project yang berbeda dengan agen data, atau sumber data agen bukan BigQuery.
Resolusi
Tentukan set data tujuan yang ada dalam project yang sama dengan agen data, atau konfigurasikan agen data dengan sumber data BigQuery.
Pemberian akses set data gagal karena agen layanan tidak ada
Pesan error
Service account service-PROJECT_NUMBER@gcp-sa-geminidataanalytics... does not exist
Penyebab
Agen layanan Analisis Percakapan API belum disediakan dalam project.
Resolusi
Lakukan salah satu hal berikut:
Konfigurasikan tujuan log pada agen terlebih dahulu, lalu berikan peran lagi.
Sediakan identitas layanan dengan menjalankan perintah berikut:
gcloud beta services identity create \ --service=geminidataanalytics.googleapis.com \ --project=PROJECT_ID
Ganti
PROJECT_IDdengan ID project yang berisi agen data.