افزونه Google Cloud

افزونه Google Cloud داده های تله متری و ثبت نام Firebase Genkit را به مجموعه عملیات Google Cloud صادر می کند.

توجه: ورود به سیستم توسط وینستون به نفع APIهای گزارش گیری OpenTelemetry تسهیل می شود. صادرات گزارش ها از طریق یک صادرکننده اختصاصی Winston Google Cloud انجام می شود.

نصب و راه اندازی

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

اگر می‌خواهید جریان‌هایی را که از این افزونه استفاده می‌کنند به صورت محلی اجرا کنید، باید ابزار Google Cloud CLI را نیز نصب کنید.

یک حساب Google Cloud راه اندازی کنید

این افزونه به یک حساب Google Cloud (اگر قبلاً ندارید ثبت نام کنید ) و یک پروژه Google Cloud نیاز دارد.

قبل از افزودن افزونه، مطمئن شوید که API های زیر برای پروژه شما فعال هستند:

• Cloud Logging API
• Cloud Trace API
• Cloud Monitoring 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، Cloud Run و غیره)، شناسه پروژه و اعتبارنامه ها به طور خودکار تنظیم می شوند.

اعتبار پیش فرض برنامه

اجرای در محیط‌های دیگر مستلزم تنظیم متغیر محیطی GCLOUD_PROJECT برای پروژه Google Cloud و احراز هویت با استفاده از ابزار gcloud است:

gcloud auth application-default login

برای اطلاعات بیشتر، به اسناد اعتبار پیش فرض برنامه مراجعه کنید.

اعتبار حساب خدمات

اگر از یک حساب سرویس استفاده می کنید و خارج از محیط Google Cloud اجرا می کنید، می توانید اعتبار خود را به عنوان یک متغیر محیطی تنظیم کنید. دستورالعمل‌های اینجا را دنبال کنید تا کلید حساب Google Cloud Service خود را تنظیم کنید .

هنگامی که فایل کلید را دانلود کردید، می توانید اعتبارنامه را به دو صورت یک مکان فایل با استفاده از متغیر محیطی 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
}

شناسه پروژه

این گزینه اجازه می دهد تا شناسه پروژه 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 اجازه نمونه برداری از ردیابی را می دهد.

چهار نمونه از پیش تنظیم شده وجود دارد:

• AlwaysOnSampler - از همه ردیابی ها نمونه برداری می کند
• AlwaysOffSampler - نمونه برداری بدون ردیابی
• ParentBased - نمونه‌ها بر اساس فاصله والدین
• TraceIdRatioBased - درصد قابل تنظیمی از ردیابی ها را نمونه برداری می کند

autoInstrumentation & autoInstrumentationConfig

فعال کردن ابزار دقیق خودکار به OpenTelemetry اجازه می دهد تا داده های تله متری را از کتابخانه های شخص ثالث بدون نیاز به تغییر کد ضبط کند.

metricsExportInterval

این فیلد فاصله صادرات معیارها را بر حسب میلی ثانیه مشخص می کند.

توجه: حداقل فاصله صادرات برای Google Cloud Monitoring 5000 میلی‌ثانیه است.

ادغام خود را تست کنید

هنگام پیکربندی افزونه، از forceDevExport: true برای فعال کردن صادرات تله متری برای اجراهای محلی استفاده کنید. این یک راه سریع برای ارسال اولین رویدادهای شما برای نظارت در Google Cloud است.

نظارت بر تولید از طریق مجموعه عملیات Google Cloud

پس از اجرای یک جریان، به مجموعه عملیات Google Cloud بروید و پروژه خود را انتخاب کنید.

سیاههها و آثار

از منوی کناری، "Logging" را پیدا کنید و روی "Logs explorer" کلیک کنید.

شما همه گزارش‌هایی را که با جریان مستقر شما مرتبط هستند، از جمله console.log() را مشاهده خواهید کرد. هر گزارشی که دارای پیشوند [genkit] باشد یک گزارش داخلی Genkit است که حاوی اطلاعاتی است که ممکن است برای اهداف اشکال زدایی جالب باشد. برای مثال، گزارش‌های Genkit در قالب Config[...] حاوی ابرداده‌هایی مانند دما و مقادیر topK برای استنتاج‌های خاص LLM هستند. گزارش‌ها در قالب Output[...] حاوی پاسخ‌های LLM هستند در حالی که گزارش‌های Input[...] حاوی اعلان‌ها هستند. Cloud Logging دارای ACL های قوی است که امکان کنترل دقیق روی گزارش های حساس را فراهم می کند.

توجه: درخواست‌ها و پاسخ‌های LLM از ویژگی‌های ردیابی در Cloud Trace حذف می‌شوند.

برای خطوط گزارش خاص، می‌توانید با کلیک بر روی منوی توسعه‌یافته، به دنباله‌های مربوطه بروید. نماد و انتخاب "مشاهده در جزئیات ردیابی".

این یک صفحه پیش نمایش ردیابی را نشان می دهد که یک نگاه سریع به جزئیات ردیابی ارائه می دهد. برای دسترسی به جزئیات کامل، روی پیوند "View in Trace" در سمت راست بالای صفحه کلیک کنید.

برجسته ترین عنصر ناوبری در Cloud Trace نمودار پراکندگی ردیابی است. این شامل تمام آثار جمع آوری شده در یک بازه زمانی معین است.

با کلیک بر روی هر نقطه داده، جزئیات آن در زیر نمودار پراکندگی نشان داده می شود.

نمای دقیق شامل شکل جریان، از جمله تمام مراحل، و اطلاعات مهم زمان بندی است. Cloud Trace این قابلیت را دارد که همه گزارش‌های مرتبط با یک ردیابی معین را در این نما به هم متصل کند. در منوی کشویی «Logs & Events» گزینه «Show expanded» را انتخاب کنید.

نمای حاصل امکان بررسی دقیق گزارش‌ها را در زمینه ردیابی، از جمله درخواست‌ها و پاسخ‌های LLM فراهم می‌کند.

معیارها

مشاهده تمام معیارهایی که Genkit صادر می کند با انتخاب "Logging" از منوی کناری و کلیک بر روی "Metrics Management" امکان پذیر است.

کنسول مدیریت متریک شامل نمای جدولی از تمام معیارهای جمع آوری شده، از جمله مواردی است که مربوط به Cloud Run و محیط اطراف آن است. با کلیک بر روی گزینه "Workload" لیستی نشان داده می شود که شامل معیارهای جمع آوری شده توسط Genkit است. هر متریک با پیشوند genkit یک معیار Genkit داخلی را تشکیل می دهد.

Genkit چندین دسته از معیارها را جمع آوری می کند، از جمله معیارهای سطح جریان، سطح عمل و سطح تولید. هر معیار دارای چندین بعد مفید است که فیلتر کردن و گروه بندی قوی را تسهیل می کند.

ابعاد متداول عبارتند از:

• flow_name - نام سطح بالای جریان.
• flow_path - دهانه و زنجیره دهانه والد آن تا دهانه ریشه.
• error_code - در صورت بروز خطا، کد خطای مربوطه.
• error_message - در صورت بروز خطا، پیام خطای مربوطه.
• model - نام مدل.
• temperature - مقدار دمای استنتاج.
• topK - مقدار topK استنتاج.
• topP - مقدار topP استنتاج.

معیارهای سطح جریان

نام	ابعاد
genkit/flow/درخواستها	flow_name، error_code، error_message
genkit/flow/latency	flow_name

معیارهای سطح اقدام

نام	ابعاد
جنکیت/عمل/درخواست	flow_name، error_code، error_message
genkit/action/latency	flow_name

معیارهای سطح تولید کنید

نام	ابعاد
genkit/ai/generate	flow_path، مدل، دما، topK، topP، error_code، error_message
genkit/ai/generate/input_tokens	flow_path، مدل، دما، topK، topP
genkit/ai/generate/output_tokens	flow_path، مدل، دما، topK، topP
genkit/ai/generate/input_characters	flow_path، مدل، دما، topK، topP
genkit/ai/generate/output_characters	flow_path، مدل، دما، topK، topP
genkit/ai/generate/input_images	flow_path، مدل، دما، topK، topP
genkit/ai/generate/output_images	flow_path، مدل، دما، topK، topP
genkit/ai/generate/latency	flow_path، مدل، دما، topK، topP، error_code، error_message

تجسم معیارها را می توان از طریق Metrics Explorer انجام داد. با استفاده از منوی کناری، "Logging" را انتخاب کنید و روی "Metrics Explorer" کلیک کنید.

با کلیک بر روی منوی کرکره‌ای «انتخاب معیار»، انتخاب «گره عمومی»، «Genkit» و یک معیار، یک معیار را انتخاب کنید.

تجسم متریک به نوع آن (شمارگر، هیستوگرام و غیره) بستگی دارد. Metrics Explorer امکانات جمع آوری و پرس و جو قوی را برای کمک به نمودارهای معیارها بر اساس ابعاد مختلف آنها فراهم می کند.

تاخیر در تله متری

ممکن است قبل از نمایش تله متری برای اجرای خاصی از یک جریان در مجموعه عملیات Cloud کمی تأخیر وجود داشته باشد. در بیشتر موارد، این تاخیر کمتر از 1 دقیقه است.

سهمیه ها و محدودیت ها

چند سهمیه وجود دارد که باید در نظر داشت:

• سهمیه های Cloud Trace
  • 128 بایت در هر کلید ویژگی
  • 256 بایت در هر مقدار مشخصه
• سهمیه های ثبت ابر
  • 256 کیلوبایت در هر ورودی گزارش
• سهمیه مانیتورینگ ابری

هزینه

Cloud Logging، Cloud Trace و Cloud Monitoring دارای سطوح رایگان سخاوتمندانه ای هستند. قیمت های ویژه را می توانید در لینک های زیر مشاهده کنید:

• قیمت گذاری Cloud Logging
• قیمت گذاری Cloud Trace
• قیمت گذاری مانیتورینگ ابری