Logging percakapan memungkinkan Anda merekam percakapan agen data Analisis Percakapan API dalam Tabel BigQuery di project Anda, sehingga Anda dapat meninjau kualitas jawaban, melacak adopsi, dan memantau biaya. Untuk setiap giliran, log akan mencatat pertanyaan pengguna,
jawaban agen, latensi, penggunaan token model, dan ID yang Anda
perlukan untuk mengelompokkan giliran berdasarkan agen, percakapan, dan pengguna. Baris ditulis menggunakan skema BigQuery Agent Analytics melalui BigQuery Storage Write API (gRPC). Anda dapat
mengaktifkan logging untuk agen data yang sumber datanya merujuk ke
tabel BigQuery dengan menetapkan kolom bigqueryAgentAnalyticsEnabled
dan bigqueryAgentAnalyticsTable-nya. Untuk mengetahui langkah-langkahnya, lihat Mengaktifkan logging percakapan.
Yang dicatat ke dalam log
Setiap giliran yang dicatat ke dalam log akan menulis beberapa baris peristiwa (events) ke tabel tujuan yang mencatat informasi berikut:
Pertanyaan pengguna.
Jawaban agen: teks, insight, asumsi, pertanyaan lanjutan yang disarankan, sumber kutipan, dan nama hasil data atau diagram.
Latensi per giliran.
Penggunaan token model, versi model, dan alasan penyelesaian (alasan model berhenti menghasilkan token) untuk setiap panggilan model.
ID agen data dan ID percakapan (untuk chat dengan referensi percakapan), sehingga Anda dapat menganalisis beberapa agen dalam satu tabel.
ID pengguna. Untuk informasi selengkapnya tentang ID pengguna, lihat Identitas pengguna.
Detail status dan error.
Yang tidak dicatat ke dalam log
Logging percakapan tidak merekam hal berikut:
Kueri SQL yang dijalankan agen: log berisi jawaban akhir serta nama hasil data dan diagram yang direferensikan, tetapi bukan kueri yang menghasilkannya. Pengecualiannya adalah saat pengguna secara eksplisit meminta agen untuk menampilkan atau menjelaskan SQL; dalam hal ini, SQL dapat muncul dalam teks jawaban.
Panggilan alat agen: setiap panggilan model menulis satu baris
LLM_RESPONSE, termasuk panggilan saat model memutuskan untuk menjalankan alat. Sebelum baris ditulis, output model akan dihapus, termasuk nama dan argumen alat apa pun yang dipanggilnya. Hanya penggunaan token, versi model, dan alasan selesai yang disimpan.Masukan pengguna: masukan suka atau tidak suka tidak dicatat dalam log.
Beberapa percakapan tidak dicatat sama sekali, seperti panggilan API stateless tanpa agen data. Untuk mengetahui informasi selengkapnya tentang platform percakapan yang tidak didukung, lihat Batasan.
Cara kerja logging percakapan
Saat pengguna melakukan chat dengan agen data yang mengaktifkan logging percakapan, analisis percakapan akan memproses setiap giliran melalui tahap-tahap berikut:
Mengonfigurasi: pemilik agen mengaktifkan logging percakapan dan menentukan set data tujuan dan nama tabel yang ada dalam project agen menggunakan API Analisis Percakapan.
Tanya: pengguna mengirim pertanyaan ke agen. Jika Anda memanggil Conversational Analytics API dari aplikasi Anda sendiri, Anda bertanggung jawab untuk memberi tahu pengguna Anda. Pengguna yang melakukan percakapan dengan agen di BigQuery Studio akan melihat pemberitahuan bahwa percakapan mereka dicatat dalam log.
Pemeriksaan privasi: sebelum agen mulai mengerjakan giliran, pemeriksaan privasi membaca metadata tabel sumber pengetahuan agen (sumber data BigQuery-nya) menggunakan kredensial pengguna yang melakukan chat. Pemeriksaan ini mengonfirmasi bahwa tidak ada tabel yang menggunakan keamanan tingkat baris (kebijakan akses baris), keamanan tingkat kolom (tag kebijakan), atau penyamaran data dinamis. Jika pemeriksaan menemukan kebijakan atau tidak dapat mengonfirmasi bahwa tidak ada kebijakan, giliran tidak akan dicatat, dan agen tetap menjawab pertanyaan pengguna.
Answer: agen menjawab pengguna seperti biasa.
Tulis: agen layanan Analisis Percakapan API project (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.) menulis baris log ke tabel tujuan melalui Storage Write API (gRPC). Pada giliran pertama yang dicatat ke dalam log, agen layanan akan membuat tabel jika belum ada.Kueri: baris biasanya muncul dalam beberapa detik setelah jawaban selesai. Waktu pengiriman tidak dijamin.
Error logging tidak pernah menggagalkan giliran, dan pemeriksaan privasi serta penulisan log dapat menambah latensi. Izin yang tidak ada pada set data log, set data yang tidak ada, atau kuota yang habis tidak akan menggagalkan permintaan chat atau panggilan API. Analisis percakapan tidak melaporkan kegagalan logging di antarmuka chat, dalam respons API, atau di Cloud Logging.
Privasi, tata kelola data, dan keamanan
Saat Anda mengaktifkan logging percakapan untuk agen, tinjau cara pemberitahuan pengguna akhir, akses data, enkripsi, kontrol jaringan, dan logging audit diterapkan ke log Anda.
Pemberitahuan pengguna akhir dan konten yang dicatat dalam log
Pemberitahuan dan aturan berikut mengatur apa yang dicatat oleh logging percakapan dan siapa yang dapat melihat data yang dicatat:
Pemberitahuan pengguna akhir di BigQuery Studio: saat logging percakapan diaktifkan untuk agen, pengguna yang melakukan percakapan dengan agen di BigQuery Studio akan melihat pemberitahuan berikut setiap kali logging percakapan diaktifkan, termasuk di layar percakapan baru sebelum pengguna mengirim perintah pertama:
Semua perintah dan respons dicatat ke BigQuery dan dapat diakses oleh pengguna yang memiliki izin set data.
Tanggung jawab Anda saat menggunakan API: jika Anda mengaktifkan logging percakapan (logging rekaman aktivitas) di agen data dan menyediakan agen tersebut kepada pengguna akhir melalui aplikasi atau integrasi Anda sendiri, Google tidak dapat menampilkan pemberitahuan kepada pengguna tersebut. Anda bertanggung jawab atas pemberitahuan, pengungkapan, atau izin apa pun yang berlaku untuk percakapan yang dicatat dalam log berdasarkan hukum yang berlaku dan perjanjian Anda dengan pengguna akhir. Untuk mengetahui informasi selengkapnya, lihat Keamanan, privasi, risiko, dan kepatuhan untuk API Analisis Percakapan.
Isi log, dan siapa yang dapat melihatnya: tabel tujuan menyimpan konten tanya jawab berdasarkan aturan privasi berikut:
Pertanyaan dan jawaban lengkap: jawaban dapat mencakup nilai yang ditampilkan dari sumber informasi Anda. Siapa pun yang dapat membaca tabel log dapat melihat data yang ditampilkan agen kepada pengguna, termasuk data yang tidak dapat mereka baca di tabel sumber. Berikan akses baca ke set data log hanya kepada orang yang seharusnya melihat konten ini.
ID pengguna dan lokasi penulisan: kolom
user_idmengidentifikasi penelepon yang mengajukan pertanyaan (lihat Identitas pengguna), dan baris hanya ditulis ke tujuan yang Anda konfigurasi di project agen.Tabel dengan keamanan tingkat baris, keamanan tingkat kolom, atau penyamaran data: jika sumber pengetahuan agen menggunakan keamanan tingkat baris (kebijakan akses baris), keamanan tingkat kolom (tag kebijakan), atau penyamaran data dinamis, responsnya tidak akan dicatat ke dalam log. Pemeriksaan privasi akan melewati tabel di
bigquery-public-datadan hanya melihat tabel dan tampilan yang Anda pilih sebagai sumber pengetahuan, bukan tabel di balik tampilan:Tampilan di atas tabel yang menggunakan kebijakan ini dapat lulus pemeriksaan, sehingga gilirannya dapat dicatat ke dalam log. Sebelum mengaktifkan logging, pastikan tabel di balik tampilan tidak menggunakan kebijakan akses baris, tag kebijakan, atau penyamaran data.
Jika Anda menambahkan salah satu kebijakan ini ke tabel sumber nanti, baris yang sudah dicatat ke dalam log akan tetap berada di tabel log. Jika kebijakan retensi atau tata kelola Anda melarang penyimpanan baris tersebut, hapus baris tersebut.
Kontrol akses, enkripsi, dan keamanan jaringan
Anda dapat mengelola retensi, akses, enkripsi, dan keamanan perimeter untuk log percakapan Anda menggunakan setelan berikut:
Retensi dan kontrol akses pada set data log: mengonfigurasi retensi, peran set data, kebijakan tabel, dan log audit untuk tabel tujuan Anda:
Retensi: Google tidak menghapus baris log. Tetapkan masa berlaku partisi pada set data atau tabel log yang sesuai dengan kebijakan Anda (misalnya, 90 hari).
Hak istimewa terendah: pisahkan set data log dari set data lainnya agar akses tulis agen layanan API Analisis Percakapan bersama tidak dapat mengakses tabel lainnya. Berikan
roles/bigquery.dataViewerkepada analis di set data log, atau beri mereka akses hanya ke tampilan yang diizinkan atau set data yang diizinkan.Kontrol tingkat kolom dan tingkat baris pada tabel log: Anda dapat menerapkan tag kebijakan, penyamaran data, atau kebijakan akses baris ke tabel log itu sendiri, seperti pada
contentatauuser_id. Kontrol tabel log ini tidak memengaruhi pemeriksaan privasi sumber pengetahuan.Logging audit: perubahan konfigurasi agen data dan operasi tabel log dicatat dalam log audit. Untuk mengetahui informasi selengkapnya, lihat Operasi yang diaudit.
CMEK, Kontrol Layanan VPC, dan residensi data: kontrol enkripsi, perimeter, dan lokasi berikut berlaku untuk logging percakapan:
CMEK: jika set data log menggunakan kunci Cloud KMS yang dikelola pelanggan (CMEK), berikan peran
roles/cloudkms.cryptoKeyEncrypterDecrypterpada kunci ke akun layanan enkripsi BigQuery (bq-PROJECT_NUMBER@bigquery-encryption.). CMEK pada agen data mengenkripsi resource agen, bukan tabel log (lihat Kunci enkripsi yang dikelola pelanggan).Kontrol Layanan VPC: jika Anda menggunakan perimeter layanan, sertakan
geminidataanalytics.googleapis.comdanbigquery.googleapis.comdalam perimeter yang berisi project agen. Agen layanan menulis ke tabel log dari infrastruktur yang dikelola Google, jadi jika perimeter membatasibigquery.googleapis.com, tambahkan aturan ingress seperti berikut. GantiPROJECT_NUMBERdengan nomor project agen:- ingressFrom: identities: - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics. sources: - accessLevel: "*" ingressTo: operations: - serviceName: bigquery.googleapis.com methodSelectors: - permission: bigquery.tables.get - permission: bigquery.tables.create - permission: bigquery.tables.update - permission: bigquery.tables.updateData resources: - projects/PROJECT_NUMBERUntuk mengetahui informasi selengkapnya, lihat Mengonfigurasi keamanan perimeter dengan Kontrol Layanan VPC.
Residensi data: baris log dan tabel yang dibuat otomatis disimpan di lokasi set data log, tempat kebijakan organisasi lokasi resource (
gcp.resourceLocations) berlaku.
Atribusi agen layanan dan penelepon
Agen layanan Analisis Percakapan API, bukan pengguna yang melakukan chat, yang membuat dan memperbarui tabel log serta menambahkan baris ke dalamnya. Untuk melakukan operasi ini, agen layanan memerlukan peran BigQuery Data Editor (roles/bigquery.dataEditor) di set data log.
Dalam entri log audit yang dicatat oleh Cloud Audit Logs, kolom authenticationInfo.principalEmail (atau authenticationInfo.principalSubject untuk identitas gabungan) mengidentifikasi akun utama yang melakukan setiap operasi:
Mencatat pembuatan tabel, pembaruan skema, dan penambahan baris ke dalam log: agen layanan,
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics..Permintaan konfigurasi agen data (
CreateDataAgent,CreateDataAgentSync,UpdateDataAgent, danUpdateDataAgentSync): pengguna, akun layanan, atau identitas gabungan yang memanggil API. Jika kredensial akun layanan yang didelegasikan berlaku, entri ini juga menyertakanauthenticationInfo.serviceAccountDelegationInfo.
Operasi yang diaudit
Cloud Audit Logs mencatat perubahan konfigurasi logging percakapan dan operasi tabel log untuk layanan berikut:
Analisis Percakapan API: metode berikut menghasilkan log audit di bagian
geminidataanalytics.googleapis.com:CreateDataAgent,CreateDataAgentSync,UpdateDataAgent, danUpdateDataAgentSyncmembuat log audit Aktivitas Admin yang mencatat kolombigqueryAgentAnalyticsEnableddanbigqueryAgentAnalyticsTableagen, termasuk project, set data, dan tabel tujuan.SetAgentOpsObservabilitymenghasilkan log audit Aktivitas Admin yang mencatat kolomdataSourceType,telemetryEnabled,bqaaEnabled, danupdateMaskpermintaan.RetrieveAgentOpsObservabilitymenghasilkan log audit Akses Data saat jenis log auditADMIN_READatauDATA_READyang sesuai diaktifkan untukgeminidataanalytics.googleapis.com.
BigQuery: operasi agen layanan pada tabel log dan kueri yang Anda jalankan terhadapnya akan menghasilkan log audit berikut:
Pembuatan tabel log dan update skema menghasilkan log audit Aktivitas Admin di bagian
bigquery.googleapis.com.Penambahan baris melalui Storage Write API (gRPC) menghasilkan log audit Akses Data untuk metode
google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows, termasuk metadataTableDataChange(WRITE_API_APPEND_ROWS). Entri ini menggunakan nama layananbigquery.googleapis.com, bukanbigquerystorage.googleapis.com; hanya log audit Kebijakan Ditolak yang menggunakanbigquerystorage.googleapis.com.Kueri terhadap tabel log menghasilkan log audit Akses Data di bagian
bigquery.googleapis.com, seperti entriJobInsertion,JobChange, danTableDataRead.
Untuk mengetahui informasi selengkapnya, lihat Logging audit Analisis Percakapan API dan Ringkasan log audit BigQuery.
Batasan
Logging percakapan memiliki batasan berikut:
Panel Preview di editor agen BigQuery Studio tidak dicatat dalam log.
Panggilan API stateless tanpa agen data tidak akan dicatat ke dalam log.
Agen yang menggunakan cakupan penelusuran, bukan tabel tertentu, atau yang tidak mendeklarasikan tabel BigQuery apa pun, tidak akan dicatat ke dalam log. Agen yang hanya mengonfigurasi grafik properti BigQuery (tanpa tabel BigQuery) sebagai sumber pengetahuan tidak akan dicatat ke dalam log.
SQL yang dihasilkan, panggilan alat, dan peristiwa permintaan atau alat Agent Development Kit (ADK) (
TOOL_STARTING,TOOL_COMPLETED,TOOL_ERROR, danLLM_REQUEST) tidak dicatat dalam log; hanya jawaban dan nama hasil data serta diagramnya yang dicatat dalam log. Giliran yang dijawab langsung dari kueri terverifikasi tidak menulis barisLLM_RESPONSE, dan giliran kueri terverifikasi yang gagal tidak dicatat dalam log.Masukan pengguna berupa suka atau tidak suka tidak dicatat dalam log.
Giliran tidak dicatat ke dalam log jika sumber pengetahuan menggunakan kebijakan akses baris, keamanan tingkat kolom (tag kebijakan), atau penyamaran data, termasuk kebijakan data yang dilampirkan langsung ke kolom. Giliran juga tidak dicatat dalam log jika pemeriksaan privasi tidak dapat memverifikasi kebijakan ini, seperti saat pengguna yang melakukan chat tidak memiliki izin untuk memeriksa metadata kebijakan tabel atau waktu pemeriksaan habis. Pemeriksaan tidak melihat melalui tampilan ke tabel di belakangnya.
Hanya agen tabel BigQuery yang didukung; sumber data Looker, Data Studio, AlloyDB untuk PostgreSQL, Spanner, dan Cloud SQL tidak didukung.
Set data tujuan harus sudah ada dalam project yang sama dengan agen.
Perubahan skema pada tabel yang ada hanya bersifat aditif; jenis atau mode kolom yang bertentangan akan menghentikan penulisan ke tabel tersebut.
Setiap giliran yang memenuhi syarat dicatat tanpa setelan pengambilan sampel; ambil sampel pada waktu kueri (lihat Mengambil sampel pertanyaan dan jawaban di semua agen untuk ditinjau).
Kolom
agentmenyimpan jenis agen, bukan nama tampilan agen; gunakan ID agen data diattributes.Pemanggil API yang menggunakan satu akun layanan untuk banyak pengguna akhir akan melihat email akun layanan tersebut di setiap baris.
Nilai teks yang lebih panjang dari 512.000 karakter (
500 * 1,024) akan dipotong dengan akhiran...[TRUNCATED], dan bagian yang dihapus tidak dapat dipulihkan.Operasi tulis dilakukan dengan upaya terbaik dan percobaan ulang terbatas; giliran yang gagal ditulis tidak akan dicatat ke dalam log, dan percobaan ulang terkadang dapat menghasilkan baris duplikat (gunakan
event_iduntuk menghapus duplikat).Agen tidak mewarisi setelan kemampuan observasi level project.
Harga
Analisis percakapan tidak mengenakan biaya terpisah untuk logging percakapan.
Project Anda membayar harga BigQuery standar untuk penyerapan data BigQuery Storage Write API (gRPC), penyimpanan, dan kueri analisis. Penyerapan BigQuery Storage Write API (gRPC) mencakup penggunaan gratis sebesar 2 TiB per bulan untuk setiap akun penagihan, yang digunakan bersama di seluruh penggunaan Storage Write API (gRPC). Filter kueri di timestamp untuk mengurangi byte yang dipindai. Pemeriksaan privasi sebelum giliran membaca metadata tabel dan menjalankan kueri uji coba tanpa biaya.