對話記錄結構定義
本文說明 BigQuery 中對話式數據分析對話記錄的資料表版面配置、資料欄、事件類型、使用者身分欄位和 JSON 酬載結構。如要概略瞭解對話記錄的運作方式，請參閱「對話記錄總覽」。
表格版面配置和自動建立
請先在資料代理所在的專案中建立目的地資料集，再啟用記錄功能。Conversational Analytics API 服務代理會在第一個記錄的回合中，於資料集的位置建立資料表 (或將缺少的結構定義資料欄新增至現有的相容資料表)。自動建立的資料表會依 timestamp 逐日分區 (繼承資料集上的任何預設分區到期時間)，並依 event_type、agent 和 user_id 分群。查詢資料表時，請一律篩選 timestamp。
資料欄
下表說明對話記錄目的地資料表中的資料欄。
| 欄 | 類型 | 模式 | 目錄 |
|---|---|---|---|
timestamp |
TIMESTAMP |
REQUIRED |
事件的世界標準時間。分區資料欄。 |
event_id |
STRING |
NULLABLE |
事件的專屬 ID。即使重試寫入作業，這個 ID 也不會改變，因此您可以使用這個 ID 移除重複項目。 |
event_type |
STRING |
NULLABLE |
事件類型。請參閱「事件類型」。 |
agent |
STRING |
NULLABLE |
代理類型，而非代理名稱或 ID (例如 ConversationalAnalyticsAgent)。如要區分代理，請使用資料代理 ID (請參閱「attributes 內的欄位」)。 |
session_id |
STRING |
NULLABLE |
一個回合，而非整個對話。一個問題及其答案的所有事件都會共用 session_id。如要將對話回合分組，請使用 attributes 中的對話 ID。 |
invocation_id |
STRING |
NULLABLE |
一輪對話中的一次執行作業。 |
user_id |
STRING |
NULLABLE |
提出問題的來電者。請參閱「使用者身分」。 |
trace_id |
STRING |
NULLABLE |
OpenTelemetry 追蹤記錄 ID (32 個十六進位字元)。 |
span_id |
STRING |
NULLABLE |
這項作業在回合執行樹狀結構中的 ID。 |
parent_span_id |
STRING |
NULLABLE |
父項作業的 ID。 |
content |
JSON |
NULLABLE |
事件酬載。形狀取決於 event_type。 |
content_parts |
RECORD |
REPEATED |
多部分內容，每個部分有一個元素 (例如 mime_type、uri、object_ref、text、part_index、part_attributes 和 storage_mode)。 |
attributes |
JSON |
NULLABLE |
中繼資料：資料代理 ID、對話 ID、內部使用者金鑰、模型版本，以及詳細的權杖用量。 |
latency_ms |
JSON |
NULLABLE |
延遲時間測量指標，例如 total_ms 和 time_to_first_token_ms。 |
status |
STRING |
NULLABLE |
OK 或 ERROR。 |
error_message |
STRING |
NULLABLE |
錯誤詳細資料。如果模型因正常停止以外的原因而停止 (例如達到詞元數量上限)，系統也會在 OK
LLM_RESPONSE 資料列中設定這個值。 |
is_truncated |
BOOLEAN |
NULLABLE |
如果事件中的任何文字值超過 512,000 個字元 (500 * 1,024) 並遭到截斷，則為 true。剪輯值結尾為 ...[TRUNCATED]。移除後即無法復原。 |
事件類型
下表說明 event_type 欄中可能顯示的值，以及儲存各事件資料的資料欄或 JSON 欄位。
event_type 值 |
說明 | 填入資料的資料欄和 JSON 欄位 |
|---|---|---|
INVOCATION_STARTING |
轉彎起點。 | 無 |
USER_MESSAGE_RECEIVED |
使用者的問題。 | content.text_summary |
AGENT_RESPONSE |
代理的回覆，以結構化物件呈現。 | content.text_summary (純文字) 和 content.response (請參閱「AGENT_RESPONSE 的結構」) |
LLM_RESPONSE |
每個模型呼叫都會有一列，包括要求工具的呼叫 (如果直接從已驗證的查詢回答一輪，則不會寫入，其中 attributes.fast_path 為 true)。系統不會儲存模型的輸出內容。 |
權杖：content.usage.prompt、content.usage.completion、content.usage.total。模型：attributes.model_version。完成原因：attributes.finish_reason。詳細用法：attributes.usage_metadata (例如 cached_content_token_count 和 thoughts_token_count)。 |
INVOCATION_COMPLETED |
對話結束，並顯示每輪對話的延遲時間。content 是空的。 |
latency_ms.total_ms |
EMBEDDING_SUGGESTION |
建議代理擁有者，哪些資料欄可透過嵌入功能提升成效。這個按鈕只會顯示在部分代理程式。 | content.reason，content.suggested_columns |
INVOCATION_ERROR、AGENT_ERROR、LLM_ERROR |
轉彎失敗。status 為 ERROR，content 為 NULL。 |
error_message (單行摘要，已遮蓋 SQL 陳述式和資料表名稱) |
使用者身分
user_id 欄包含呼叫者的電子郵件地址：使用者的電子郵件地址、API 呼叫者使用服務帳戶驗證時的服務帳戶電子郵件地址，或 NULL (如果呼叫者沒有電子郵件地址，例如某些員工身分聯盟身分)。系統也會在每個資料列的 attributes.session_metadata.user_id 中記錄內部使用者金鑰，因此您可以使用 internal_user_key 計算不重複使用者 (請參閱「建立跨代理事件檢視畫面」)。
如要在透過服務帳戶呼叫 API 時，將對話歸因於自己的使用者，請在應用程式中記錄使用者對應。API 不接受使用者 ID 記錄。
attributes 內的欄位
下表顯示用於從 attributes JSON 資料欄擷取中繼資料欄位的 GoogleSQL 運算式。
| 需求條件 | GoogleSQL 運算式 |
|---|---|
| 資料代理 ID | JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"') |
| 資料代理完整資源名稱 | JSON_VALUE(attributes, '$.adk.app_name') |
| 對話 ID | JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"') |
| 內部使用者金鑰 | JSON_VALUE(attributes, '$.session_metadata.user_id') |
模型版本 (LLM_RESPONSE 列) |
JSON_VALUE(attributes, '$.model_version') |
AGENT_RESPONSE 的結構
如要以純文字形式讀取代理的回覆，請使用 JSON_VALUE(content, '$.text_summary')。結合答案的 Markdown、假設和洞察部分，以及任何釐清問題。在 AGENT_RESPONSE 資料列中，content.response 是 JSON 物件，而非字串，因此 JSON_VALUE(content, '$.response') 會傳回 NULL。
下表說明 content.response 下方的路徑。
content.response 底下的路徑 |
類型 | 目錄 |
|---|---|---|
parts |
ARRAY<JSON> |
答案就在這裡。 |
parts[].markdown |
STRING |
答案文字 (Markdown)。 |
parts[].insight |
STRING |
從資料中得出的洞察資訊。 |
parts[].assumption |
STRING |
代理做出的假設。 |
parts[].data_result_artifact_name |
STRING |
資料結果的名稱。 |
parts[].chart_artifact_name |
STRING |
圖表名稱。 |
followup_questions |
ARRAY<STRING> |
建議的後續問題。 |
clarifying_question |
STRING |
設定代理向使用者提出釐清問題，而非回答問題的時間。 |
citation_sources |
JSON |
答案中引用的來源。 |