סכימה של יומן השיחות

במאמר הזה מוסבר על פריסת הטבלה, העמודות, סוגי האירועים, שדות זהות המשתמש ומבנה המטען הייעודי (payload) של JSON לרישום ביומן של ניתוח נתוני השיחות ב-BigQuery. במאמר סקירה כללית על תיעוד שיחות מוסבר איך פועל תיעוד השיחות.

פריסת טבלה ויצירה אוטומטית

לפני שמפעילים את הרישום ביומן, צריך ליצור את מערך הנתונים של היעד באותו פרויקט שבו נמצא סוכן הנתונים. סוכן השירות של Conversational Analytics API יוצר את הטבלה במיקום של מערך הנתונים בתור הראשון שנרשם ביומן (או מוסיף עמודות סכימה חסרות לטבלה תואמת קיימת). הטבלה שנוצרת באופן אוטומטי מחולקת למחיצות לפי יום ב-timestamp (היא יורשת את כל תפוגות ברירת המחדל של המחיצות במערך הנתונים) ומקובצת לפי event_type, agent ו-user_id. תמיד צריך לסנן לפי timestamp כששולחים שאילתה לטבלה.

Columns

בטבלה הבאה מתוארות העמודות בטבלת היעד של רישום השיחות ביומן.

עמודה סוג מצב תוכן עניינים
timestamp TIMESTAMP REQUIRED השעה של האירוע לפי שעון UTC. עמודת החלוקה למחיצות.
event_id STRING NULLABLE המזהה הייחודי של האירוע. הוא נשאר זהה אם מנסים שוב לכתוב, כך שאפשר להשתמש בו כדי להסיר כפילויות.
event_type STRING NULLABLE סוג האירוע. סוגי אירועים
agent STRING NULLABLE סוג הסוכן, לא השם או המזהה של הסוכן (לדוגמה, ConversationalAnalyticsAgent). כדי להבדיל בין הסוכנים, משתמשים במזהה של סוכן הנתונים (ראו שדות בתוך attributes).
session_id STRING NULLABLE תור אחד, לא שיחה שלמה. לכל האירועים של שאלה אחת והתשובה שלה יש session_id משותף. כדי לקבץ פניות לשיחות, משתמשים במזהה השיחה ב-attributes.
invocation_id STRING NULLABLE הרצה אחת בכל תור.
user_id STRING NULLABLE המשתתף ששאל את השאלה. זהות המשתמש
trace_id STRING NULLABLE מזהה המעקב של OpenTelemetry (32 תווים בבסיס הקסדצימלי).
span_id STRING NULLABLE מזהה הפעולה הזו בעץ הביצוע של התור.
parent_span_id STRING NULLABLE המזהה של פעולת ההורה.
content JSON NULLABLE המטען הייעודי של האירוע. הצורה שלו תלויה בevent_type.
content_parts RECORD REPEATED תוכן שמורכב מכמה חלקים, עם רכיב אחד לכל חלק (לדוגמה, mime_type,‏ uri,‏ object_ref,‏ text,‏ part_index,‏ part_attributes ו-storage_mode).
attributes JSON NULLABLE מטא-נתונים: מזהה סוכן הנתונים, מזהה השיחה, מפתח המשתמש הפנימי, גרסת המודל ופירוט השימוש באסימונים.
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 ‫true אם ערך טקסט כלשהו באירוע חרג מ-512,000 תווים (500 * 1,024) ונחתך. הערכים החתוכים מסתיימים ב-...[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 לא מקבל מזהה משתמש לצורך רישום ביומן.

שדות בתוך attributes

בטבלה הבאה מוצגים ביטויי GoogleSQL שמשמשים לחילוץ שדות של מטא-נתונים מהעמודה attributes בפורמט JSON.

מה צריך ביטוי GoogleSQL
מזהה סוכן הנתונים JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
השם המלא של המשאב של סוכן הנתונים JSON_VALUE(attributes, '$.adk.app_name')
מזהה השיחה 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 המקורות שצוטטו בתשובה.

המאמרים הבאים