איסוף והצגה של הנחיות ותשובות מולטי-מודאליות

אתם יכולים להגדיר סוכני AI שנבנו באמצעות המסגרת של הערכה לפיתוח סוכנים (ADK) או סוכני LangGraph ReAct כדי לשלוח הנחיות ותשובות מולטימודאליות ל Google Cloud פרויקט. איסוף של מדיה מולטימודלית מאפשר לכם לבדוק שיחות ב-Cloud Trace, לנתח נתונים של הנחיות ב-BigQuery ולהעריך את ביצועי המודל באמצעות Vertex AI ו-Colaboratory.

סוגי המדיה שאפשר לאסוף

אפשר לאסוף את סוגי המדיה הבאים:

• אודיו.
• מסמכים.
• תמונות Google
• טקסט פשוט וטקסט בפורמט Markdown.
• סרטון.

פרומפטים ותשובות יכולים לכלול תוכן מוטמע וקישורים. הקישורים יכולים להפנות למשאבים ציבוריים או לקטגוריות של Cloud Storage.

איפה נשמרים הפרומפטים והתשובות

כשאפליקציה מבוססת-סוכן יוצרת הנחיות או תגובות או מקבלת אותן, ה-SDK שבו האפליקציה משתמשת מפעיל את OpenTelemetry instrumentation. הכלי הזה מעצב את ההנחיות והתשובות, ואת הנתונים המולטי-מודאליים שהם עשויים להכיל, בהתאם לגרסה 1.37.0 של המוסכמות הסמנטיות של OpenTelemetry GenAI. יש תמיכה גם בגרסאות גבוהות יותר.

לאחר מכן, כלי המדידה של OpenTelemetry מבצע את הפעולות הבאות:

• הוא יוצר מזהי אובייקטים לפרומפטים ולנתוני התשובות, ואז כותב את הנתונים האלה בקטגוריה של Cloud Storage. הערכים בקטגוריה של Cloud Storage נשמרים בפורמט JSON Lines.

• הוא יוצר מזהי אובייקטים לפרומפטים ולנתוני התשובות, ואז כותב את התוכן המלא של הפרומפטים והתשובות של משתמשי הקצה בקטגוריה של Cloud Storage בפורמט JSON Lines. לפרטים על בקרת גישה או מחיקת נתונים, אפשר לעיין במסמכי Cloud Storage. כדי לנהל מידע אישי רגיש בפרומפטים ובתשובות, אפשר להשתמש ב-Model Armor וב-Sensitive Data Protection.

• הוא שולח נתוני יומן ומעקב אל Google Cloud הפרויקט שלכם, שבו שירותי הרישום ביומן והמעקב קולטים ומאחסנים את הנתונים. המוסכמות הסמנטיות של OpenTelemetry קובעות הרבה מהמאפיינים והשדות שמצורפים לרשומות ביומן או לטווחים של מעקב.

  כש-OpenTelemetry יוצרת אובייקטים של קטגוריות Cloud Storage, היא גם כותבת רשומה ביומן שמכילה הפניות לאובייקטים האלה. בדוגמה הבאה מוצג חלק מרשומה ביומן שכוללת הפניות לאובייקטים:

  {
    ...
    "labels": {
      "gen_ai.system": "vertex_ai",
      "event.name": "gen_ai.client.inference.operation.details",
      "gen_ai.output.messages_ref": "gs://my-bucket/eso9aP7NA_GX2PgPkrOi-Qg_output.jsonl",
      "gen_ai.system_instructions_ref": "gs://my-bucket/eso9aP7NA_GX2PgPkrOi-Qg_system_instructions.jsonl",
      "gen_ai.input.messages_ref": "gs://my-bucket/eso9aP7NA_GX2PgPkrOi-Qg_input.jsonl"
    },
    "logName": "projects/my-project/logs/gen_ai.client.inference.operation.details",
    "trace": "projects/my-project/traces/963761020fc7713e4590cad89ad03229",
    "spanId": "1234512345123451",
    ...
  }
  

  בדוגמה של הרשומה ביומן, שימו לב לפרטים הבאים:

  • התווית "event.name": "gen_ai.client.inference.operation.details" מציינת שרשומת היומן מכילה הפניות לאובייקטים של Cloud Storage.
  • התוויות שהמפתחות שלהן כוללים gen_ai מפנות כל אחת לאובייקט בקטגוריה של Cloud Storage.
  • כל הרשומות ביומן שמכילות הפניות לאובייקטים נכתבות לאותו יומן שנקרא projects/my-project/logs/gen_ai.client.inference.operation.details.

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

איסוף פרומפטים ותשובות מולטי-מודאליים

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

כדי לאסוף ולהציג פרומפטים מולטי-מודאליים ותשובות מאפליקציה:

1. מגדירים את הפרויקט:

   1. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

   2. מפעילים את ממשקי ה-API של Vertex AI,‏ Cloud Storage,‏ Telemetry,‏ Cloud Logging ו-Cloud Trace, אם חלק מהם עדיין לא מופעלים.

      תפקידים שנדרשים להפעלת ממשקי API

      כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

      הפעלת ממשקי ה-API

   3. מוודאים שיש לכם קטגוריה של Cloud Storage. במידת הצורך, יוצרים קטגוריה של Cloud Storage.

      מה אתם יכולים לעשות?

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

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

      • מגדירים את תקופת השמירה של הקטגוריה ב-Cloud Storage כך שתהיה זהה לתקופת השמירה של קטגוריית היומנים שבה נשמרות הרשומות ביומן. תקופת השמירה של נתוני היומן היא 30 יום כברירת מחדל. במאמר נעילת קטגוריות מוסבר איך מגדירים את תקופת השמירה של קטגוריה ב-Cloud Storage.

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

      חשוב: צריך להקצות את התפקידים האלה לחשבון השירות שבו האפליקציה משתמשת, ולא לחשבון המשתמש. אם לא מקצים את התפקידים לחשבון המשתמש הנכון, יכול להיות שיופיעו שגיאות הרשאה.
      • Storage Object User (roles/storage.objectUser) בקטגוריית האחסון
      • כתיבה ביומן (roles/logging.logWriter) בפרויקט
      • כותב מדדי מעקב (roles/monitoring.metricWriter) בפרויקט
      • ‫Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) בפרויקט

      התפקיד 'Storage Object User' כולל את ההרשאה storage.objects.create. ההרשאה הזו מאפשרת לאפליקציה לכתוב אובייקטים בקטגוריה שלכם ב-Cloud Storage. באובייקטים האלה מאוחסנים הפרומפטים והתשובות שהאפליקציה שלכם יוצרת או מקבלת. מידע נוסף זמין במאמר הגדרה וניהול של מדיניות IAM בדליים.

2. מגדירים את ה-SDK:

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

      ADK

      google-adk>=1.16.0
      opentelemetry-instrumentation-google-genai>=0.4b0
      fsspec[gcs]==2025.10.0
      

      LangGraph

      opentelemetry-instrumentation-vertexai>=2.2b0
      opentelemetry-instrumentation-google-genai>=0.4b0
      fsspec[gcs]==2025.10.0
      

      לא כל הגרסאות של fsspec תומכות באיסוף של הנחיות ותשובות. ידוע שהגרסה שמופיעה ברשימה תומכת בתכונה הזו. אפשר גם לבדוק את הדוגמה כדי לראות אם אפשר להשתמש בגרסה מאוחרת יותר.

   2. אם אתם משתמשים ב-ADK, צריך לעדכן את הקריאה של האפליקציה כדי להפעיל את הדגל otel_to_cloud:

      • אם אתם משתמשים ב-CLI של ADK, מריצים את הפקודה הבאה:

        adk web --otel_to_cloud  [other options]
        

      • אחרת, מעבירים את הדגל כשיוצרים את אפליקציית FastAPI:

        get_fast_api_app(..., otel_to_cloud=True)
        

   3. מגדירים את משתני הסביבה הבאים:

      • מנחים את OpenTelemetry לעצב אובייקטים של Cloud Storage כ-JSON Lines.

        OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
        

      • אפשר להנחות את OpenTelemetry להעלות נתונים של הנחיות ותשובות במקום להטמיע את התוכן הזה בטווחים של מעקבים. הפניות לאובייקטים שהועלו נכללות ברשומה ביומן.

        OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
        

      • הוראה ל-OpenTelemetry להשתמש במוסכמות הסמנטיות העדכניות ביותר עבור AI גנרטיבי.

        OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
        

      • אופציונלי: אפשר להנחות את OpenTelemetry לא לצרף תוכן של הודעות כמאפיינים ב-spans.

        OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='NO_CONTENT'
        

        אין צורך להגדיר את משתנה הסביבה הקודם. עם זאת, אם אתם עושים את זה, מומלץ להגדיר את האפשרות NO_CONTENT. למידע על הערכים המותרים, אפשר לעיין במאמר genai/types.py.

      • מציינים את הנתיב לאובייקטים:

        OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET/PATH'
        

        בביטוי הקודם, STORAGE_BUCKET מתייחס לשם הקטגוריה של Cloud Storage. ‫PATH הוא הנתיב שבו מאוחסנים האובייקטים.

      • בסוכני LangGraph ReAct, צריך להנחות את OpenTelemetry לתעד באופן אוטומטי נתוני יומן:

        OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'
        

      • יכול להיות שתצטרכו להגדיר משתני סביבה אחרים. לדוגמה, אם אתם פורסים ל-Gemini Enterprise Agent Platform, כדאי להגדיר גם את משתנה הסביבה הבא.

        GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
        

הצגת פרומפטים ותשובות מולטי-מודאליים

כדי לקבוע את ההנחיות והתשובות שיוצגו לטווח, Cloud Trace שולח שאילתות לקריאת נתוני יומן ולקריאת נתונים שמאוחסנים בקטגוריה של Cloud Storage. התפקידים שלכם בניהול הזהויות והרשאות הגישה (IAM) במשאבים שנשלחה לגביהם שאילתה קובעים אם הנתונים יוחזרו. במקרים מסוימים, יכול להיות שתופיע הודעת שגיאה. לדוגמה, אם אין לכם הרשאה לקרוא נתונים מקטגוריה של Cloud Storage, ניסיונות לגשת לנתונים האלה יגרמו לשגיאה של דחיית הרשאה.

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

לדוגמה, בתמונה הבאה אפשר לראות איך ההנחיות והתשובות נראות, ואיך מסוכמים מאפיינים של OpenTelemetry:

לפני שמתחילים

כדי לוודא שלחשבון השירות שהאפליקציה שלכם משתמשת בו יש את ההרשאות הנדרשות להצגת הנחיות ותשובות מרובות-מוֹדָלִיוּת, אתם צריכים לבקש מהאדמין להקצות לחשבון השירות שהאפליקציה שלכם משתמשת בו את תפקידי ה-IAM הבאים בפרויקט:

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

• משתמש Cloud Trace (roles/cloudtrace.user)
• כלי הצפייה ביומנים (roles/logging.viewer)
• צפייה באובייקטים באחסון (roles/storage.objectViewer)

חיפוש טווחי זמן שמכילים פרומפטים ותשובות מולטי-מודאליים

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

1. נכנסים לדף Trace explorer במסוף Google Cloud :

   כניסה אל Trace explorer

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

2. בחלונית Span filter, עוברים לקטע Span name ובוחרים באפשרות generate_content.

   אפשר גם להוסיף את המסנן gen_ai.operation.name: generate_content.

3. בוחרים טווח מהרשימה של הטווחים.

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

הכרת פרומפטים מולטי-מודאליים ותשובות

הכרטיסייה Inputs/Outputs (קלט/פלט) מכילה שני קטעים. בקטע אחד מוצגות ההנחיות והתשובות, ובקטע השני מוצג OpenTelemetry: Attributes. הכרטיסייה הזו מופיעה רק כשפרקי הזמן שנשלחים אל Trace עומדים בדרישות של המוסכמות הסמנטיות של OpenTelemetry GenAI, גרסה 1.37.0 ואילך, וכתוצאה מכך מתקבלות הודעות שהשם שלהן מתחיל ב-gen_ai.

בכרטיסייה Inputs/Outputs (קלט/פלט) מוצגות הודעות בפורמט של צ'אט. אתם קובעים אילו הודעות יופיעו ומה יהיה הפורמט שלהן באמצעות האפשרויות בכרטיסייה:

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

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

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

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

• כדי לראות את ההודעות בפורמט JSON, בוחרים באפשרות Raw. בבחירה הזו, מדיה כמו תמונות לא מוצגת.

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

  

מציאת כל רשומות היומן שמתייחסות לפרומפטים ולתשובות

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

1. במסוף Google Cloud , נכנסים לדף segment Logs Explorer:

   כניסה אל Logs Explorer

   אם משתמשים בשורת החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.

2. בכלי לבחירת פרויקטים, בוחרים את הפרויקט Google Cloud .

3. בסרגל הכלים, מרחיבים את האפשרות All log names, מזינים gen_ai במסנן ובוחרים ביומן שנקרא gen_ai.client.inference.operation.details.

   השלבים הקודמים מוסיפים את השאילתה הבאה ל-Logs Explorer:

   logName="projects/PROJECT_ID/logs/gen_ai.client.inference.operation.details"
   

   אם רוצים, מחליפים את PROJECT_ID במזהה הפרויקט, מעתיקים את ההצהרה ומדביקים אותה בחלונית Query של Logs Explorer.

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

   labels."event.name"="gen_ai.client.inference.operation.details"
   

4. כדי לראות את ההנחיות והתשובות שמקושרות לרשומה ביומן, לוחצים על View trace details (הצגת פרטי המעקב) ברשומה ביומן.

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

ניתוח נתונים של הנחיות ותשובות באמצעות BigQuery

אתם יכולים לנתח את ההנחיות והתשובות שמאוחסנות בקטגוריה של Cloud Storage באמצעות BigQuery. לפני שמבצעים את הניתוח הזה, צריך לבצע את השלבים הבאים:

1. מפעילים את ממשקי ה-API הנדרשים ומוודאים שקיבלתם את תפקידי ה-IAM הנדרשים.
2. יוצרים מערך נתונים מקושר ב-BigQuery בדלי של יומנים.
3. נותנים ל-BigQuery הרשאה לקרוא מהקטגוריה שלכם ב-Cloud Storage.
4. ליצור טבלה חיצונית.

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

לפני שמתחילים

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

1. מפעילים את BigQuery API ואת BigQuery Connection API, אם הם לא מופעלים.

   תפקידים שנדרשים להפעלת ממשקי API

   כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   הפעלת ממשקי ה-API

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

   חשוב: צריך להקצות את התפקידים האלה לחשבון השירות שבו האפליקציה משתמשת, ולא לחשבון המשתמש. אם לא מקצים את התפקידים לחשבון המשתמש הנכון, יכול להיות שיופיעו שגיאות הרשאה.
   • כתיבה של הגדרות יומנים (roles/logging.configWriter)
   • אדמין באחסון (roles/storage.admin)
   • אדמין של BigQuery Connection (roles/bigquery.connectionAdmin)
   • BigQuery Data Viewer (roles/bigquery.dataViewer)
   • BigQuery Studio User (roles/bigquery.studioUser)

יצירת מערך נתונים מקושר ב-BigQuery בדלי של יומנים

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

   gcloud logging buckets describe LOG_BUCKET_ID --location=LOCATION
   

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

   • ‫LOG_BUCKET_ID: מזהה מאגר היומנים.
   • ‫LOCATION: המיקום של מאגר היומנים.

   כשמשדרגים מאגר יומנים ל-Observability Analytics, התוצאות של הפקודה describe כוללות את ההצהרה הבאה:

   analyticsEnabled: true
   

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

   gcloud logging buckets update LOG_BUCKET_ID --location=LOCATION --enable-analytics --async
   

   תהליך השדרוג יכול להימשך כמה דקות. כשהפקודה describe מחזירה את הערך lifecycleState בתור ACTIVE, השדרוג הושלם.

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

   gcloud logging links create LINKED_DATASET_NAME --bucket=LOG_BUCKET_ID --location=LOCATION
   

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

   • ‫LOG_BUCKET_ID: מזהה מאגר היומנים.
   • ‫LOCATION: המיקום של מאגר היומנים.
   • ‫LINKED_DATASET_NAME: השם של מערך הנתונים המקושר ב-BigQuery שרוצים ליצור.

   מערך הנתונים המקושר ב-BigQuery מאפשר ל-BigQuery לקרוא את נתוני היומן שמאוחסנים בדלי היומן. מידע נוסף זמין במאמר בנושא שאילתות על מערך נתונים מקושר ב-BigQuery.

   כדי לוודא שהקישור קיים, מריצים את הפקודה הבאה:

   gcloud logging links list --bucket=LOG_BUCKET_ID --location=LOCATION
   

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

   LINK_ID: LINKED_DATASET_NAME
   

נותנים ל-BigQuery הרשאה לקרוא מהקטגוריה שלכם ב-Cloud Storage

1. כדי ליצור חיבור ל-BigQuery, מריצים את הפקודה הבאה:

   bq mk --connection --location=CONNECTION_LOCATION --project_id=PROJECT_ID \
         --connection_type=CLOUD_RESOURCE CONNECTION_ID
   

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

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫CONNECTION_ID: המזהה של החיבור שרוצים ליצור.
   • ‫CONNECTION_LOCATION: המיקום של החיבור.

   אם הפקודה מסתיימת בלי שגיאות, מוצגת הודעה שדומה לזו:

   Connection 151560119848.CONNECTION_LOCATION.CONNECTION_ID successfully created
   

2. בודקים את החיבור.

   bq show --connection PROJECT_ID.CONNECTION_LOCATION.CONNECTION_ID
   

   התגובה לפקודה הזו מציגה את מזהה החיבור ואת חשבון השירות:

   {"serviceAccountId": "[e-mail]"}
   

3. נותנים לחשבון השירות של חיבור BigQuery תפקיד IAM שמאפשר לו לקרוא נתונים שמאוחסנים בדלי Cloud Storage:

   gcloud storage buckets add-iam-policy-binding gs://STORAGE_BUCKET \
     --member=serviceAccount:SERVICE_ACCT_EMAIL \
     --role=roles/storage.objectViewer
   

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

   • ‫STORAGE_BUCKET: השם של הקטגוריה שלכם ב-Cloud Storage.
   • SERVICE_ACCT_EMAIL: כתובת האימייל של חשבון השירות.

יצירת טבלת BigLake חיצונית

כדי להריץ שאילתות על נתוני ההנחיות והתשובות שמאוחסנים בדלי ב-Cloud Storage, צריך להשתמש ב-BigQuery כדי ליצור טבלה חיצונית ב-BigLake.

1. במסוף Google Cloud , עוברים לדף BigQuery:

   כניסה ל-BigQuery Studio

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

2. בעורך השאילתות, מזינים את ההצהרה הבאה:

   CREATE OR REPLACE EXTERNAL TABLE `PROJECT_ID.EXT_TABLE_DATASET_NAME.EXT_TABLE_NAME` (
     -- Schema matching the JSON structure in a Cloud Storage bucket.
     parts ARRAY<
         STRUCT<
           type STRING,
           content STRING,
   
           -- multimodal attachments
           mime_type STRING,
           uri STRING,
           data BYTES,
   
           -- tool calls
           id STRING,
           name STRING,
           arguments JSON,
           response JSON
         >
       >,
       role STRING,
       `index` INT64,
     )
   
   WITH CONNECTION `PROJECT_ID.CONNECTION_LOCATION.CONNECTION_ID`
   OPTIONS (
     format = 'NEWLINE_DELIMITED_JSON',
     uris = ['gs://STORAGE_BUCKET/PATH/*'],
     ignore_unknown_values = TRUE
   );
   

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

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫EXT_TABLE_DATASET_NAME: השם של קבוצת הנתונים שרוצים ליצור.
   • ‫EXT_TABLE_NAME: השם של טבלת BigLake החיצונית שרוצים ליצור.
   • ‫CONNECTION_LOCATION: המיקום של CONNECTION_ID.
   • ‫CONNECTION_ID: מזהה החיבור.
   • ‫STORAGE_BUCKET: השם של הקטגוריה ב-Cloud Storage.
   • ‫PATH: הנתיב לפרומפטים ולתשובות. משתנה הסביבה OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH מציין את הנתיב.

3. לוחצים על Run.

מידע על טבלאות חיצוניות:

• מבוא למקורות נתונים חיצוניים
• מבוא לטבלאות חיצוניות ב-BigLake

צירוף הטבלה החיצונית לנתוני היומן

בקטע הזה מוסבר איך אפשר לנתח פרומפטים מולטי-מודאליים ב-BigQuery. הפתרון מתבסס על צירוף של טבלת BigLake חיצונית לנתוני היומן, וכך מאפשר לאחזר אובייקטים מהקטגוריה שלכם ב-Cloud Storage. בדוגמה הזו, ההצטרפות מתבצעת על ה-URI של הודעות הקלט, gen_ai.input.messages. אפשר גם להצטרף באמצעות ה-URI של הודעות הפלט, gen_ai.output.messages, או באמצעות ההוראות למערכת, gen_ai.system_instructions.

כדי לצרף את טבלת BigLake החיצונית לנתוני היומן:

1. במסוף Google Cloud , עוברים לדף BigQuery:

   כניסה ל-BigQuery Studio

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

2. בעורך השאילתות, מזינים את השאילתה הבאה, שמצטרפת לנתוני היומן ולטבלה החיצונית בנתיב לרשומות של קטגוריית Cloud Storage:

   -- Query the linked BigQuery dataset for completion logs.
   FROM PROJECT_ID.LINKED_DATASET_NAME._AllLogs
   |> WHERE
       log_name = 'projects/PROJECT_ID/logs/gen_ai.client.inference.operation.details'
       AND timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
   |> SELECT
     insert_id,
     timestamp,
     labels,
     trace,
     span_id,
     STRING(labels['gen_ai.input.messages_ref']) AS messages_ref_uri
   
   -- Join completion log entries with the external table.
   |> JOIN `PROJECT_ID.EXT_TABLE_DATASET_NAME.EXT_TABLE_NAME`
       ON messages_ref_uri = _FILE_NAME
   |> RENAME `index` AS message_idx
   
   -- Flatten.
   |> CROSS JOIN UNNEST(parts) AS part WITH OFFSET AS part_idx
   
   -- Print fields.
   |> SELECT
       insert_id,
       labels,
       timestamp,
       trace,
       span_id,
       role,
       part.content,
       part.uri,
       part.mime_type,
       TO_HEX(MD5(part.data)) AS data_md5_hex,
       part.id AS tool_id,
       part.name AS tool_name,
       part.arguments AS tool_args,
       part.response AS tool_response,
       message_idx,
       part_idx,
   |> ORDER BY timestamp, message_idx, part_idx;
   |> LIMIT 10;
   

   לפני שמריצים את השאילתה, מחליפים את הערכים הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫LINKED_DATASET_NAME: השם של מערך הנתונים המקושר ב-BigQuery.
   • ‫EXT_TABLE_DATASET_NAME: השם של מערך הנתונים של טבלת BigLake החיצונית.
   • ‫EXT_TABLE_NAME: השם של הטבלה החיצונית ב-BigLake.

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

   AND trace = 'projects/PROJECT_ID/traces/TRACE_ID'
   

   בביטוי הקודם, מחליפים את TRACE_ID במחרוזת הקסדצימלית של 16 בייט שמכילה מזהה מעקב.

שימוש בפונקציות של BigQuery ML

אתם יכולים להשתמש בפונקציות של BigQuery ML כמו AI.GENERATE בהנחיות ובתשובות שמאוחסנות בקטגוריה שלכם ב-Cloud Storage.

לדוגמה, השאילתה הבאה מצטרפת לרשומות ביומן ההשלמות עם הטבלה החיצונית, ואז משטחת ומסננת את תוצאת הצירוף. לאחר מכן, השאילתה מופעלת AI.GENERATE כדי לנתח אם הרשומות מכילות תמונה וליצור סיכום של כל רשומה:

-- Query the linked BigQuery dataset for completion logs.
FROM PROJECT_ID.LINKED_DATASET_NAME._AllLogs
|> WHERE
    log_name = 'projects/PROJECT_ID/logs/gen_ai.client.inference.operation.details'
    AND timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
|> SELECT
  insert_id,
  timestamp,
  labels,
  trace,
  span_id,
  STRING(labels['gen_ai.input.messages_ref']) AS messages_ref_uri

-- Join completion log entries with the external table.
|> JOIN `PROJECT_ID.EXT_TABLE_DATASET_NAME.EXT_TABLE_NAME`
    ON messages_ref_uri = _FILE_NAME
|> RENAME `index` AS message_idx

-- Flatten.
|> CROSS JOIN UNNEST(parts) AS part WITH OFFSET AS part_idx
|> WHERE part.uri IS NOT NULL AND part.uri LIKE 'gs://%'
|> LIMIT 10

-- Use natural language to search for images, and then summarize the entry.
|> EXTEND
    AI.GENERATE(
      (
        'Describe the attachment in one sentence and whether the image contains a diagram.',
        OBJ.FETCH_METADATA(OBJ.MAKE_REF(part.uri, 'CONNECTION_LOCATION.CONNECTION_ID'))),
      connection_id => 'CONNECTION_LOCATION.CONNECTION_ID',
      endpoint => 'gemini-2.5-flash-lite',
      output_schema => 'description STRING, is_match BOOLEAN') AS gemini_summary
|> SELECT insert_id, trace, span_id, timestamp, part_idx, part.uri, part.mime_type, gemini_summary
|> WHERE gemini_summary.is_match = TRUE
|> ORDER BY timestamp DESC

לפני שמריצים את השאילתה, מחליפים את הערכים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫LINKED_DATASET_NAME: השם של מערך הנתונים המקושר ב-BigQuery.
• ‫EXT_TABLE_DATASET_NAME: השם של מערך הנתונים של טבלת BigLake החיצונית.
• ‫EXT_TABLE_NAME: השם של הטבלה החיצונית ב-BigLake.
• ‫CONNECTION_LOCATION: המיקום של CONNECTION_ID.
• ‫CONNECTION_ID: מזהה החיבור.

הרצת הערכות על נתוני ההנחיות והתגובות באמצעות Colaboratory

אתם יכולים להעריך פרומפטים ותשובות באמצעות Vertex AI SDK ל-Python.

כדי להריץ הערכות באמצעות מחברת Google Colaboratory:

1. כדי לראות מחברת לדוגמה, לוחצים על evaluating_observability_datasets.ipynb.

   מערכת GitHub תיפתח ותציג הוראות לשימוש ב-notebook.

2. לוחצים על פתיחה ב-Colab.

   ‫Colaboratory ייפתח ויציג את הקובץ evaluating_observability_datasets.ipynb.

3. בסרגל הכלים, לוחצים על העתקה ל-Drive.

   ‫Colaboratory יוצר עותק של הנוטבוק, שומר אותו ב-Drive ואז פותח את העותק.

4. בעותק שלכם, עוברים לקטע Set Google Cloud project information ומזינים את Google Cloud מזהה הפרויקט בענן ואת המיקום שנתמך על ידי Vertex AI. לדוגמה, אפשר להגדיר את המיקום ל-"us-central1".

5. עוברים לקטע Load in Google Observability Gen AI datasets (טעינה של מערכי נתונים של AI גנרטיבי ב-Google Observability) ומזינים ערכים למקורות הבאים:

   • INPUT_SOURCE
   • OUTPUT_SOURCE
   • SYSTEM_SOURCE

   אפשר למצוא את הערכים של השדות האלה באמצעות התוויות gen_ai שמצורפות לרשומות ביומן. לדוגמה, עבור INPUT_SOURCE, הערך דומה לערך הבא:

   'gs://STORAGE_BUCKET/PATH/REFERENCE_inputs.jsonl'
   

   בביטוי שלמעלה, השדות מייצגים את הדברים הבאים:

   • ‫STORAGE_BUCKET: השם של הקטגוריה ב-Cloud Storage.
   • ‫PATH: הנתיב לפרומפטים ולתשובות.
   • ‫REFERENCE: המזהה של הנתונים בקטגוריית Cloud Storage.

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

6. בסרגל הכלים, לוחצים על הפעלה של הכול.