סקירה כללית על תיעוד השיחות

בעזרת יומן השיחות של ניתוח נתוני השיחות, אתם יכולים לתעד את השיחות של סוכן הנתונים בטבלה ב-BigQuery בפרויקט שלכם, כדי לבדוק את איכות התשובות, לעקוב אחרי השימוש ולעקוב אחרי העלויות של כל הסוכנים לניתוח נתוני שיחות. בכל שלב, היומן מתעד את השאלה של המשתמש, את התשובה של הנציג, את זמן האחזור, את השימוש בטוקנים של המודל ואת המזהים שצריך כדי לקבץ את השלבים לפי נציג, שיחה ומשתמש. השורות נכתבות באמצעות הסכימה של BigQuery Agent Analytics דרך BigQuery Storage Write API (gRPC)‎.

מה מתועד ביומן

כל תור שמתועד ביומן כותב כמה שורות של אירועים (events) בטבלת היעד, שמתעדות את המידע הבא:

• השאלה של המשתמש.

• התשובה של הנציג: הטקסט, התובנות, ההנחות, ההצעות לשאלות המשך, המקורות לציטוטים והשמות של תוצאות הנתונים או התרשימים.

• זמן האחזור לכל פנייה.

• השימוש בטוקנים של המודל, גרסת המודל והסיבה לסיום (למה המודל הפסיק ליצור טוקנים) לכל קריאה למודל.

• מזהה סוכן הנתונים ומזהה השיחה, כדי שתוכלו לנתח כמה סוכנים בטבלה אחת.

• מזהה משתמש. מידע נוסף על מזהי משתמשים זמין במאמר זהות משתמש.

• פרטי הסטטוס והשגיאה.

מה לא מתועד ביומן

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

• שאילתות ה-SQL שהנציג מריץ: היומן מכיל את התשובה הסופית ואת השמות של תוצאות הנתונים והתרשימים שאליהם מפנים, אבל לא את השאילתות שיצרו אותם. החריג היחיד הוא כשמשתמש מבקש במפורש מהסוכן להציג או להסביר את ה-SQL. במקרה כזה, ה-SQL יכול להופיע בטקסט של התשובה.

• קריאות לכלים של הנציג: כל קריאה למודל כותבת שורה אחת ב-LLM_RESPONSE, כולל קריאות שבהן המודל מחליט להפעיל כלי. לפני שהשורה נכתבת, הפלט של המודל מוסר, כולל השם והארגומנטים של כל כלי שהוא קרא לו. רק השימוש בטוקנים, גרסת המודל והסיבה לסיום נשמרים.

• משוב מהמשתמשים: משוב מסוג לייק או דיסלייק לא נרשם ביומן.

חלק מהשיחות לא מתועדות בכלל, כמו שיחות בחלונית התצוגה המקדימה של BigQuery Studio. מידע נוסף על פלטפורמות שיחה שלא נתמכות מופיע בקטע מגבלות.

איך פועל הרישום ביומן של השיחות

כשמשתמש מתכתב בצ'אט עם סוכן נתונים שמופעל בו תיעוד שיחות, ניתוח השיחות מעבד כל שלב בשיחה לפי השלבים הבאים:

1. הגדרה: בעלי הסוכן מפעילים את יומן השיחות ובוחרים שם קיים של מערך נתונים וטבלה בפרויקט של הסוכן ב-BigQuery Studio.

2. שאלה: משתמש שולח שאלה לסוכן. ב-BigQuery Studio, המשתמשים רואים הודעה שהשיחות שלהם מתועדות ביומן.

3. בדיקת פרטיות: לפני שהנציג מתחיל לעבוד על התור, בדיקת פרטיות קוראת את המטא-נתונים של טבלאות מקורות הידע של הנציג באמצעות פרטי הכניסה של המשתמש בצ'אט. הבדיקה הזו מאשרת שאף אחת מהטבלאות לא משתמשת באבטחה ברמת השורה (כללי מדיניות גישה לשורות), באבטחה ברמת העמודה (תגי מדיניות) או בהסתרת מידע דינמית. אם הבדיקה מוצאת מדיניות או לא מצליחה לאשר שאין מדיניות, הסבב לא מתועד ביומן, והנציג עדיין עונה על השאלה של המשתמש.

4. תשובה: הנציג עונה למשתמש כרגיל.

5. כתיבה: סוכן השירות של Conversational Analytics API בפרויקט (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.iam.gserviceaccount.com) כותב את שורות היומן בטבלת היעד באמצעות Storage Write API ‏ (gRPC). בפנייה הראשונה שנרשמת ביומן, סוכן השירות יוצר את הטבלה אם היא עדיין לא קיימת.

6. שאילתה: השורות בדרך כלל מופיעות כמה שניות אחרי שהתשובה מוכנה. אנחנו לא מתחייבים לגבי זמן האספקה.

שגיאות רישום ביומן אף פעם לא גורמות לכישלון של תור, ובדיקת הפרטיות והכתיבה ביומן יכולות להוסיף זמן אחזור. אם חסרה הרשאה במערך הנתונים של היומן, אם מערך הנתונים לא קיים או אם המכסה מוצתה, בקשת הצ'אט לא תיכשל. הכלי לניתוח שיחות לא מדווח על כשלים ברישום ביומן בממשק הצ'אט או ב-Cloud Logging.

פרטיות, משילות מידע ואבטחה

כשמפעילים את תיעוד השיחות של נציג, חשוב לבדוק איך ההודעות למשתמשי הקצה, הגישה לנתונים, ההצפנה ואמצעי הבקרה ברשת חלים על היומנים.

הודעות למשתמשי קצה ותוכן מתועד

ההודעות והכללים הבאים קובעים מה נרשם ביומן השיחות ומי יכול לראות את הנתונים שנרשמו:

• הודעה למשתמשי קצה ב-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. אמצעי הבקרה האלה בטבלת היומנים לא משפיעים על בדיקת הפרטיות של מקור הידע.

  • רישום ביומן הביקורת: שינויים בסוכן הנתונים מתועדים ביומני הביקורת של פעילות האדמין. ביומני הביקורת של BigQuery, יצירת טבלאות ועדכוני מטא-נתונים על ידי סוכן השירות מתועדים ב-bigquery.googleapis.com, והוספת שורות באמצעות Storage Write API ‏ (gRPC) מתועדת ב-bigquerystorage.googleapis.com.

• ‫CMEK,‏ VPC Service Controls ומיקום אחסון הנתונים: אמצעי הבקרה הבאים על הצפנה, מתחם אבטחה היקפית ומיקום חלים על תיעוד השיחות:

  • ‫CMEK: אם מערך הנתונים של היומן משתמש במפתחות Cloud KMS בניהול הלקוח (CMEK), צריך לתת לחשבון השירות של הצפנת BigQuery‏ (bq-PROJECT_NUMBER@bigquery-encryption.s3ns-system.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.s3ns-system.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).

מגבלות

לרישום ביומן של השיחות יש את המגבלות הבאות:

• החלונית Preview בעורך הסוכנים של BigQuery Studio לא מתועדת ביומן.

• שיחות ישירות בלי סוכן נתונים לא מתועדות.

• סוכנים שמשתמשים בהיקף חיפוש במקום בטבלאות ספציפיות, או שלא מצהירים על טבלאות ב-BigQuery, לא מתועדים ביומן. לא מתבצע רישום ביומן של נציגים שמגדירים תרשימי נכסים ב-BigQuery כמקורות ידע.

• ה-SQL שנוצר, קריאות הכלים ואירועי הבקשות או הכלים של ערכת הפיתוח לסוכנים (ADK) (TOOL_STARTING,‏ TOOL_COMPLETED,‏ TOOL_ERROR ו-LLM_REQUEST) לא נרשמים ביומן. רק התשובה והשמות של תוצאות הנתונים והתרשימים שלה נרשמים ביומן. פניות שנענו ישירות משאילתה מאומתת לא כותבות שורות ב-LLM_RESPONSE, ופניות של שאילתות מאומתות שנכשלו לא מתועדות ביומן.

• משוב ממשתמשים באמצעות סימון לייק או דיסלייק לא נרשם ביומן.

• האינטראקציות לא מתועדות אם מקורות הידע משתמשים במדיניות גישה ברמת השורה, באבטחה ברמת העמודה (תגי מדיניות) או בהסתרת נתונים, או אם לא ניתן להשלים את בדיקת הפרטיות. הבדיקה לא עוברת על תצוגות של הטבלאות שמאחוריהן.

• אפשר להשתמש רק בסוכנים של טבלאות ב-BigQuery. אי אפשר להשתמש במקורות נתונים מ-Looker, מ-Data Studio, מ-AlloyDB, מ-Spanner ומ-Cloud SQL.

• מערך הנתונים של היעד כבר צריך להיות קיים באותו פרויקט שבו נמצא הנציג.

• שינויים בסכימה של טבלאות קיימות הם רק תוספות. סוג או מצב של עמודה שמתנגשים עם הסכימה הקיימת עוצרים את הכתיבה לטבלה הזו.

• כל תור מתאים מתועד ביומן בלי הגדרת דגימה. במקום זאת, הדגימה מתבצעת בזמן השאילתה (ראו דגימת שאלות לדוגמה ותשובות בכל הסוכנים לבדיקה).

• בעמודה agent מופיע סוג הסוכן ולא השם המוצג שלו. צריך להשתמש במזהה של סוכן הנתונים ב-attributes.

• אם משתמשים בחשבון שירות אחד להרבה משתמשי קצה, כתובת האימייל של חשבון השירות הזה תופיע בכל שורה.

• ערכי טקסט עם יותר מ-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. בדיקת הפרטיות לפני ההפעלה קוראת את המטא-נתונים של הטבלה ומריצה שאילתות הרצה (dry run) ללא תשלום.

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

• הפעלת הרישום ביומן של השיחות בסוכן נתונים.

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

• ניתוח יומני שיחות.