הפלאגין של Google Cloud

הפלאגין של Google Cloud מייצא את נתוני הטלמטריה והיומנים של Firebase Genkit אל חבילת התפעול של Google Cloud.

התקנה

npm i --save @genkit-ai/google-cloud

אם רוצים להריץ באופן מקומי תהליכים שמשתמשים בפלאגין הזה, צריך להתקין גם את הכלי Google Cloud CLI.

הגדרת חשבון Google Cloud

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

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

ממשקי ה-API האלה אמורים להופיע במרכז הבקרה של ה-API של הפרויקט.

מידע נוסף על הפעלה והשבתה של ממשקי API זמין כאן.

הגדרת Genkit

כדי להפעיל את הייצוא ל-Google Cloud Tracing,‏ Logging ו-Monitoring, מוסיפים את הפלאגין googleCloud להגדרות של Genkit:

import { googleCloud } from '@genkit-ai/google-cloud';

export default configureGenkit({
  plugins: [googleCloud()],
  enableTracingAndMetrics: true,
  telemetry: {
    instrumentation: 'googleCloud',
    logger: 'googleCloud',
  },
});

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

אימות

כדי להשתמש בפלאגין, נדרשים מזהה הפרויקט ב-Google Cloud ופרטי הכניסה לפרויקט ב-Google Cloud. אם אתם מריצים את התהליך מסביבת Google Cloud (Cloud Functions,‏ Cloud Run וכו'), מזהה הפרויקט ופרטי הכניסה מוגדרים באופן אוטומטי.

Application Default Credentials

כדי לפעול בסביבות אחרות צריך להגדיר את משתנה הסביבה GCLOUD_PROJECT לפרויקט שלכם ב-Google Cloud ולבצע אימות באמצעות הכלי gcloud:

gcloud auth application-default login

מידע נוסף זמין במסמכי Application Default Credentials.

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

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

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

נתיב הקובץ:

GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

הטקסט הישיר:

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

הגדרת יישומי פלאגין

הפלאגין googleCloud() משתמש באובייקט הגדרה אופציונלי:

{
    projectId?: string,
    telemetryConfig?: TelemetryConfig
}

projectId

בעזרת האפשרות הזו, אפשר לציין באופן מפורש את מזהה הפרויקט ב-Google Cloud. ברוב המקרים אין צורך בכך.

telemetryConfig

האפשרות הזו מגדירה את המכונה של OpenTelemetry NodeSDK.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

googleCloud({
  telemetryConfig: {
    forceDevExport: false, // Set this to true to export telemetry for local runs
    sampler: new AlwaysOnSampler(),
    autoInstrumentation: true,
    autoInstrumentationConfig: {
      '@opentelemetry/instrumentation-fs': { enabled: false },
      '@opentelemetry/instrumentation-dns': { enabled: false },
      '@opentelemetry/instrumentation-net': { enabled: false },
    },
    metricExportIntervalMillis: 5_000,
  },
});

forceDevExport

האפשרות הזו תאלץ את Genkit לייצא נתוני טלמטריה ונתוני יומנים כשהיא פועלת בסביבה dev (למשל, באופן מקומי).

דוגם צלילים

במקרים שבהם לא מעשי לייצא את כל הטראסים, OpenTelemetry מאפשר דגימה של טראסים.

יש ארבעה Samplers מוגדרים מראש:

autoInstrumentation ו-autoInstrumentationConfig

הפעלת הכלי למדידת ביצועים מאפשרת ל-OpenTelemetry לתעד נתוני טלמטריה מספריות של צד שלישי בלי צורך לשנות את הקוד.

metricsExportInterval

השדה הזה מציין את מרווח הזמן לייצוא מדדים באלפיות השנייה.

בדיקת השילוב

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

מעקב אחרי ייצור באמצעות חבילת התפעול של Google Cloud

אחרי שפורסים תהליך, נכנסים לחבילת התפעול של Google Cloud ובוחרים את הפרויקט.

יומנים ומעקב

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

יוצגו כל היומנים שמשויכים לתהליך הפריסה, כולל console.log(). כל יומן עם הקידומת [genkit] הוא יומן פנימי של Genkit שמכיל מידע שעשוי לעניין אותך למטרות ניפוי באגים. לדוגמה, יומני Genkit בפורמט Config[...] מכילים מטא-נתונים כמו הטמפרטורה וערכים של topK להסקות ספציפיות של LLM. יומנים בפורמט Output[...] מכילים תגובות LLM, בעוד שיומנים בפורמט Input[...] מכילים את ההנחיות. ל-Cloud Logging יש רשימות ACL חזקות שמאפשרות שליטה פרטנית ביומנים רגישים.

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

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

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

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

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

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

מדדים

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

מסוף ניהול המדדים מכיל טבלה של כל המדדים שנאספו, כולל מדדים שקשורים ל-Cloud Run ולסביבה שלו. לחיצה על האפשרות 'עומס עבודה' תציג רשימה שכוללת מדדים שנאספו על ידי Genkit. כל מדד עם הקידומת genkit מגדיר מדד פנימי של Genkit.

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

מאפיינים נפוצים כוללים:

  • flow_name - השם ברמה העליונה של התהליך.
  • flow_path - ה-span ושרשרת ההורה שלו עד לטווח השורש.
  • error_code – במקרה של שגיאה, קוד השגיאה התואם.
  • error_message – במקרה של שגיאה, הודעת השגיאה המתאימה.
  • model – שם הדגם.
  • temperature – טמפרטורת ההסקה value.
  • topK – הערך של topK של ההסקה.
  • topP - ערך ההיקש העליון.

מדדים ברמת הזרימה

שם מאפיינים
genkit/flow/requests flow_name,‏ error_code,‏ error_message
genkit/flow/latency flow_name

מדדים ברמת הפעולה

שם מאפיינים
genkit/פעולה/בקשות traffic_name, error_code, error_message
Genkit/פעולה/זמן אחזור שם_זרימה

מדדים ברמת היצירה

שם מאפיינים
genkit/ai/generate flow_path, מודל, טמפרטורה, topK, topP, error_code, error_message
genkit/ai/generate/input_tokens traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/output_tokens traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/input_characters flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/output_characters traffic_path, מודל, טמפרטורה, topK, topP
genkit/ai/generate/input_images flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/output_images flow_path,‏ model,‏ temperature,‏ topK,‏ topP
genkit/ai/generate/latency flow_path,‏ model,‏ temperature,‏ topK,‏ topP,‏ error_code,‏ error_message

אפשר להציג את המדדים באופן חזותי באמצעות Metrics Explorer. באמצעות תפריט הצד, בוחרים באפשרות 'רישום ביומן' ולוחצים על 'Metrics Explorer'.

כדי לבחור מדד, לוחצים על התפריט הנפתח 'בחירת מדד', בוחרים באפשרות 'Generic Node' (צומת גנרי), 'Genkit' (Genkit) ומדד.

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

זמן אחזור של טלמטריה

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

מכסות ומגבלות

יש כמה מכסות שחשוב לזכור:

עלות

ל-Cloud Logging, ל-Cloud Trace ול-Cloud Monitoring יש רמות חינמיות נדיבות. אפשר למצוא מחירים ספציפיים בקישורים הבאים: