שימוש ב-BigQuery Agent Analytics

‫BigQuery Agent Analytics הוא פתרון בקוד פתוח שמאפשר לתעד, לנתח ולהמחיש נתונים של אינטראקציות עם נציגים מולטי-מודאליים בקנה מידה נרחב, על ידי העברה בסטרימינג של אינטראקציות גולמיות עם נציגים – כמו בקשות, תשובות, קריאות לכלים ושגיאות – ישירות ל-BigQuery. הפתרון הזה מאפשר לכם לבצע הערכות מבוססות-AI, לשפר את ההנחיות לסוכנים ולשלוף זיכרון לטווח ארוך כדי לשפר את האינטראקציות בעתיד. ‫BigQuery Agent Analytics נתמך ב-Agent Development Kit (ADK) וב-LangGraph (גרסת טרום-השקה).

ארכיטקטורה

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

זרימת הנתונים מורכבת מהשלבים הבאים:

  1. צילום. משתמשים בפלאגין רישום ביומן ב-ADK או בגורם מטפל בקריאה חוזרת ב-LangGraph כדי ליירט ולתעד אירועי אינטראקציה של סוכנים.
  2. סטרימינג. אירועי אינטראקציה נשלחים ל-BigQuery דרך Storage Write API ‏ (gRPC). אם אין סכימה סטנדרטית, הנציג יוצר אחת באופן אוטומטי.
  3. צריכה. לנתח ולהעריך את נתוני סוכן Logging שנרשמו ביומן. אתם יכולים להריץ שאילתות על נתונים גולמיים באמצעות SQL, לעקוב אחרי מדדים בלוחות בקרה בהתאמה אישית או להשתמש ב- BigQuery Agent Analytics SDK כדי לשחזר ולהעריך עקבות מורכבים של ביצוע סוכנים בכמה שלבים.

דיאגרמה שמראה איך נתוני הפעילות של הסוכן זורמים ממסגרות תזמור ל-BigQuery לצורך ניתוח נתונים.

היתרונות של ניתוח נתונים של סוכנים

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

בחירת ספרייה לכל שלב בתהליך העבודה

ל-BigQuery Agent Analytics יש שני שילובי רישום ביומן ו-Analytics SDK אחד לניתוח. השילובים של הרישום ביומן וה-Analytics SDK משמשים בשלבים שונים בתהליך העבודה:

  • רישום אירועי סוכן Logging ביומן: משתמשים בשילוב של רישום ביומן עבור framework הסוכן, פלאגין ADK או גורם מטפל בקריאה חוזרת של LangGraph ו-LangChain. צריך רק שילוב אחד של רישום ביומן, ולא צריך את ה-Analytics SDK כדי לתעד אירועים. במאמר דרכים לתעד נתונים ביומן הפעילות של הסוכן מוסבר איך עושים את זה במסגרות אחרות, או איך מפעילים רישום שיחות מובנה עבור סוכנים לאינטראקציה עם נתונים לניתוח נתונים בשיחה.
  • ניתוח אירועי סוכן: משתמשים ב-BigQuery Agent Analytics SDK כדי לשלוח שאילתות, לשחזר ולהעריך את האירועים שנרשמו ביומן. אפשר גם לנתח את האירועים באמצעות שאילתות SQL ומרכזי בקרה.

בתרשים הבא מוצג באיזו ספרייה להשתמש בכל שלב בתהליך העבודה:

הפלאגין של ADK או הגורם המטפל בקריאה חוזרת של LangGraph ו-LangChain מעבירים אירועי סוכנים בסטרימינג לטבלת אירועים ב-BigQuery, שאותה אתם מנתחים באמצעות BigQuery Agent Analytics SDK, שאילתות SQL או מרכזי בקרה.

בטבלה הבאה מתוארים כל שילוב של רישום ביומן ו-SDK לניתוח:

שלב בתהליך העבודה שילוב או SDK חבילה ונקודת כניסה מתי כדאי להשתמש בזה?
אירועים ביומן של סוכן Logging הפלאגין של BigQuery Agent Analytics ב-ADK

חבילת Python של google-adk[bigquery-analytics]

כיתה אחת (BigQueryAgentAnalyticsPlugin)

לשפות אחרות, כמו Java, אפשר לעיין ב מדריך לפלאגין של ADK.

 אפשר להשתמש בסוכן ADK כדי להעביר בסטרימינג בקשות ל-LLM, קריאות API לכלים ואירועים של תהליכי עבודה ל-BigQuery.
אירועים ביומן של Agent גורם מטפל בקריאה חוזרת (callback) של LangGraph ו-LangChain BigQuery (גרסת טרום-השקה)

חבילת Python של langchain-google-community[bigquery]

כיתה אחת (BigQueryCallbackHandler)

 אפשר להשתמש ב-LangGraph או ב-LangChain כדי להעביר אירועי הפעלה של סוכנים ל-BigQuery.
ניתוח אירועים של נציגים BigQuery Agent Analytics SDK

חבילת Python של bigquery-agent-analytics

‫Client ו-GraderPipeline כיתות

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

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

כדי לתעד את נתוני הטלמטריה של האינטראקציות של הנציג (בקשות, תשובות, קריאות לכלים ויומני שגיאות) באופן מקורי ב-BigQuery, אתם יכולים לתעד את נתוני האירועים בכמה דרכים:

  • פלאגינים של Orchestration Framework: משתמשים בפלאגינים סטנדרטיים של רישום ביומן שסופקו על ידי ערכת הכלים של Agent Orchestration. לדוגמה, ה-BigQueryAgentAnalyticsPlugin ב-ADK מתחבר ל-agent runner כדי ליירט, להעביר לסדרה ולהעביר בסטרימינג אירועים באופן אוטומטי.
  • גורמים מטפלים בקריאה חוזרת (callback) של Framework: שילוב של קריאות חוזרות סטנדרטיות בסביבות נפוצות של נציגים. לדוגמה, אתם יכולים להשתמש ב-BigQueryCallbackHandler מהחבילה langchain-google-community ב-LangGraph וב-LangChain כדי ליירט עקבות ולהעביר אותם ל-BigQuery.
  • הטמעה ישירה של API: במסגרות מותאמות אישית או קנייניות, משתמשים בGoogle Cloud ספריות הלקוח כדי להעביר אירועים מובְנים ישירות לטבלת האירועים באמצעות Storage Write API ‏ (gRPC).
  • סוכני נתונים של ניתוח שיחות: מפעילים רישום מובנה של שיחות כשמגדירים את ההגדרות של סוכן נתונים ב-BigQuery ב-BigQuery Studio או באמצעות Conversational Analytics API, כדי להעביר באופן אוטומטי אירועי שיחות לטבלת יעד ב-BigQuery ולנתח את יומני השיחות.

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

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

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

  • שאילתות SQL ישירות: מריצים שאילתות בהתאמה אישית ב-BigQuery כדי לחשב מדדים כמו צריכת טוקנים וזמן אחזור של ביצוע. אפשר גם להשתמש ב-AI.GENERATE כדי לנתח באופן אוטומטי את שורש הבעיה של שגיאות, או לבצע איחודים עם טבלאות עסקיות כדי למדוד את ההשפעה על העסק.
  • מרכזי בקרה אינטראקטיביים: אפשר לחבר כלים להצגה חזותית כמו Data Studio לתצוגות מוגדרות מראש או מותאמות אישית של BigQuery, כדי לעקוב אחרי תקינות הנציג, שיעורי השגיאות ומגמות השימוש לאורך זמן. לקוחות Looker יכולים גם להשתמש בתבנית מוכנה מראש של מרכז בקרה ב-BigQuery Agent Analytics (בלוק של Looker) מ-Looker Marketplace.
  • מסמכי Jupyter: בדיקה והתנסות בנתוני היומן באמצעות ספריות Python,‏ pandas או BigFrames בסביבות אינטראקטיביות.
  • ‫Python SDK: באופן פרוגרמטי, שולחים שאילתות, משחזרים ובודקים את עקבות הביצוע של הנציג ישירות בקוד האפליקציה או בצינורות עיבוד נתונים אוטומטיים להערכה.

דוגמאות לעבודה עם נתוני יומן הפעילות של הסוכן

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

מדדי ניראות ומדדים תפעוליים

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

הערכת תפקוד הסוכנים וניתוח איכות

  • מדרגים את השיחות ומודדים את דירוג הנציג לאורך זמן באמצעות הפונקציה AI.SCORE.
  • מזהים אשכולות של שיחות שבהן הנציג לא הצליח לעזור למשתמשים באמצעות שאילתת SQL עם חיפוש וקטורי, ואז משווים אותם לכוונה המקורית של המשתמש. כך אפשר לזהות פערים בכלים או במאגר הידע של הנציג.

תובנות עסקיות והקשר

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

דוגמאות נוספות מופיעות במאמר מתכונים לשאילתות.

שימוש ב-Jupyter Notebook כדי לעבוד עם יומני פעילות של סוכנים

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

שימוש ב-BigQuery Agent Analytics SDK

BigQuery Agent Analytics SDK היא ספריית Python בקוד פתוח שמספקת שכבת צריכה והערכה ליכולת התבוננות לעומק בסוכנים לטווח ארוך. לוחות בקרה ו-notebooks הם כלים מצוינים לניתוח אד הוק, וה-SDK מאפשר לנתח ולבדוק באופן שיטתי את ההתנהגות של הנציגים בקנה מידה נרחב.

מה אפשר לעשות עם ה-SDK

אתם יכולים לבצע את המשימות הבאות באמצעות BigQuery Agent Analytics SDK. דוגמאות מפורטות לניתוח נתוני יומן מופיעות במאגר GitHub של ה-SDK.

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

תיעוד וניתוח של פעילות הסוכן

ערכת ה-SDK קוראת ומעריכה אירועים ששילוב הרישום ביומן כותב. תהליך עבודה אופייני כולל את השלבים הבאים:

  1. תיעוד אינטראקציות: במסגרת ניהול הסוכנים, הוסיפו שילוב של רישום ביומן, כמו BigQueryAgentAnalyticsPlugin ב-ADK או BigQueryCallbackHandler ב-LangGraph. כשמשתמשים יוצרים אינטראקציה עם הנציג, האינטגרציה מעבירה את האירועים באופן אסינכרוני ל-BigQuery באמצעות Storage Write API‏ (gRPC) עם תפוקה גבוהה. בשלב הזה לא צריך את ה-SDK.

  2. מאתחלים את הלקוח: מתחברים למערך הנתונים של היומן מ-Python SDK:

    from google.cloud import bigquery
from bigquery_agent_analytics import Client

client = Client(
    project_id="YOUR_PROJECT_ID",
    dataset_id="YOUR_DATASET_ID",
    table_id="agent_events",
)

    קטע הקוד משתמש ברכיבים הבאים:

    • ‫client: המכונה הראשית של Client שמנתבת שאילתות באופן פרוגרמטי ומנהלת חיבורים פעילים למסד הנתונים.
    • ‫project_id: מזהה הפרויקט ב- Google Cloud שמכיל את מערך הנתונים של היעד.
    • ‫dataset_id: השם של מערך הנתונים ב-BigQuery שבו מאוחסנים היומנים.
    • ‫table_id: הטבלה שבה נשמרים האירועים שנרשמו ביומן (כברירת מחדל, agent_events). הערך הזה צריך להיות זהה לטבלה שאליה נכתב שילוב הרישום ביומן. לדוגמה, BigQueryCallbackHandler ב-langchain-google-community בגרסה 4.0.0 ובגרסאות קודמות כותב ל-agent_events_v2 כברירת מחדל.

  3. שחזור מעקב אחרי סשן: אחזור סשן ספציפי של שיחה כדי להציג ולבדוק את רצף האירועים המדויק:

    trace = client.get_session_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    קטע הקוד משתמש ברכיבים הבאים:

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

  4. הפעלת הערכות אוטומטיות: דירוג פרוגרמטי של מסלולי הסשנים או בדיקת רגרסיה מול חבילת מקרים לבדיקה.

    from bigquery_agent_analytics import (
    LLMAsJudge,
    TraceFilter,
)

# Run semantic evaluations across target sessions
evaluator = LLMAsJudge.correctness()
filters = TraceFilter(session_ids=["session_1", "session_2"])

report = client.evaluate(evaluator, filters=filters)
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    קטע הקוד משתמש ברכיבים הבאים:

    • ‫evaluator: מעריך סמנטי (LLMAsJudge) שמשמש לדירוג סשנים (אפשר גם להריץ בדיקות SystemEvaluator מבוססות-כללים או לשלב מעריכים ב-GraderPipeline משוקלל).
    • filters: המכונה של TraceFilter שמציינת את הרשימה של session_ids (או חלון הזמן ומסנני הנציגים) להרצת הערכות באצווה ב-BigQuery.
    • ‫report: אובייקט EvaluationReport שנוצר ומכיל ציונים גולמיים של הסשן, סיכומי מדדים ומשוב מהמדרג האוטומטי.

שילוב BigQuery Agent Analytics בתהליך העבודה

כדי לשלב את BigQuery Agent Analytics בתהליך העבודה:

  1. מגדירים את שילוב הרישום ביומן של Agent Framework:

  2. מנתחים את האירועים שנרשמו ביומן באמצעות BigQuery Agent Analytics SDK, הדוגמה ל-Colab Notebook או המתכונים לשאילתות SQL.

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