Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

בדף Trace Explorer אפשר לראות הנחיות או תשובות ספציפיות, או שיחה שלמה. יש לכם אפשרויות לצפייה במדיה בפורמט מעובד או בפורמט גולמי. מידע נוסף על צפייה בהנחיות ובתשובות ל-multimodal
משתמשים בשירותי BigQuery כדי לנתח את הנתונים המולטימודאליים. לדוגמה, אפשר להשתמש בפונקציה כמו AI.GENERATE כדי לסכם שיחה. מידע נוסף זמין במאמר בנושא ניתוח נתוני הנחיות ותשובות באמצעות BigQuery.
משתמשים ב-Vertex AI SDK כדי להעריך שיחה. לדוגמה, אפשר להשתמש ב-Google Colaboratory כדי לבצע ניתוח סנטימנט. מידע נוסף זמין במאמר הרצת הערכות על נתוני ההנחיות והתשובות באמצעות Colaboratory.

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

אתם יכולים להשתמש במוצרים כמו Model Armor ו-Sensitive Data Protection כדי לנהל מידע אישי רגיש שעשוי להיכלל בהנחיות ובתשובות.

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

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

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

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

איפה נשמרות ההנחיות והתשובות

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

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

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

כש-OpenTelemetry instrumentation יוצרת אובייקטים של קטגוריות ב-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. מוודאים שהחיוב מופעל בפרויקט Google Cloud .
2. מפעילים את ממשקי ה-API‏ Vertex AI,‏ Cloud Storage,‏ Telemetry,‏ Cloud Logging ו-Cloud Trace.
  תפקידים שנדרשים להפעלת ממשקי API
  כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים
  הפעלת ממשקי ה-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/roles/storage.objectUser) בקטגוריית האחסון
  - כתיבה ביומן (roles/logging.logWriter) בפרויקט
  - כותב מדדים של Monitoring (roles/monitoring.metricWriter) בפרויקט
  - ‫Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) בפרויקט שלכם
  התפקיד 'Storage Object User' כולל את ההרשאה storage.objects.create. ההרשאה הזו מאפשרת לאפליקציה לכתוב אובייקטים לקטגוריה שלכם ב-Cloud Storage. באובייקטים האלה מאוחסנות ההנחיות והתשובות שהאפליקציה מבוססת-הסוכן יוצרת או מקבלת. מידע נוסף זמין במאמר הגדרה וניהול של מדיניות IAM בדליים.
מגדירים את ה-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 לא לצרף תוכן הודעה כמאפיינים בטווחים.
```
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: Attributes:

דוגמה לפלט שעבר עיבוד.

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

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

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

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

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

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

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

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

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

הכרת הנחיות ותשובות של multimodal

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

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

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

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

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

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

חיפוש כל רשומות היומן שמתייחסות להנחיות ולתשובות

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

במסוף Google Cloud , נכנסים לדף Logs Explorer:
כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
בבורר הפרויקטים, בוחרים את הפרויקט Google Cloud .
בסרגל הכלים, מרחיבים את האפשרות All log names, מקלידים gen_ai במסנן ובוחרים ביומן בשם gen_ai.client.inference.operation.details.

השלבים הקודמים מוסיפים את השאילתה הבאה ל-Logs Explorer:
```
logName="projects/PROJECT_ID/logs/gen_ai.client.inference.operation.details"
```
אם רוצים, אפשר להעתיק את ההצהרה ולהדביק אותה בחלונית Query של Logs Explorer, אבל צריך להחליף את PROJECT_ID במזהה הפרויקט לפני שמבצעים את ההעתקה.

אפשר גם לסנן את נתוני היומן לפי ערך התווית. לדוגמה, אם מוסיפים את המסנן הבא, יופיעו רק רשומות ביומן שמכילות את התווית שצוינה:
```
labels."event.name"="gen_ai.client.inference.operation.details"
```
כדי לראות את ההנחיות והתשובות שמקושרות לרשומה ביומן, לוחצים על View trace details ברשומה ביומן.

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

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

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

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

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

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

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

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

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

יצירת מערך נתונים מקושר בקטגוריית היומנים

כדי לבדוק אם קטגוריית היומנים שבה מאוחסנים נתוני היומן שודרגה ל-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, השדרוג הושלם.
כדי ליצור מערך נתונים מקושר בקטגוריית היומנים, מריצים את הפקודה הבאה:
```
gcloud logging links create LINKED_DATASET_NAME --bucket=LOG_BUCKET_ID --location=LOCATION
```
לפני שמריצים את הפקודה, מחליפים את הערכים הבאים:
- ‫LOG_BUCKET_ID: מזהה קטגוריה ביומן.
- ‫LOCATION: המיקום של קטגוריה ביומן.
- ‫LINKED_DATASET_NAME: השם של מערך הנתונים המקושר שרוצים ליצור.
מערך הנתונים המקושר מאפשר ל-BigQuery לקרוא את נתוני היומן שמאוחסנים בדלי היומנים. מידע נוסף על שאילתות במערך נתונים מקושר של BigQuery

כדי לוודא שהקישור קיים, מריצים את הפקודה הבאה:
```
gcloud logging links list --bucket=LOG_BUCKET_ID --location=LOCATION
```
אם הפקודה הקודמת מצליחה, התגובה כוללת את השורה הבאה:
```
LINK_ID: LINKED_DATASET_NAME
```

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

כדי ליצור חיבור ל-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
```

מאמתים את החיבור.

bq show --connection PROJECT_ID.CONNECTION_LOCATION.CONNECTION_ID

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

{"serviceAccountId": "bqcx-151560119848-s1pd@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

נותנים לחשבון השירות של חיבור 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 חיצונית

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

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

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

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

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 מציין את הנתיב.

לוחצים על Run.

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

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

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

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

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

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

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

-- Query the linked 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: השם של קבוצת הנתונים המקושרת.
‫EXT_TABLE_DATASET_NAME: השם של מערך הנתונים של טבלת BigLake החיצונית.
‫EXT_TABLE_NAME: השם של הטבלה החיצונית ב-BigLake.

אופציונלי: השאילתה הקודמת מסננת לפי שם היומן וחותמת הזמן. אם רוצים לסנן גם לפי מזהה מעקב ספציפי, מוסיפים את ההצהרה הבאה לפסוקית 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 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: השם של קבוצת הנתונים המקושרת.
‫EXT_TABLE_DATASET_NAME: השם של מערך הנתונים של טבלת BigLake החיצונית.
‫EXT_TABLE_NAME: השם של הטבלה החיצונית ב-BigLake.
‫CONNECTION_LOCATION: המיקום של CONNECTION_ID.
‫CONNECTION_ID: מזהה החיבור.

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

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

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

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

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

‫Colaboratory ייפתח והקובץ evaluating_observability_datasets.ipynb יוצג.
בסרגל הכלים, לוחצים על העתקה ל-Drive.

‫Colaboratory יוצר עותק של ה-notebook, שומר אותו ב-Drive ואז פותח את העותק.
בעותק שלכם, עוברים לקטע Set Google Cloud project information ומזינים את Google Cloud מזהה הפרויקט Google Cloud ואת המיקום שנתמך על ידי Vertex AI. לדוגמה, אפשר להגדיר את המיקום ל-"us-central1".
עוברים לקטע 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.
במאמר איך מוצאים את כל רשומות היומן שמפנות להנחיות ולתשובות מוסבר איך מוצאים את הערכים של המקורות האלה.
בסרגל הכלים, לוחצים על הפעלה של הכול.

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

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

איפה נשמרות ההנחיות והתשובות

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

ADK

LangGraph

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

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

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

הכרת הנחיות ותשובות של multimodal

חיפוש כל רשומות היומן שמתייחסות להנחיות ולתשובות

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

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

יצירת מערך נתונים מקושר בקטגוריית היומנים

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

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

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

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

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

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