תיעוד השיחות מאפשר לכם להקליט את השיחות של סוכן לאינטראקציה עם נתונים של Conversational Analytics API בטבלה ב-BigQuery בפרויקט שלכם, כדי שתוכלו לבדוק את איכות התשובות, לעקוב אחרי השימוש ולעקוב אחרי העלויות. בכל שלב, היומן מתעד את השאלה של המשתמש, את התשובה של הנציג, את זמן האחזור, את השימוש בטוקנים של המודל ואת המזהים שצריך כדי לקבץ את השלבים לפי נציג, שיחה ומשתמש. השורות נכתבות באמצעות הסכימה של BigQuery Agent Analytics דרך BigQuery Storage Write API (gRPC). כדי להפעיל את הרישום ביומן של סוכן לאינטראקציה עם נתונים שמקורות הנתונים שלו מפנים לטבלאות ב-BigQuery, מגדירים את השדות bigqueryAgentAnalyticsEnabled ו-bigqueryAgentAnalyticsTable. איך מפעילים את יומן השיחות?
מה מתועד ביומן
כל תור שמתועד ביומן כותב כמה שורות של אירועים (events) בטבלת היעד, שבהן מתועד המידע הבא:
השאלה של המשתמש.
התשובה של הנציג: הטקסט, התובנות, ההנחות, הצעות לשאלות המשך, מקורות הציטוטים והשמות של תוצאות הנתונים או התרשימים.
זמן האחזור לכל תור.
שימוש בטוקנים של המודל, גרסת המודל והסיבה לסיום (למה המודל הפסיק ליצור טוקנים) לכל קריאה למודל.
מזהה הסוכן לאינטראקציה עם נתונים ומזהה השיחה (לצ'אט עם הפניה לשיחה), כדי שתוכלו לנתח כמה סוכנים בטבלה אחת.
מזהה משתמש. למידע נוסף על מזהי משתמשים, ראו זהות משתמש.
פרטי הסטטוס והשגיאה.
מה לא מתועד ביומן
הרישום ביומן של השיחות לא מתעד את הדברים הבאים:
שאילתות ה-SQL שהנציג מריץ: היומן מכיל את התשובה הסופית ואת השמות של תוצאות הנתונים והתרשימים שאליהם מפנים, אבל לא את השאילתות שיצרו אותם. החריג היחיד הוא אם המשתמש מבקש במפורש מהסוכן להציג או להסביר את ה-SQL. במקרה כזה, ה-SQL יכול להופיע בטקסט של התשובה.
קריאות ה-API לכלי של הסוכן: כל קריאה למודל כותבת שורה אחת ב-
LLM_RESPONSE, כולל קריאות שבהן המודל מחליט להפעיל כלי. לפני שהשורה נכתבת, הפלט של המודל מוסר, כולל השם והארגומנטים של כל כלי שהוא קרא לו. רק השימוש בטוקנים, גרסת המודל והסיבה לסיום נשמרים.משוב מהמשתמשים: משוב מסוג לייק או דיסלייק לא נרשם ביומן.
חלק מהשיחות לא מתועדות בכלל, כמו קריאות ל-API ללא שמירת מצב (stateless) בלי סוכן לאינטראקציה עם נתונים. מידע נוסף על פלטפורמות שיחה לא נתמכות מופיע בקטע מגבלות.
איך פועל הרישום ביומן של השיחות
כשמשתמש מתכתב בצ'אט עם סוכן לאינטראקציה עם נתונים שמופעל בו רישום שיחות ביומן, ניתוח השיחות מעבד כל שלב בשיחה לפי השלבים הבאים:
הגדרה: בעלי הנציג מפעילים את יומן השיחות ומציינים את שם הטבלה וקבוצת הנתונים הקיימת של היעד בפרויקט של הנציג באמצעות Conversational Analytics API.
שאלה: משתמש שולח שאלה לסוכן. אם אתם קוראים ל-Conversational Analytics API מהאפליקציה שלכם, אתם אחראים ליידע את המשתמשים. משתמשים שמתכתבים בצ'אט עם הסוכן ב-BigQuery Studio רואים הודעה שהשיחות שלהם מתועדות ביומן.
בדיקת פרטיות: לפני שהנציג מתחיל לעבוד על התור, בדיקת פרטיות קוראת את המטא-נתונים של טבלאות מקורות הידע של הנציג (מקורות הנתונים שלו ב-BigQuery) באמצעות פרטי הכניסה של המשתמש בצ'אט. הבדיקה הזו מוודאת שאף אחת מהטבלאות לא משתמשת באבטחה ברמת השורה (מדיניות גישה לשורות), באבטחה ברמת העמודה (תגי מדיניות) או בהסתרת מידע דינמית. אם הבדיקה מוצאת מדיניות או לא מצליחה לאשר שאין מדיניות, התור לא מתועד ביומן, והנציג עדיין עונה על השאלה של המשתמש.
תשובה: הנציג עונה למשתמש כרגיל.
כתיבה: סוכן השירות של Conversational Analytics API בפרויקט (
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) כותב את שורות היומן בטבלת היעד באמצעות Storage Write API (gRPC). בפעם הראשונה שבה נרשם תור, סוכן השירות יוצר את הטבלה אם היא עדיין לא קיימת.שאילתה: השורות בדרך כלל מופיעות כמה שניות אחרי שהתשובה מוכנה. אנחנו לא מתחייבים לגבי זמן האספקה.
שגיאות רישום ביומן אף פעם לא גורמות לכישלון של תור, ובדיקת הפרטיות והכתיבה ביומן יכולות להוסיף זמן אחזור. אם חסרה הרשאה במערך הנתונים של היומן, אם מערך הנתונים לא קיים או אם המכסה מוצתה, בקשת הצ'אט או הקריאה ל-API לא נכשלות. בניתוח נתוני השיחות לא מדווח על כשלים ברישום ביומן בממשק הצ'אט, בתגובה מה-API או ב-Cloud Logging.
פרטיות, משילות מידע (data governance) ואבטחה
כשמפעילים את תיעוד השיחות בנציג, חשוב לבדוק איך ההודעות למשתמשי הקצה, הגישה לנתונים, ההצפנה, אמצעי הבקרה ברשת ויומני הביקורת חלים על היומנים.
הודעות למשתמשי קצה ותוכן שנרשם ביומן
ההודעות והכללים הבאים קובעים מה נרשם ביומן השיחות ומי יכול לראות את הנתונים שנרשמו:
הודעה למשתמשי קצה ב-BigQuery Studio: כשיומן השיחות מופעל לסוכן, המשתמשים שמתכתבים בצ'אט עם הסוכן ב-BigQuery Studio רואים את ההודעה הבאה בכל פעם שיומן השיחות מופעל, כולל במסך השיחה החדשה לפני שהמשתמש שולח את ההנחיה הראשונה:
כל התשובות וההנחיות נשמרות ב-BigQuery, והן גלויות למשתמשים שיש להם הרשאת גישה לקבוצת הנתונים.
תחומי האחריות שלכם כשאתם משתמשים ב-API: אם אתם מפעילים רישום שיחות ביומן (יומן מעקב) בסוכן לאינטראקציה עם נתונים, והסוכן הזה זמין למשתמשי קצה דרך האפליקציה או השילוב שלכם, Google לא יכולה להציג הודעה למשתמשים האלה. אתם אחראים לכל ההודעות, הגילויים הנאותים או ההסכמות שחלים על השיחות המתועדות בהתאם לדין החל ולהסכמים שלכם עם משתמשי הקצה. מידע נוסף זמין במאמר אבטחה, פרטיות, סיכונים ותאימות ב-Conversational Analytics API.
מה היומן מכיל ומי יכול לראות אותו: טבלת היעד מאחסנת את תוכן השאלות והתשובות בהתאם לכללי הפרטיות הבאים:
שאלות ותשובות מלאות: התשובות יכולות לכלול ערכים שמוחזרים ממקורות הידע שלכם. כל מי שיכול לקרוא את טבלת היומן יכול לראות את הנתונים שהנציג החזיר למשתמש, כולל נתונים שהוא לא יכול לקרוא בטבלאות המקור. לתת גישת קריאה למערך הנתונים של היומן רק לאנשים שצריכים לראות את התוכן הזה.
מזהי משתמשים ומיקום הכתיבה: העמודה
user_idמזהה את מי ששאל את השאלה (ראו זהות המשתמש), והשורות נכתבות רק ביעד שהגדרתם בפרויקט של הנציג.טבלאות עם אבטחה ברמת השורה, אבטחה ברמת העמודה או הסתרת נתונים: אם מקורות הידע של הנציג משתמשים באבטחה ברמת השורה (כללי מדיניות גישה לשורות), באבטחה ברמת העמודה (תגי מדיניות) או בהסתרת נתונים דינמית, הפעולות שלו לא מתועדות ביומן. בבדיקת הפרטיות המערכת מדלגת על טבלאות ב-
bigquery-public-dataובוחנת רק את הטבלאות והתצוגות שבחרתם כמקורות ידע, ולא את הטבלאות שמאחורי התצוגה:תצוגה של טבלה שמשתמשת בכללי המדיניות האלה יכולה לעבור את הבדיקה, כך שאפשר לתעד את התורות שלה. לפני שמפעילים את הרישום ביומן, חשוב לוודא שהטבלאות שמאחורי התצוגות לא משתמשות במדיניות גישה לשורות, בתגי מדיניות או בהסתרת נתונים.
אם תוסיפו אחת מהמדיניות האלה לטבלת מקור בשלב מאוחר יותר, שורות שכבר נרשמו ביומן יישארו בטבלת היומן. אם מדיניות השמירה או הפיקוח שלכם אוסרת על שמירת השורות האלה, מחקו אותן.
בקרת גישה, הצפנה ואבטחת רשת
אתם יכולים לנהל את השמירה, הגישה, ההצפנה והאבטחה ההיקפית של יומני השיחות באמצעות ההגדרות הבאות:
שמירה ובקרת גישה במערך הנתונים של היומן: הגדרת שמירה, תפקידים במערך הנתונים, כללי מדיניות של טבלאות ויומני ביקורת לטבלת היעד:
שמירה: Google לא מוחקת שורות ביומן. מגדירים תפוגת מחיצה במערך הנתונים או בטבלה של היומן שתואמת למדיניות (לדוגמה, 90 יום).
הרשאות מינימליות: כדאי להפריד את מערך הנתונים של היומן ממערכי הנתונים האחרים, כדי שסוכן השירות המשותף של Conversational Analytics API לא יוכל לגשת לטבלאות האחרות. לתת למנתחי הנתונים את התפקיד
roles/bigquery.dataViewerבמערך הנתונים של היומן, או לתת להם גישה רק לתצוגות מורשות או למערכי נתונים מורשים.אמצעי בקרה ברמת העמודה וברמת השורה בטבלת היומן: אתם יכולים להחיל תגי מדיניות, הסתרת נתונים או כללי מדיניות גישה לשורות בטבלת היומן עצמה, למשל ב-
contentאו ב-user_id. אמצעי הבקרה האלה בטבלת היומנים לא משפיעים על בדיקת הפרטיות של מקור הידע.רישום ביומן הביקורת: שינויים בהגדרות של הסוכן לאינטראקציה עם נתונים ופעולות בטבלת היומנים מתועדים ביומני הביקורת. מידע נוסף על פעולות שנבדקות
CMEK, VPC Service Controls ומיקום אחסון הנתונים: אמצעי הבקרה הבאים על הצפנה, מתחם אבטחה היקפית ומיקום חלים על תיעוד השיחות:
CMEK: אם מערך הנתונים של היומן משתמש במפתחות Cloud KMS בניהול הלקוח (CMEK), צריך לתת לחשבון השירות של הצפנת BigQuery (
bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) את התפקידroles/cloudkms.cryptoKeyEncrypterDecrypterבמפתח. מפתח CMEK בסוכן לאינטראקציה עם נתונים מצפין את משאב הסוכן, ולא את טבלת היומן (ראו מפתחות הצפנה בניהול הלקוח).VPC Service Controls: אם אתם משתמשים בגבולות גזרה לשירות, צריך לכלול את
geminidataanalytics.googleapis.comוגם אתbigquery.googleapis.comבגבולות הגזרה שמכילים את הפרויקט של הנציג. סוכן השירות כותב לטבלת היומן מתשתית שמנוהלת על ידי Google, כך שאם ההיקף מגביל אתbigquery.googleapis.com, צריך להוסיף כלל תעבורת נתונים נכנסת כמו הכלל הבא. מחליפים אתPROJECT_NUMBERבמספר הפרויקט של הנציג:- ingressFrom: identities: - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com 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_NUMBERמידע נוסף זמין במאמר הגדרת אבטחה היקפית באמצעות VPC Service Controls.
מיקום אחסון הנתונים: שורות היומן והטבלה שנוצרה באופן אוטומטי מאוחסנות במיקום של מערך הנתונים של היומן, שבו חלים כללי המדיניות של הארגון לגבי מיקום המשאבים (
gcp.resourceLocations).
שיוך של סוכן השירות ושל המתקשר
סוכן השירות של Conversational Analytics API, ולא המשתמש בצ'אט, יוצר ומעדכן את טבלת היומן ומוסיף לה שורות. כדי לבצע את הפעולות האלה, סוכן השירות צריך את התפקיד עריכת נתונים ב-BigQuery (roles/bigquery.dataEditor) במערך הנתונים של היומן.
ברשומות של יומני הביקורת של Cloud, השדה authenticationInfo.principalEmail (או authenticationInfo.principalSubject לזהויות מאוחדות) מזהה את חשבון המשתמש שביצע כל פעולה:
יצירת טבלאות ביומן, עדכוני סכימה והוספת שורות: סוכן השירות
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.בקשות להגדרת סוכן לאינטראקציה עם נתונים (
CreateDataAgent,CreateDataAgentSync,UpdateDataAgentו-UpdateDataAgentSync): המשתמש, חשבון השירות או הזהות המאוחדת שקוראים ל-API. כשחלים פרטי כניסה לחשבון שירות שהוקצו לו הרשאות, הרשומות האלה כוללות גם אתauthenticationInfo.serviceAccountDelegationInfo.
פעולות מבוקרות
ב-Cloud Audit Logs מתועדים שינויים בהגדרות של רישום השיחות ביומן ופעולות בטבלת היומנים בשירותים הבאים:
Conversational Analytics API: ה-methods הבאות יוצרות יומני ביקורת ב-
geminidataanalytics.googleapis.com:
CreateDataAgent,CreateDataAgentSync,UpdateDataAgentו-UpdateDataAgentSyncיוצרים יומני ביקורת של פעילות אדמין שמתעדים את השדותbigqueryAgentAnalyticsEnabledו-bigqueryAgentAnalyticsTableשל הסוכן, כולל הפרויקט, מערך הנתונים והטבלה של היעד.
SetAgentOpsObservabilityיוצר יומני ביקורת של פעילות אדמין שמתעדים את השדותdataSourceType,telemetryEnabled,bqaaEnabledו-updateMaskשל הבקשה.
RetrieveAgentOpsObservabilityיוצר יומני בקרת הרשאות גישה לנתונים כשסוג יומן הביקורת התואם שלADMIN_READאוDATA_READמופעל בשבילgeminidataanalytics.googleapis.com.
BigQuery: הפעולות של סוכן השירות בטבלת היומנים והשאילתות שאתם מריצים עליה יוצרות את יומני הביקורת הבאים:
יצירת טבלאות של יומנים ועדכוני סכימה יוצרים יומני ביקורת של פעילות אדמין ב-
bigquery.googleapis.com.הוספת שורות באמצעות Storage Write API (gRPC) יוצרת יומני ביקורת של גישה לנתונים בשביל ה-method
google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows, כולל מטא-נתונים שלTableDataChange(WRITE_API_APPEND_ROWS). ברשומות האלה נעשה שימוש בשם השירותbigquery.googleapis.com, ולא ב-bigquerystorage.googleapis.com. רק ביומני הביקורת של Policy Denied נעשה שימוש ב-bigquerystorage.googleapis.com.שאילתות בטבלת היומן יוצרות יומני ביקורת של גישה לנתונים ב-
bigquery.googleapis.com, כמו רשומות שלJobInsertion,JobChangeו-TableDataRead.
למידע נוסף, קראו את המאמרים רישום ביומן ביקורת של Conversational Analytics API וסקירה כללית על יומני ביקורת ב-BigQuery.
מגבלות
לרישום ביומן של השיחות יש את המגבלות הבאות:
החלונית Preview בעורך הסוכנים של BigQuery Studio לא מתועדת ביומן.
קריאות ל-API ללא שמירת מצב (stateless) בלי סוכן לאינטראקציה עם נתונים לא מתועדות ביומן.
סוכנים שמשתמשים בהיקף חיפוש במקום בטבלאות ספציפיות, או שלא מצהירים על טבלאות ב-BigQuery, לא נרשמים ביומן. סוכנים שמגדירים רק תרשימי מאפיינים ב-BigQuery (בלי טבלאות ב-BigQuery) כמקורות ידע לא מתועדים ביומן.
ה-SQL שנוצר, קריאות ה-API לכלי ואירועי הבקשות או הכלים של ערכת הפיתוח לסוכנים (ADK) (
TOOL_STARTING,TOOL_COMPLETED,TOOL_ERRORו-LLM_REQUEST) לא נרשמים ביומן. רק התשובה והשמות של תוצאות הנתונים והתרשימים שלה נרשמים ביומן. באינטראקציות שנענו ישירות משאילתה מאומתת לא נכתבות שורות ב-LLM_RESPONSE, ואינטראקציות של שאילתות מאומתות שנכשלו לא מתועדות ביומן.משוב ממשתמשים (לייק או דיסלייק) לא נרשם ביומן.
האינטראקציות לא מתועדות ביומן אם מקורות הידע משתמשים במדיניות גישה ברמת השורה, באבטחה ברמת העמודה (תגי מדיניות) או בהסתרת נתונים, כולל כללי מדיניות נתונים שמצורפים ישירות לעמודות. התור לא נרשם ביומן גם אם בדיקת הפרטיות לא יכולה לאמת את כללי המדיניות האלה, למשל אם למשתמש בצ'אט אין הרשאה לבדוק את המטא-נתונים של המדיניות של הטבלה, או אם הבדיקה נכשלה בגלל זמן קצוב לתפוגה. הבדיקה לא עוברת דרך תצוגות לטבלאות שמאחוריהן.
יש תמיכה רק בסוכנים של טבלאות ב-BigQuery. אין תמיכה במקורות נתונים של Looker, Data Studio, AlloyDB ל-PostgreSQL, Spanner ו-Cloud SQL.
מערך הנתונים של היעד כבר צריך להיות קיים באותו פרויקט שבו נמצא הנציג.
שינויים בסכימה של טבלאות קיימות הם רק תוספות. סוג או מצב של עמודה שמתנגשים עם הסכימה הקיימת עוצרים את הכתיבה לטבלה הזו.
כל תור שעומד בדרישות נרשם ביומן בלי הגדרת דגימה. במקום זאת, הדגימה מתבצעת בזמן השאילתה (ראו דגימת שאלות לדוגמה ותשובות בכל הסוכנים לבדיקה).
בעמודה
agentמופיע סוג הסוכן ולא השם המוצג שלו. צריך להשתמש במזהה הסוכן לאינטראקציה עם נתונים שמופיע בעמודהattributes.קריאות ל-API שמשתמשות בחשבון שירות אחד להרבה משתמשי קצה רואות את כתובת האימייל של חשבון השירות הזה בכל שורה.
ערכי טקסט באורך של יותר מ-512,000 תווים (
500 * 1,024) נחתכים עם הסיומת...[TRUNCATED], ואי אפשר לשחזר את החלק שהוסר.הכתיבה מתבצעת כמיטב היכולת עם מספר מוגבל של ניסיונות חוזרים. מהלכים שהכתיבה שלהם נכשלה לא מתועדים ביומן, וניסיונות חוזרים יכולים לפעמים ליצור שורות כפולות (אפשר להשתמש ב-
event_idכדי לבטל כפילויות).הסוכן לא מקבל בירושה את הגדרת הניטור ברמת הפרויקט.
תמחור
בניתוח שיחות אין חיוב נפרד על רישום ביומן של השיחות.
בפרויקט שלכם משלמים את המחירים הרגילים של BigQuery על הטמעת נתונים של BigQuery Storage Write API (gRPC), אחסון ושאילתות ניתוח. הטמעת BigQuery Storage Write API (gRPC) כוללת שימוש חינמי בנפח של 2TiB בחודש לכל חשבון לחיוב, שמשותף לשימוש ב-Storage Write API (gRPC). כדי לצמצם את מספר הבייטים שנסרקים, כדאי לסנן את השאילתות לפי timestamp. בדיקת הפרטיות לפני ההפעלה קוראת את המטא-נתונים של הטבלה ומריצה שאילתות ללא חיוב.