במאמר הזה מוסבר איך להוסיף כלי מדידה לסוכן AI שנוצר באמצעות ה-framework של הערכה לפיתוח סוכנים (ADK). מסגרת ה-ADK כוללת כלי OpenTelemetry שאוספים נתוני טלמטריה מהפעולות העיקריות של הנציג. כשמפעילים את כלי המדידה המובנים, הם שולחים מידע כמו פרומפטים טקסטואליים ותשובות של הנציג לפרויקט ב- Google Cloud . במסמך הזה מפורטים השינויים הנדרשים ויש בו קישור לאפליקציה לדוגמה.
אפליקציות שמשתמשות ב-ADK יכולות גם לאסוף פרומפטים ותשובות מולטי-מודאליים. במאמר הזה מוסבר איך לאסוף פרומפטים טקסטואליים ותשובות. אם רוצים לאסוף נתונים ממספר מקורות, צריך להגדיר הגדרות נוספות. מידע נוסף זמין במאמר איסוף והצגה של הנחיות ותשובות בכמה אופנים.
יכול להיות שהתצפיתיות שמוגדרת כברירת מחדל ב-ADK לא תספיק לתרחיש לדוגמה של האפליקציה שלכם. אתם יכולים להוסיף עוד ספריות אינסטרומנטציה באמצעות OpenTelemetry כדי לתעד נתוני טלמטריה מחלקים אחרים של האפליקציה, או להשתמש באינסטרומנטציה בהתאמה אישית כדי לתעד נתונים ספציפיים לאפליקציה ולקבל ניראות מפורטת יותר. לדוגמה, אתם יכולים לכתוב באפליקציה קוד למדידת ביצועים כדי:
- מעקב אחרי צריכת המשאבים של כלים שהסוכן מפעיל.
- מעקב אחרי כשלים באימות שספציפיים לאפליקציה, הפרות של כללים עסקיים או מנגנונים מותאמים אישית להתאוששות משגיאות.
- לעקוב אחרי ציוני האיכות של התשובות של הנציג על סמך הקריטריונים הספציפיים לדומיין שלכם.
הוספת כלים לאפליקציית ה-AI הגנרטיבי כדי לאסוף נתוני טלמטריה
כדי להגדיר את סוכן ה-AI לאסוף נתוני יומנים, מדדים ומעקב, מבצעים את הפעולות הבאות:
בהמשך הקטע מתוארים השלבים הקודמים.
התקנת חבילות OpenTelemetry
מוסיפים את חבילות הכלים והייצוא הבאות של OpenTelemetry:
uv add 'google-adk>=2.12.0' \
'opentelemetry-instrumentation-google-genai>=0.7b1' \
'opentelemetry-instrumentation-sqlite3>=0.63b1' \
'opentelemetry-exporter-otlp-proto-grpc>=1.42.1' \
'opentelemetry-exporter-otlp-proto-http>=1.42.1' \
'opentelemetry-instrumentation-vertexai>=2.0b0'
נתוני היומנים, המדדים והמעקבים נשלחים אל Google Cloud באמצעות Telemetry (OTLP) API, שמטמיע את פרוטוקול OpenTelemetry.
הספרייה opentelemetry-exporter-otlp-proto-grpc מפעילה את נקודת הקצה ל-API של Telemetry (OTLP).
נתוני המעקב מאוחסנים בפורמט שתואם בדרך כלל לקובצי ה-proto שמוגדרים על ידי פרוטוקול OpenTelemetry. עם זאת, יכול להיות שהשדות יומרו מסוג נתונים ספציפי ל-OpenTelemetry לסוג נתונים של JSON לפני האחסון. למידע נוסף על פורמט האחסון, קראו את המאמר סכימה לנתוני מעקב.
הגדרת סביבת ה-ADK
גרסאות 1.17.0 ואילך של ADK framework כוללות תמיכה מובנית ב-OpenTelemetry ובשליחת נתוני טלמטריה של OpenTelemetry אלGoogle Cloud Observability. כדי להפעיל את האפשרות הזו, צריך להגדיר את סביבת ה-ADK:
אם אתם מריצים את האפליקציה באמצעות הפקודה
adk web, צריך לכלול את הדגל--otel_to_cloud.בקובץ
opentelemetry.env, מגדירים את משתני הסביבה הבאים:OTEL_SERVICE_NAME='adk-sql-agent' OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'מגדירים את OpenTelemetry כך שישתמש במוסכמות הסמנטיות העדכניות ביותר ל-AI גנרטיבי.
OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'מגדירים את OpenTelemetry כך שיצרף הודעות כאירועים.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'מידע נוסף על ערכים ממוספרים מותרים זמין במאמר
genai/types.py.מומלץ גם להוסיף את משתנה הסביבה הבא לקובץ
opentelemetry.env:ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'משתנה הסביבה הזה מבצע את הפעולות הבאות:
- מונעת מהכלים של ADK לצרף מאפייני span שחורגים ממגבלת הגודל של המאפיינים.
- מונעת צירוף של פרטים אישיים מזהים (PII) לטווחים כמאפיינים.
יכול להיות שתצטרכו להגדיר משתני סביבה אחרים. לדוגמה, אם אתם פורסים ב-Gemini Enterprise Agent Platform, אתם צריכים להגדיר גם את משתנה הסביבה הבא:
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
הורדה והפעלה של האפליקציה לדוגמה
הקוד לדוגמה הזה מטמיע סוכן AI גנרטיבי שנוצר באמצעות ADK. הסוכן מצויד ב-OpenTelemetry, שמוגדר לשלוח מדדים, מעקבים ויומנים לפרויקט ב- Google Cloud . הנתונים הטלמטריים שנשלחים לפרויקט כוללים הנחיות ותשובות של AI גנרטיבי.
פרסונה של סוכן ADK
סוכן ה-AI הגנרטיבי מוגדר כמומחה SQL שיש לו גישה מלאה למסד נתונים זמני של SQLite. הסוכן נוצר באמצעות הערכה לפיתוח סוכנים, והוא ניגש למסד נתונים באמצעות SQLDatabaseToolkit. מסד הנתונים ריק בהתחלה.
לפני שמתחילים
- נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init -
יוצרים או בוחרים פרויקט ב- Google Cloud .
התפקידים שנדרשים כדי לבחור או ליצור פרויקט
- בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
-
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (
roles/resourcemanager.projectCreator), שכולל את ההרשאהresourcemanager.projects.create. איך מקצים תפקידים?
-
יוצרים פרויקט ב- Google Cloud :
gcloud projects create PROJECT_ID
מחליפים את
PROJECT_IDבשם של הפרויקט ב- Google Cloud שאתם יוצרים. -
בוחרים את הפרויקט שיצרתם ב- Google Cloud :
gcloud config set project PROJECT_ID
מחליפים את
PROJECT_IDבשם הפרויקט ב- Google Cloud .
מפעילים את ממשקי ה-API הבאים, אם הם עדיין לא מופעלים: Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring ו-Cloud Trace.
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידיםgcloud services enable aiplatform.googleapis.com
serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com -
התקינו את ה-CLI של Google Cloud.
-
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.
-
כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:
gcloud init -
יוצרים או בוחרים פרויקט ב- Google Cloud .
התפקידים שנדרשים כדי לבחור או ליצור פרויקט
- בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
-
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (
roles/resourcemanager.projectCreator), שכולל את ההרשאהresourcemanager.projects.create. איך מקצים תפקידים?
-
יוצרים פרויקט ב- Google Cloud :
gcloud projects create PROJECT_ID
מחליפים את
PROJECT_IDבשם של הפרויקט ב- Google Cloud שאתם יוצרים. -
בוחרים את הפרויקט שיצרתם ב- Google Cloud :
gcloud config set project PROJECT_ID
מחליפים את
PROJECT_IDבשם הפרויקט ב- Google Cloud .
מפעילים את ממשקי ה-API הבאים, אם הם עדיין לא מופעלים: Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring ו-Cloud Trace.
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה
serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידיםgcloud services enable aiplatform.googleapis.com
serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com -
כדי לקבל את ההרשאות שנדרשות כדי שאפליקציית הדוגמה תכתוב נתוני יומנים, מדדים ומעקב, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- כתיבת נתוני מעקב ב-Cloud Telemetry (
roles/telemetry.tracesWriter) - כתיבת יומנים (
roles/logging.logWriter) - כתיבת מדדי מעקב (
roles/monitoring.metricWriter) - Vertex AI User (
roles/aiplatform.user)
ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבי Google Cloud או בסביבת פיתוח מקומית.
- כתיבת נתוני מעקב ב-Cloud Telemetry (
חשוב לוודא שאתם מציינים פרויקט לצורכי מכסה. ב-Vertex AI API (
aiplatform.googleapis.com) צריך לציין פרויקט לחיוב על מכסות. למידע נוסף, קראו את המאמר הגדרת הפרויקט לצורכי מכסה. לדוגמה, הפקודה הבאה יכולה להגדיר פרויקט לחיוב על מכסות.gcloud config set billing/quota_project PROJECT_ID
מפעילים את האפליקציה.
כדי להפעיל את האפליקציה לדוגמה:
ב-Cloud Shell, משכפלים את המאגר:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.gitעוברים לספריית הדוגמה:
cd opentelemetry-samples/python/adk-sql-agentהדוגמה מכילה קובץ
.envשמגדיר שני משתני סביבה. משתנה אחד קובע באילו נקודות קצה ה-SDK משתמש. המשתנה השני מגדיר מיקום.אם אתם מעדיפים להשתמש במודל אחר, ערכו את
main.py. חשוב לוודא שהמודל שבחרתם תומך במיקום שצוין בקובץ.env. מידע נוסף על המודלים זמין במאמר המודלים של Google.יוצרים סביבה וירטואלית ומריצים את הדוגמה:
uv run --env-file opentelemetry.env adk web --otel_to_cloudבאפליקציה תוצג הודעה דומה לזו:
Application startup complete Uvicorn running on http://127.0.0.1:8080כדי לקיים אינטראקציה עם הנציג, בוחרים את כתובת ה-URL שמופיעה בפלט של השלב הקודם.
מרחיבים את האפשרות בחירת אפליקציה ובוחרים את
sql_agentמרשימת הנציגים.
אינטראקציה עם הסוכן
כדי לתקשר עם הסוכן, שואלים אותו שאלה או נותנים לו פקודה. לדוגמה, אתם יכולים לשאול:
What can you do for me ?
באופן דומה, מכיוון של-sql_agent יש פרסונה של מומחה SQL, אתם יכולים לבקש ממנו ליצור טבלאות לאפליקציות שלכם ולכתוב שאילתות שיפעלו על הטבלאות שנוצרו. הסוכן יכול ליצור רק מסד נתונים זמני שמגובה בקובץ .db שנוצר במכונה שמריצה את האפליקציה.
הדוגמה הבאה ממחישה אינטראקציה בין sql_agent למשתמש:
הפעולות שמבצעים סוכני AI גנרטיבי הן לא דטרמיניסטיות, ולכן יכול להיות שתקבלו תשובה שונה לאותו פרומפט.
יוצאים מהאפליקציה.
כדי לצאת מהאפליקציה, מזינים Ctrl-C במעטפת שבה השתמשתם כדי להפעיל את האפליקציה.
הצגת המעקבים, המדדים ורישומי היומן
בקטע הזה מוסבר איך אפשר לראות אירועי AI גנרטיבי.
לפני שמתחילים
כדי לקבל את ההרשאות שדרושות לצפייה בנתוני היומנים, המדדים והמעקב, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט:
- צפייה ביומנים (
roles/logging.viewer) - צפייה במעקב (
roles/monitoring.viewer) - Cloud Trace User (
roles/cloudtrace.user)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
הצגת נתוני הטלמטריה
כדי לראות את אירועי ה-AI הגנרטיבי שהאפליקציה יצרה, משתמשים בדף Trace Explorer:
-
במסוף Google Cloud , נכנסים לדף
Trace explorer:
אפשר גם למצוא את הדף הזה באמצעות שורת החיפוש.
בסרגל הכלים, לוחצים על Add filter, בוחרים באפשרות Span name ואז בוחרים ב-
call_llm.כך נראה הדף Trace Explorer אחרי סינון הנתונים:
אם אף פעם לא השתמשתם ב-Cloud Trace, צריך ליצור מסד נתונים ב-Google Cloud Observability כדי לאחסן את נתוני המעקב. יצירת מסד הנתונים יכולה להימשך כמה דקות, ובמהלך הזמן הזה אי אפשר לראות את נתוני המעקב.
כדי לבחון את נתוני הטווחים והיומנים, בוחרים טווח בטבלה Spans.
הדף Details נפתח. בדף הזה מוצג המעקב המשויך והתקופות שלו. בטבלה שבדף מוצג מידע מפורט על ה-span שנבחר. המידע הזה כולל:
בכרטיסייה Inputs/Outputs מוצגים אירועים של סוכני AI גנרטיבי. מידע נוסף על האירועים האלה זמין במאמר צפייה באירועי AI גנרטיבי.
בצילום המסך הבא מוצג מעקב שבו ל-span אחד יש את השם
call_llm. ה-span הזה מפעיל את מודל השפה הגדול (LLM) שמפעיל את הנציג הזה. בדוגמה הזו, המודל הוא Gemini. התקופה של Gemini כוללת אירועים של AI גנרטיבי:
בכרטיסייה Logs & Events מופיעה רשימה של רשומות ביומן ואירועים שמשויכים ל-span. כדי לראות את נתוני היומן ב-Logs Explorer, לוחצים על View logs בסרגל הכלים של הכרטיסייה.
נתוני היומן כוללים את התגובה של
sql_agent. לדוגמה, בהרצה לדוגמה, המטען הייעודי (payload) של ה-JSON כולל את התוכן הבא:{ "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp", "jsonPayload": { "content": { "parts": [ 0: { "text": "Now I can create the table." } 1: {1} ], "role": "model" } }, ... }