Google Cloud प्लगिन

Google Cloud प्लग इन, Firebase Genkit के टेलीमेट्री और लॉगिंग डेटा को Cloud Observability सुइट में एक्सपोर्ट करता है. यह सुइट, Firebase एआई मॉनिटरिंग डैशबोर्ड को बेहतर बनाता है.

इंस्टॉल करना

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

इस प्लगिन वाले Genkit कोड को लोकल तौर पर चलाने के लिए, आपको Google Cloud CLI टूल भी इंस्टॉल करना होगा.

Google Cloud खाता सेट अप करना

इस प्लग इन के लिए, Google Cloud खाता/प्रोजेक्ट होना ज़रूरी है. सभी Firebase प्रोजेक्ट में डिफ़ॉल्ट रूप से एक (GCP Console) शामिल होता है. इसके अलावा, https://cloud.google.com पर जाकर भी साइन अप किया जा सकता है.

प्लग इन जोड़ने से पहले, पक्का करें कि आपके GCP प्रोजेक्ट के लिए ये एपीआई चालू हों:

ये एपीआई, आपके प्रोजेक्ट के लिए एपीआई डैशबोर्ड में मौजूद होने चाहिए.

एपीआई चालू और बंद करने के बारे में ज़्यादा जानने के लिए, यहां क्लिक करें.

Genkit कॉन्फ़िगरेशन

क्लाउड ट्रैकिंग, लॉगिंग, और मॉनिटरिंग (मेट्रिक) की सुविधा चालू करने के लिए, enableGoogleCloudTelemetry() को कॉल करें:

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

enableGoogleCloudTelemetry();

प्रोडक्शन में चलने पर, टेलीमेट्री अपने-आप एक्सपोर्ट हो जाएगी.

पुष्टि करना और अनुमति देना

प्लग इन के लिए, Google Cloud प्रोजेक्ट आईडी और ऐप्लिकेशन क्रेडेंशियल की ज़रूरत होती है.

Google Cloud

अगर Google Cloud के किसी एनवायरमेंट (Cloud Functions, Cloud Run वगैरह) में अपना कोड डिप्लॉय किया जा रहा है, तो ऐप्लिकेशन के लिए डिफ़ॉल्ट क्रेडेंशियल की मदद से, प्रोजेक्ट आईडी और क्रेडेंशियल अपने-आप मिल जाएंगे.

आपको IAM Console के ज़रिए, उस सेवा खाते पर ये भूमिकाएं लागू करनी होंगी जो आपका कोड चला रहा है. जैसे, 'अटैच किया गया सेवा खाता':

  • roles/monitoring.metricWriter
  • roles/cloudtrace.agent
  • roles/logging.logWriter

लोकल डेवलपमेंट

स्थानीय डेवलपमेंट करते समय, प्लग इन के लिए उपयोगकर्ता के क्रेडेंशियल उपलब्ध कराने के लिए, कुछ और चरण पूरे करने होंगे.

  1. अपने Google Cloud प्रोजेक्ट में GCLOUD_PROJECT एनवायरमेंट वैरिएबल सेट करें.

  2. gcloud CLI का इस्तेमाल करके पुष्टि करना:

    gcloud auth application-default login

Google Cloud से बाहर के प्रोडक्शन एनवायरमेंट

अगर हो सके, तो प्लग इन के लिए क्रेडेंशियल उपलब्ध कराने के लिए, ऐप्लिकेशन के लिए डिफ़ॉल्ट क्रेडेंशियल की प्रोसेस का फ़ायदा लें.

आम तौर पर, इसमें सेवा खाते की कुंजी/जोड़ी जनरेट करना और उन क्रेडेंशियल को अपने प्रोडक्शन एनवायरमेंट में डिप्लॉय करना शामिल होता है.

  1. सेवा खाते की कुंजी सेट अप करने के लिए, निर्देशों का पालन करें.

  2. पक्का करें कि सेवा खाते के पास ये भूमिकाएं हों:

    • roles/monitoring.metricWriter
    • roles/cloudtrace.agent
    • roles/logging.logWriter

  3. क्रेडेंशियल फ़ाइल को प्रोडक्शन में डिप्लॉय करें (सोर्स कोड में शामिल न करें)

  4. GOOGLE_APPLICATION_CREDENTIALS एनवायरमेंट वैरिएबल को क्रेडेंशियल फ़ाइल के पाथ के तौर पर सेट करें.

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

कुछ सर्वरलेस एनवायरमेंट में, हो सकता है कि आप क्रेडेंशियल वाली फ़ाइल को डिप्लॉय न कर पाएं. इस मामले में, ऊपर दिए गए तीसरे और चौथे चरण के बजाय, क्रेडेंशियल फ़ाइल के कॉन्टेंट के साथ GCLOUD_SERVICE_ACCOUNT_CREDS एनवायरमेंट वैरिएबल को इस तरह सेट किया जा सकता है:

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"
}'

प्लग इन का कॉन्फ़िगरेशन

enableGoogleCloudTelemetry() फ़ंक्शन, एक वैकल्पिक कॉन्फ़िगरेशन ऑब्जेक्ट लेता है, जो OpenTelemetry NodeSDK इंस्टेंस को कॉन्फ़िगर करता है.

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

enableGoogleCloudTelemetry({
  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,
});

कॉन्फ़िगरेशन ऑब्जेक्ट की मदद से, टेलीमेट्री एक्सपोर्ट के अलग-अलग पहलुओं को बेहतर तरीके से कंट्रोल किया जा सकता है. इन पहलुओं के बारे में यहां बताया गया है.

क्रेडेंशियल

Google-auth लाइब्रेरी से, JWTInput का इस्तेमाल करके, सीधे क्रेडेंशियल डालने की अनुमति देता है.

सैंपलर

जिन मामलों में सभी ट्रेस एक्सपोर्ट करना मुमकिन नहीं है वहां OpenTelemetry, ट्रेस के सैंपलिंग की सुविधा देता है.

पहले से कॉन्फ़िगर किए गए चार सैंपलर होते हैं:

  • AlwaysOnSampler - सभी ट्रेस का सैंपल लेता है
  • AlwaysOffSampler - कोई डेटा सेव नहीं करता
  • ParentBased - पैरंट स्पैन के आधार पर सैंपल
  • TraceIdRatioBased - यह ट्रैस का कॉन्फ़िगर किया जा सकने वाला प्रतिशत सैंपल करता है

autoInstrumentation और autoInstrumentationConfig

अपने-आप इंस्ट्रूमेंटेशन चालू करने पर, OpenTelemetry को कोड में बदलाव किए बिना, तीसरे पक्ष की लाइब्रेरी से टेलीमेट्री डेटा कैप्चर करने की अनुमति मिलती है.

metricExportIntervalMillis

इस फ़ील्ड में, मेट्रिक एक्सपोर्ट इंटरवल को मिलीसेकंड में बताया जाता है.

metricExportTimeoutMillis

इस फ़ील्ड में, मेट्रिक एक्सपोर्ट के लिए मिलीसेकंड में टाइम आउट तय किया जाता है.

disableMetrics

यह एक बदलाव है, जो मेट्रिक एक्सपोर्ट करने की सुविधा को बंद कर देता है. हालांकि, इससे ट्रेस और लॉग एक्सपोर्ट होते रहते हैं.

disableTraces

यह एक बदलाव है, जो मेट्रिक और लॉग एक्सपोर्ट करते समय, ट्रेस एक्सपोर्ट करने की सुविधा बंद कर देता है.

disableLoggingIO

इनपुट और आउटपुट लॉग इकट्ठा करने की सुविधा बंद करने के लिए, बदलाव करने का विकल्प देता है.

forceDevExport

इस विकल्प की मदद से, Genkit को dev एनवायरमेंट (जैसे, स्थानीय तौर पर) में चलने के दौरान, टेलीमेट्री और लॉग डेटा को एक्सपोर्ट करने के लिए मजबूर किया जाएगा.

अपने इंटिग्रेशन की जांच करना

प्लग इन को कॉन्फ़िगर करते समय, forceDevExport: true का इस्तेमाल करके, लोकल रन के लिए टेलीमेट्री एक्सपोर्ट की सुविधा चालू करें. टेलीमेट्री देखने के लिए, Google Cloud के लॉग, मेट्रिक या Trace Explorer पर जाएं.

Google Cloud का ऑब्ज़र्वेबिलिटी सुइट

कोड (उदाहरण के लिए, फ़्लो) डिप्लॉय होने के बाद, क्लाउड मॉनिटरिंग डैशबोर्ड पर जाएं और अपना प्रोजेक्ट चुनें. यहां से, प्रोडक्शन मॉनिटरिंग के लिए, लॉग, मेट्रिक, और ट्रेस एक्सप्लोरर के बीच आसानी से नेविगेट किया जा सकता है.

लॉग और ट्रेस

बाईं ओर मौजूद मेन्यू में, 'एक्सप्लोर करें' हेडिंग में जाकर, 'लॉग एक्सप्लोरर' पर क्लिक करें.

यहां आपको डिप्लॉय किए गए Genkit कोड से जुड़े सभी लॉग दिखेंगे. इनमें console.log() भी शामिल है. [genkit] प्रीफ़िक्स वाला कोई भी लॉग, Genkit का इंटरनल लॉग होता है. इसमें ऐसी जानकारी होती है जो डीबग करने के लिए काम की हो सकती है. उदाहरण के लिए, Config[...] फ़ॉर्मैट में Genkit लॉग में, LLM के खास अनुमान के लिए, तापमान और टॉपK वैल्यू जैसी मेटाडेटा होती है. Output[...] फ़ॉर्मैट में मौजूद लॉग में LLM के जवाब होते हैं, जबकि Input[...] लॉग में प्रॉम्प्ट होते हैं. Cloud Logging में बेहतर ACLs हैं, जिनकी मदद से संवेदनशील लॉग के ऐक्सेस को बेहतर तरीके से कंट्रोल किया जा सकता है.

इससे, ट्रैक की झलक दिखाने वाला पैनल खुलेगा. इसमें, ट्रैक की जानकारी एक नज़र में देखी जा सकती है. पूरी जानकारी पाने के लिए, पैनल के सबसे ऊपर दाईं ओर मौजूद, "ट्रेस में देखें" लिंक पर क्लिक करें.

Cloud Trace में सबसे अहम नेविगेशन एलिमेंट, ट्रेस स्कैटर प्लॉट है. इसमें किसी तय समयावधि में इकट्ठा किए गए सभी ट्रेस शामिल होते हैं.

हर डेटा पॉइंट पर क्लिक करने से, स्कैटर प्लॉट के नीचे उसकी जानकारी दिखेगी.

ज़्यादा जानकारी वाले व्यू में, फ़्लो का आकार दिखता है. इसमें सभी चरणों के साथ-साथ, समय से जुड़ी अहम जानकारी भी दिखती है. Cloud Trace में, इस व्यू में किसी ट्रेस से जुड़े सभी लॉग को इंटरलीव करने की सुविधा होती है. "लॉग और इवेंट" ड्रॉप-डाउन में, "बड़ा करके दिखाएं" विकल्प चुनें.

इस व्यू की मदद से, ट्रैस के संदर्भ में लॉग की पूरी जांच की जा सकती है. इसमें प्रॉम्प्ट और एलएलएम के जवाब भी शामिल हैं.

मेट्रिक

Genkit की मदद से एक्सपोर्ट की गई सभी मेट्रिक देखने के लिए, बाईं ओर मौजूद मेन्यू में 'कॉन्फ़िगर करें' सेक्शन में जाकर, 'मेट्रिक मैनेजमेंट' पर क्लिक करें.

मेट्रिक मैनेजमेंट कंसोल में, इकट्ठा की गई सभी मेट्रिक का टेबल व्यू होता है. इसमें Cloud Run और उसके आस-पास के एनवायरमेंट से जुड़ी मेट्रिक भी शामिल होती हैं. 'वर्कलोड' विकल्प पर क्लिक करने से, एक सूची दिखेगी. इसमें Genkit से इकट्ठा की गई मेट्रिक शामिल होंगी. genkit प्रीफ़िक्स वाली कोई भी मेट्रिक, एक इंटरनल Genkit मेट्रिक होती है.

Genkit, मेट्रिक की कई कैटगरी इकट्ठा करता है. इनमें ये शामिल हैं: सुविधा, कार्रवाई, और जनरेट. हर मेट्रिक में कई काम के डाइमेंशन होते हैं, जिनकी मदद से बेहतर फ़िल्टरिंग और ग्रुपिंग की जा सकती है.

आम तौर पर इस्तेमाल होने वाले डाइमेंशन में ये शामिल हैं:

  • flow_name - फ़्लो का टॉप-लेवल नाम.
  • flow_path - स्पैन और उसके पैरंट स्पैन, रूट स्पैन तक चेन बनाते हैं.
  • error_code - गड़बड़ी होने पर, गड़बड़ी का कोड.
  • error_message - गड़बड़ी होने पर, गड़बड़ी का मैसेज.
  • model - मॉडल का नाम.

सुविधा की मेट्रिक

सुविधाएं, आपके Genkit कोड के टॉप-लेवल एंट्री-पॉइंट हैं. ज़्यादातर मामलों में, यह एक फ़्लो होगा. ऐसा न करने पर, यह ट्रैस में सबसे ऊपर वाला स्पैन होगा.

नाम टाइप ब्यौरा
genkit/feature/requests काउंटर कुल अनुरोध
genkit/feature/latency हिस्टोग्राम एक्सीक्यूशन में लगने वाला समय, मिलीसेकंड में

हर सुविधा मेट्रिक में ये डाइमेंशन शामिल होते हैं:

नाम ब्यौरा
नाम सुविधा का नाम. ज़्यादातर मामलों में, यह Genkit का टॉप-लेवल फ़्लो होता है
स्थिति 'सफल' या 'असफल'. यह इस बात पर निर्भर करता है कि सुविधा के अनुरोध को स्वीकार किया गया है या नहीं
गड़बड़ी सिर्फ़ तब सेट करें, जब status=failure. इसमें गड़बड़ी का टाइप शामिल होता है, जिसकी वजह से अनुरोध पूरा नहीं हो पाया
source Genkit की सोर्स भाषा. उदाहरण के लिए, 'ts'
sourceVersion Genkit फ़्रेमवर्क का वर्शन

ऐक्शन मेट्रिक

ऐक्शन, Genkit में प्रोसेस को लागू करने का एक सामान्य चरण दिखाते हैं. इनमें से हर चरण में, ये मेट्रिक ट्रैक की जाएंगी:

नाम टाइप ब्यौरा
genkit/action/requests काउंटर यह कार्रवाई कितनी बार की गई
genkit/action/latency हिस्टोग्राम एक्सीक्यूशन में लगने वाला समय, मिलीसेकंड में

हर ऐक्शन मेट्रिक में ये डाइमेंशन होते हैं:

नाम ब्यौरा
नाम कार्रवाई का नाम
featureName जिस पैरंट सुविधा को लागू किया जा रहा है उसका नाम
पाथ सुविधा के रूट से इस कार्रवाई तक, प्रोसेस को पूरा करने का पाथ. उदाहरण के लिए, '/myFeature/parentAction/thisAction'
स्थिति 'सफल' या 'असफल', यह इस बात पर निर्भर करता है कि कार्रवाई पूरी हुई या नहीं
गड़बड़ी सिर्फ़ तब सेट करें, जब status=failure. इसमें गड़बड़ी का टाइप शामिल होता है, जिसकी वजह से अनुरोध पूरा नहीं हो पाया
source Genkit की सोर्स भाषा. उदाहरण के लिए, 'ts'
sourceVersion Genkit फ़्रेमवर्क का वर्शन

मेट्रिक जनरेट करना

ये खास ऐक्शन मेट्रिक, मॉडल के साथ इंटरैक्ट करने वाली कार्रवाइयों से जुड़ी होती हैं. अनुरोधों और इंतज़ार के समय के अलावा, इनपुट और आउटपुट को भी ट्रैक किया जाता है. इसके लिए, मॉडल के हिसाब से डाइमेंशन का इस्तेमाल किया जाता है. इससे, डीबग करने और कॉन्फ़िगरेशन को ट्यून करने में आसानी होती है.

नाम टाइप ब्यौरा
genkit/ai/generate/requests काउंटर इस मॉडल को कॉल किए जाने की संख्या
genkit/ai/generate/latency हिस्टोग्राम एक्सीक्यूशन में लगने वाला समय, मिलीसेकंड में
genkit/ai/generate/input/tokens काउंटर इनपुट टोकन
genkit/ai/generate/output/tokens काउंटर आउटपुट टोकन
genkit/ai/generate/input/characters काउंटर वर्ण डालें
genkit/ai/generate/output/characters काउंटर आउटपुट वर्ण
genkit/ai/generate/input/images काउंटर इनपुट इमेज
genkit/ai/generate/output/images काउंटर आउटपुट इमेज
genkit/ai/generate/input/audio काउंटर ऑडियो फ़ाइलें डालना
genkit/ai/generate/output/audio काउंटर ऑडियो फ़ाइलें आउटपुट करना

जनरेट की गई हर मेट्रिक में ये डाइमेंशन शामिल होते हैं:

नाम ब्यौरा
modelName मॉडल का नाम
featureName जिस पैरंट सुविधा को लागू किया जा रहा है उसका नाम
पाथ सुविधा के रूट से इस कार्रवाई तक, प्रोसेस को पूरा करने का पाथ. उदाहरण के लिए, '/myFeature/parentAction/thisAction'
latencyMs मॉडल को जवाब देने में लगने वाला समय
स्थिति 'सफल' या 'असफल'. यह इस बात पर निर्भर करता है कि सुविधा के अनुरोध को स्वीकार किया गया है या नहीं
गड़बड़ी सिर्फ़ तब सेट करें, जब status=failure. इसमें गड़बड़ी का टाइप शामिल होता है, जिसकी वजह से अनुरोध पूरा नहीं हो पाया
source Genkit की सोर्स भाषा. उदाहरण के लिए, 'ts'
sourceVersion Genkit फ़्रेमवर्क का वर्शन

मेट्रिक को विज़ुअलाइज़ करने के लिए, मेट्रिक एक्सप्लोरर का इस्तेमाल किया जा सकता है. बाईं ओर मौजूद मेन्यू का इस्तेमाल करके, 'एक्सप्लोर करें' हेडिंग में जाकर, 'मेट्रिक एक्सप्लोरर' पर क्लिक करें.

'कोई मेट्रिक चुनें' ड्रॉपडाउन पर क्लिक करके, कोई मेट्रिक चुनें. इसके बाद, 'सामान्य नोड', 'Genkit', और कोई मेट्रिक चुनें.

मेट्रिक का विज़ुअलाइज़ेशन, उसके टाइप (काउंटर, हिस्टोग्राम वगैरह) पर निर्भर करेगा. मेट्रिक एक्सप्लोरर, मेट्रिक को उनके अलग-अलग डाइमेंशन के हिसाब से ग्राफ़ में दिखाने के लिए, एग्रीगेशन और क्वेरी करने की बेहतर सुविधाएं देता है.

टेलीमेट्री में देरी

किसी फ़्लो के किसी खास रन के लिए, टेलीमेट्री को Cloud के ऑपरेशंस सुइट में दिखने में थोड़ी देर लग सकती है. ज़्यादातर मामलों में, यह समय एक मिनट से कम होता है.

कोटा और सीमाएं

कुछ कोटा ऐसे हैं जिन्हें ध्यान में रखना ज़रूरी है:

लागत

Cloud Logging, Cloud Trace, और Cloud Monitoring के लिए, मुफ़्त में इस्तेमाल किए जा सकने वाले टियर उपलब्ध हैं. अलग-अलग कीमतों के बारे में जानने के लिए, इन लिंक पर जाएं: