הוספת OpenTelemetry לאפליקציות ADK

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

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

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

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

הערה: במאמר הזה מניחים שאתם משתמשים במסגרת ADK בגרסה 1.17.0 ומעלה.

לבצע אינסטרומנטציה באפליקציית AI גנרטיבי כדי לאסוף נתוני טלמטריה

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

1. מתקינים חבילות OpenTelemetry.
2. הגדרת סביבת ADK.

בהמשך הקטע הזה מתוארים השלבים הקודמים.

התקנת חבילות OpenTelemetry

מוסיפים את חבילות ה-instrumentation והייצוא הבאות של OpenTelemetry:

uv add 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

נתוני היומנים נשלחים לפרויקט Google Cloud באמצעות Cloud Logging API או Cloud Monitoring API. הספרייה opentelemetry-exporter-gcp-logging מפעילה נקודות קצה ב-Cloud Logging API.

לא נאספים נתונים של מדדים. בדרך כלל, אפליקציות שלא משתמשות בפתרון מבוסס-איסוף כוללות את הספרייה opentelemetry-exporter-gcp-monitoring. הספרייה הזו מפעילה נקודות קצה ב-Cloud Monitoring API.

נתוני מעקב נשלחים אל Google Cloud באמצעות Telemetry (OTLP) API, שמיישם את OpenTelemetry Line Protocol. ספריית opentelemetry-exporter-otlp-proto-grpc מפעילה את נקודת הקצה ל-API של Telemetry (OTLP).

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

הגדרת סביבת ה-ADK

גרסאות 1.17.0 ומעלה של מסגרת ADK כוללות תמיכה מובנית ב-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'
  

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

  למידע נוסף על ערכים מותרים של ספירה, אפשר לעיין במאמר בנושא 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 פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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 .

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

מפעילים את ממשקי ה-API‏ Vertex AI,‏ Service Usage,‏ Telemetry,‏ Cloud Logging,‏ Cloud Monitoring ו-Cloud Trace:

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

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

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

• Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
• יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (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 .

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

מפעילים את ממשקי ה-API‏ Vertex AI,‏ Service Usage,‏ Telemetry,‏ Cloud Logging,‏ Cloud Monitoring ו-Cloud Trace:

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

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

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

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

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Logs Writer (roles/logging.logWriter)
   • כתיבת מדדי מעקב (roles/monitoring.metricWriter)
   • משתמש Vertex AI (roles/aiplatform.user)

   ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבים או בסביבת פיתוח מקומית. Google Cloud

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

2. חשוב לוודא שמציינים פרויקט מכסה. ‫Vertex AI API‏ (aiplatform.googleapis.com) מחייב לציין מכסה בפרויקט. מידע נוסף זמין במאמר בנושא הגדרת פרויקט לצורכי מכסה. לדוגמה, הפקודה הבאה יכולה להגדיר פרויקט של מכסת שימוש.

   gcloud config set billing/quota_project PROJECT_ID

הפעלת האפליקציה

כדי להפעיל את האפליקציה לדוגמה:

1. ב-Cloud Shell, משכפלים את המאגר:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. עוברים לספריית הדוגמאות:

   cd opentelemetry-samples/python/adk-sql-agent
   

   הדוגמה מכילה קובץ .env שמגדיר שני משתנים סביבתיים. משתנה אחד קובע באילו נקודות קצה ה-SDK משתמש. המשתנה השני מגדיר מיקום.

   אם אתם מעדיפים להשתמש במודל אחר, אתם יכולים לערוך את main.py. חשוב לוודא שהמודל שבחרתם תומך במיקום שצוין בקובץ .env. מידע על מודלים זמין במאמר מודלים של Google.

3. יוצרים סביבה וירטואלית ומריצים את הדוגמה:

   uv run --env-file opentelemetry.env adk web --otel_to_cloud
   

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

   Appplication startup complete
   Uvicorn running on http://127.0.0.1:8080
   

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

5. מרחיבים את בחירת אפליקציה ובוחרים את sql_agent מרשימת הסוכנים.

   הערה: האפליקציה הזו דורשת שיתוף משאבים בין מקורות (CORS). אם מזינים הנחיה ו-CORS חסום, האפליקציה מציגה את ההודעה Failed to create session ובשורת הפקודה מופיע שהפקודות נדחו, POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   כדי להפעיל את CORS, מוסיפים את הפקודה הבאה לפקודה שמריצה את הדוגמה:
   

   --allow_origins="regex:.*"

איך מתקשרים עם נציג

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

What can you do for me ?

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

בדוגמה הבאה מוצגת אינטראקציה לדוגמה בין sql_agent לבין המשתמש:

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

יציאה מהאפליקציה

כדי לצאת מהאפליקציה, מזינים Ctrl-C במעטפת שבה השתמשתם כדי להפעיל את האפליקציה.

צפייה בנתוני המעקב, במדדים וביומנים

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

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

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

• כלי הצפייה ביומנים (roles/logging.viewer)
• צפייה ב-Monitoring (roles/monitoring.viewer)
• משתמש Cloud Trace (roles/cloudtrace.user)

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

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

צפייה בטלמטריה

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

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

   כניסה אל Trace explorer

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

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

   האיור הבא מציג את הדף Trace Explorer אחרי סינון הנתונים:

   

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

3. כדי לעיין בנתוני יחידה לוגית למעקב ויומן, בטבלה Spans, בוחרים יחידה לוגית למעקב.

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

   • בכרטיסייה Inputs/Outputs מוצגים אירועים של סוכני AI גנרטיבי. מידע נוסף על האירועים האלה זמין במאמר צפייה באירועים של AI גנרטיבי.

     בצילום המסך הבא מוצג מעקב, שבו לטווח אחד יש את השם call_llm. הטווח הזה מפעיל את ה-LLM (מודל שפה גדול) שמפעיל את הנציג הזה. בדוגמה הזו, המודל הוא Gemini. הטווח של Gemini כולל אירועים של AI גנרטיבי:

     

   • בכרטיסייה Logs & Events (יומנים ואירועים) מופיעים רשומות ביומן ואירועים שמשויכים לטווח. אם רוצים לראות את נתוני היומן ב-Logs Explorer, בסרגל הכלים של הכרטיסייה הזו בוחרים באפשרות הצגת יומנים.

     נתוני היומן כוללים את התשובה של sql_agent. לדוגמה, בהרצת הדוגמה, מטען ה-JSON הייעודי (payload) כולל את התוכן הבא:

     {
       "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"
         }
       },
       ...
     }
     

הדוגמה מוגדרת לשליחת נתוני מדדים ל Google Cloud פרויקט, אבל היא לא יוצרת מדדים.