Skema log percakapan

Dokumen ini menjelaskan tata letak tabel, kolom, jenis peristiwa, kolom identitas pengguna, dan struktur payload JSON untuk logging percakapan analisis percakapan di BigQuery. Untuk ringkasan tentang cara kerja logging percakapan, lihat Ringkasan logging percakapan.

Tata letak tabel dan pembuatan otomatis

Buat set data tujuan dalam project yang sama dengan agen data sebelum mengaktifkan logging; agen layanan Conversational Analytics API membuat tabel di lokasi set data pada giliran pertama yang dicatat ke dalam log (atau menambahkan kolom skema yang tidak ada ke tabel yang kompatibel yang sudah ada). Tabel yang dibuat otomatis dipartisi berdasarkan hari di timestamp (mewarisi masa berlaku partisi default pada set data) dan dikelompokkan di event_type, agent, dan user_id. Selalu filter di timestamp saat Anda membuat kueri tabel.

Kolom

Tabel berikut menjelaskan kolom dalam tabel tujuan logging percakapan.

Kolom Jenis Mode Daftar Isi
timestamp TIMESTAMP REQUIRED Waktu UTC peristiwa. Kolom partisi.
event_id STRING NULLABLE ID unik untuk peristiwa. ID ini tetap sama jika penulisan dicoba lagi, sehingga Anda dapat menggunakannya untuk menghapus duplikat.
event_type STRING NULLABLE Jenis acara. Lihat Jenis peristiwa.
agent STRING NULLABLE Jenis agen, bukan nama atau ID agen Anda (misalnya, ConversationalAnalyticsAgent). Untuk membedakan agen, gunakan ID agen data (lihat Kolom di dalam attributes).
session_id STRING NULLABLE Satu giliran, bukan seluruh percakapan. Semua peristiwa untuk satu pertanyaan dan jawabannya memiliki session_id yang sama. Untuk mengelompokkan giliran menjadi percakapan, gunakan ID percakapan di attributes.
invocation_id STRING NULLABLE Satu eksekusi dalam satu giliran.
user_id STRING NULLABLE Penelepon yang mengajukan pertanyaan. Lihat Identitas pengguna.
trace_id STRING NULLABLE ID trace OpenTelemetry (32 karakter heksadesimal).
span_id STRING NULLABLE ID operasi ini di hierarki eksekusi giliran.
parent_span_id STRING NULLABLE ID operasi induk.
content JSON NULLABLE Payload peristiwa. Bentuknya bergantung pada event_type.
content_parts RECORD REPEATED Konten multi-bagian, dengan satu elemen per bagian (misalnya, mime_type, uri, object_ref, text, part_index, part_attributes, dan storage_mode).
attributes JSON NULLABLE Metadata: ID agen data, ID percakapan, kunci pengguna internal, versi model, dan penggunaan token mendetail.
latency_ms JSON NULLABLE Pengukuran latensi, seperti total_ms dan time_to_first_token_ms.
status STRING NULLABLE OK atau ERROR.
error_message STRING NULLABLE Detail error. Nilai ini juga dapat ditetapkan pada baris OK LLM_RESPONSE saat model berhenti karena alasan selain penghentian normal (misalnya, saat mencapai batas token maksimum).
is_truncated BOOLEAN NULLABLE true jika ada nilai teks dalam peristiwa yang melebihi 512.000 karakter (500 * 1,024) dan dipotong. Nilai potongan diakhiri dengan ...[TRUNCATED]. Bagian yang dihapus tidak dapat dipulihkan.

Jenis peristiwa

Tabel berikut menjelaskan nilai yang dapat muncul di kolom event_type dan kolom atau kolom JSON yang menyimpan data untuk setiap peristiwa.

Nilai event_type Deskripsi Kolom yang terisi dan kolom JSON
INVOCATION_STARTING Awal giliran. Tidak ada
USER_MESSAGE_RECEIVED Pertanyaan pengguna. content.text_summary
AGENT_RESPONSE Jawaban agen, sebagai objek terstruktur. content.text_summary (teks biasa) dan content.response (lihat Struktur AGENT_RESPONSE)
LLM_RESPONSE Satu baris untuk setiap panggilan model, termasuk panggilan yang meminta alat (tidak ditulis saat giliran dijawab langsung dari kueri terverifikasi, dengan attributes.fast_path adalah true). Output model tidak disimpan. Token: content.usage.prompt, content.usage.completion, content.usage.total. Model: attributes.model_version. Alasan penyelesaian: attributes.finish_reason. Penggunaan mendetail: attributes.usage_metadata (misalnya, cached_content_token_count dan thoughts_token_count).
INVOCATION_COMPLETED Akhir giliran, dengan latensi per giliran. content kosong. latency_ms.total_ms
EMBEDDING_SUGGESTION Saran untuk pemilik agen tentang kolom yang dapat memperoleh manfaat dari embedding. Kolom ini hanya muncul untuk beberapa agen. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR Giliran gagal. status adalah ERROR dan content adalah NULL. error_message (ringkasan satu baris dengan pernyataan SQL dan nama tabel yang disamarkan)

Identitas pengguna

Kolom user_id berisi alamat email pemanggil: alamat email pengguna, alamat email akun layanan saat pemanggil API melakukan autentikasi dengan akun layanan, atau NULL jika pemanggil tidak memiliki alamat email (seperti beberapa identitas gabungan Workforce Identity Federation). Kunci pengguna internal juga dicatat di attributes.session_metadata.user_id pada setiap baris, sehingga Anda dapat menghitung pengguna yang berbeda dengan internal_user_key (lihat Membuat tampilan peristiwa lintas agen).

Untuk mengatribusikan giliran ke pengguna akhir Anda sendiri saat Anda memanggil API melalui akun layanan, catat pemetaan pengguna di aplikasi Anda. API tidak menerima ID pengguna akhir untuk logging.

Kolom di dalam attributes

Tabel berikut menunjukkan ekspresi GoogleSQL yang digunakan untuk mengekstrak kolom metadata dari kolom JSON attributes.

Yang Anda perlukan Ekspresi GoogleSQL
ID agen data JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
Nama lengkap resource agen data JSON_VALUE(attributes, '$.adk.app_name')
ID Percakapan JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
Kunci pengguna internal JSON_VALUE(attributes, '$.session_metadata.user_id')
Versi model (pada LLM_RESPONSE baris) JSON_VALUE(attributes, '$.model_version')

Struktur AGENT_RESPONSE

Untuk membaca jawaban agen sebagai teks biasa, gunakan JSON_VALUE(content, '$.text_summary'). Respons ini menggabungkan bagian Markdown, asumsi, dan insight jawaban, serta pertanyaan klarifikasi. Dalam baris AGENT_RESPONSE, content.response adalah objek JSON, bukan string, sehingga JSON_VALUE(content, '$.response') menampilkan NULL.

Tabel berikut menjelaskan jalur di bagian content.response.

Jalur di content.response Jenis Daftar Isi
parts ARRAY<JSON> Jawabannya, dalam beberapa bagian.
parts[].markdown STRING Teks jawaban (Markdown).
parts[].insight STRING Insight yang diambil dari data.
parts[].assumption STRING Asumsi yang dibuat agen.
parts[].data_result_artifact_name STRING Nama hasil data.
parts[].chart_artifact_name STRING Nama diagram.
followup_questions ARRAY<STRING> Pertanyaan lanjutan yang disarankan.
clarifying_question STRING Ditetapkan saat agen mengajukan pertanyaan klarifikasi kepada pengguna, bukan menjawab.
citation_sources JSON Sumber yang dikutip dalam jawaban.

Langkah berikutnya