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

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

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

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

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

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

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

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

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

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

מוסיפים את חבילות המכשירים והייצוא הבאות של 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).

נתוני העקבות מאוחסנים בפורמט שתואם בדרך כלל לקובצי ה-proto שמוגדרים על ידי OpenTelemetry Line Protocol. עם זאת, יכול להיות שהשדות יומרו מסוג נתונים ספציפי ל-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'

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

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

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

  2. התקינו את ה-CLI של Google Cloud.

  3. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  4. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  5. יוצרים או בוחרים 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 .

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

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

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

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

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

  8. התקינו את ה-CLI של Google Cloud.

  9. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  10. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  11. יוצרים או בוחרים 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 .

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

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

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

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

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

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

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

  15. חשוב לוודא שמציינים פרויקט מכסה. ‫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 מרשימת הסוכנים.

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

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

What can you do for me ?

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

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

הצגת האינטראקציה עם sql_agent.

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

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

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

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

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

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

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

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

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

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

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

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

    כניסה אל Trace explorer

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

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

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

    הצגת טווחים של מעקב.

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

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

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

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

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

      הצגה של אירועים שקשורים ל-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 פרויקט, אבל היא לא יוצרת מדדים.