Google Cloud eklentisi

Google Cloud eklentisi, Firebase Genkit telemetri ve günlük kaydı verilerini Firebase AI Monitoring kontrol panelini destekleyen Cloud Observability paketine aktarır.

Kurulum

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

Bu eklentiyi içeren Genkit kodunu yerel olarak çalıştırırken Google Cloud CLI aracının da yüklü olması gerekir.

Google Cloud hesabı oluşturma

Bu eklenti için bir Google Cloud hesabı/projesi gerekir. Tüm Firebase projeleri varsayılan olarak bir tane içerir (GCP Console) veya https://cloud.google.com adresinden kaydolabilirsiniz.

Eklentiyi eklemeden önce GCP projeniz için aşağıdaki API'lerin etkinleştirildiğinden emin olun:

Bu API'ler, projenizin API kontrol panelinde listelenmelidir.

API'leri etkinleştirme ve devre dışı bırakma hakkında daha fazla bilgi edinmek için burayı tıklayın.

Genkit yapılandırması

Cloud Tracing, Logging ve Monitoring'i (metrikler) etkinleştirmek için enableGoogleCloudTelemetry() işlevini çağırmanız yeterlidir:

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

enableGoogleCloudTelemetry();

Üretimde çalışırken telemetri otomatik olarak dışa aktarılır.

Kimlik doğrulama ve yetkilendirme

Eklenti için bir Google Cloud proje kimliği ve uygulama kimlik bilgileri gerekir.

Google Cloud

Kodunuzu bir Google Cloud ortamına (Cloud Functions, Cloud Run vb.) dağıtıyorsanız proje kimliği ve kimlik bilgileri Uygulama Varsayılan Kimlik Bilgileri aracılığıyla otomatik olarak bulunur.

IAM Konsolu üzerinden, kodunuzu çalıştıran hizmet hesabına ("bağlı hizmet hesabı") aşağıdaki rolleri uygulamanız gerekir:

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

Yerel Geliştirme

Yerel geliştirme yaparken kullanıcı kimlik bilgilerinizin eklentiye erişebilmesi için ek adımlar gerekir.

  1. GCLOUD_PROJECT ortam değişkenini Google Cloud projenize ayarlayın.

  2. gcloud KSA'yı kullanarak kimlik doğrulama:

    gcloud auth application-default login

Google Cloud dışındaki üretim ortamları

Mümkünse kimlik bilgilerini eklentiye sunmak için Uygulama Varsayılan Kimlik Bilgileri sürecinden yararlanmanız önerilir.

Bu genellikle bir hizmet hesabı anahtarı/çift oluşturmayı ve bu kimlik bilgilerini üretim ortamınıza dağıtmayı içerir.

  1. Hizmet hesabı anahtarı oluşturma talimatlarını uygulayın.

  2. Hizmet hesabının aşağıdaki rollere sahip olduğundan emin olun:

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

  3. Kimlik bilgisi dosyasını üretime dağıtın (kaynak koda kaydetmeyin)

  4. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini, kimlik bilgisi dosyasının yolu olarak ayarlayın.

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

Bazı sunucusuz ortamlarda kimlik bilgisi dosyası dağıtamayabilirsiniz. Bu durumda, yukarıdaki 3. ve 4. adımlara alternatif olarak GCLOUD_SERVICE_ACCOUNT_CREDS ortam değişkenini, aşağıdaki gibi kimlik bilgisi dosyasının içeriğiyle ayarlayabilirsiniz:

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

Eklenti yapılandırması

enableGoogleCloudTelemetry() işlevi, OpenTelemetry NodeSDK örneğini yapılandıran isteğe bağlı bir yapılandırma nesnesi alır.

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

Yapılandırma nesneleri, aşağıda açıklanan telemetri dışa aktarma işleminin çeşitli yönleri üzerinde ayrıntılı kontrol sağlar.

credentials

google-auth kitaplığındaki JWTInput kullanılarak kimlik bilgilerinin doğrudan belirtilmesine olanak tanır.

örnekleyici

Tüm izlemelerin dışa aktarılmasının uygun olmadığı durumlarda OpenTelemetry, izleme örnekleme yapılmasına olanak tanır.

Dört önceden yapılandırılmış örnekleyici vardır:

autoInstrumentation ve autoInstrumentationConfig

Otomatik enstrümantasyonu etkinleştirmek, OpenTelemetry'nin kodda değişiklik yapmadan üçüncü taraf kitaplıklarından telemetri verileri yakalamasına olanak tanır.

metricExportIntervalMillis

Bu alan, milisaniye cinsinden metrik dışa aktarma aralığını belirtir.

metricExportTimeoutMillis

Bu alan, metrik dışa aktarma işleminin zaman aşım süresini milisaniye cinsinden belirtir.

disableMetrics

İzler ve günlükler dışa aktarılırken metrikleri dışa aktarmayı devre dışı bırakan bir geçersiz kılma sağlar.

disableTraces

Metrikleri ve günlükleri dışa aktarırken izlerin dışa aktarılmasını devre dışı bırakan bir geçersiz kılma sağlar.

disableLoggingIO

Giriş ve çıkış günlüklerinin toplanmasını devre dışı bırakan bir geçersiz kılma sağlar.

forceDevExport

Bu seçenek, Genkit'i dev ortamında (ör. yerel olarak) çalışırken telemetri ve günlük verilerini dışa aktarmaya zorlar.

Entegrasyonunuzu test etme

Eklentiyi yapılandırırken yerel çalıştırmalar için telemetri dışa aktarma özelliğini etkinleştirmek üzere forceDevExport: true simgesini kullanın. Telemetriyi görüntülemek için Google Cloud Logs, Metrics veya Trace Explorer'a gidin.

Google Cloud Gözlemlenebilirlik paketi

Kodunuz (ör. akış) dağıtıldıktan sonra Cloud Monitoring kontrol paneline gidin ve projenizi seçin. Buradan, üretim izleme için Günlük, Metrikler ve İzleme keşifleri arasında kolayca gezinebilirsiniz.

Günlükler ve izler

Sol taraftaki menüde "Keşfet" başlığı altında "Günlük gezgini"ni tıklayın.

Burada, dağıtılan Genkit kodunuzla ilişkili tüm günlükleri (console.log() dahil) görürsünüz. [genkit] ön ekiyle başlayan tüm günlükler, hata ayıklama amacıyla ilgi çekici olabilecek bilgiler içeren Genkit dahili bir günlüktür. Örneğin, Config[...] biçimindeki Genkit günlükleri, belirli LLM çıkarımlarının sıcaklığı ve en iyi K değerleri gibi meta verileri içerir. Output[...] biçimindeki günlükler LLM yanıtlarını, Input[...] günlükleri ise istemleri içerir. Cloud Logging, hassas günlüklere erişim üzerinde ayrıntılı denetim sağlayan güçlü EKL'lere sahiptir.

Bu işlem, izlemenin ayrıntılarına hızlıca göz atmanızı sağlayan bir izleme önizleme bölmesi açar. Ayrıntıların tamamını görmek için bölmenin sağ üst kısmındaki "İzleme'de Görüntüle" bağlantısını tıklayın.

Cloud Trace'teki en belirgin gezinme öğesi, iz dağılım grafiğidir. Belirli bir zaman aralığında toplanan tüm izleri içerir.

Her bir veri noktasını tıkladığınızda, noktalı grafikte ilgili noktanın ayrıntıları gösterilir.

Ayrıntılı görünümde, tüm adımlar ve önemli zamanlama bilgileri dahil olmak üzere akış şekli bulunur. Cloud Trace, bu görünümde belirli bir izlemeyle ilişkili tüm günlükleri birbirine bağlayabilir. "Günlükler ve etkinlikler" açılır menüsünde "Genişletilmiş olarak göster" seçeneğini belirleyin.

Sonuçta elde edilen görünüm, istemler ve LLM yanıtları dahil olmak üzere günlüklerin izleme bağlamında ayrıntılı bir şekilde incelenmesine olanak tanır.

Metrikler

Genkit tarafından dışa aktarılan tüm metrikleri görüntülemek için sol taraftaki menüde "Yapılandır" başlığı altındaki "Metrik yönetimi"ni tıklayabilirsiniz.

Metrik yönetimi konsolu, Cloud Run ve çevresel ortamıyla ilgili olanlar da dahil olmak üzere toplanan tüm metriklerin tablo biçiminde bir görünümünü içerir. "İş yükü" seçeneğini tıkladığınızda Genkit tarafından toplanan metrikleri içeren bir liste gösterilir. genkit ön ekiyle başlayan tüm metrikler dahili bir Genkit metriğidir.

Genkit; özellik, işlem ve oluşturma dahil olmak üzere çeşitli metrik kategorileri toplar. Her metrikte, güçlü filtreleme ve gruplandırmayı kolaylaştıran çeşitli faydalı boyutlar bulunur.

Yaygın olarak kullanılan boyutlar şunlardır:

  • flow_name: Akıştaki üst düzey ad.
  • flow_path: Aralık ve üst aralığı, kök aralığa kadar zincirlenir.
  • error_code: Hata olması durumunda ilgili hata kodu.
  • error_message: Hata olması durumunda ilgili hata mesajı.
  • model: Modelin adı.

Özellik metrikleri

Özellikler, Genkit kodunuzun üst düzey giriş noktasıdır. Çoğu durumda bu bir akış olacaktır. Aksi takdirde, bu bir izlemedeki en üst ara olacaktır.

Ad Tür Açıklama
genkit/feature/requests Sayaç İstek sayısı
genkit/feature/latency Histogram ms cinsinden yürütme gecikmesi

Her özellik metriği aşağıdaki boyutları içerir:

Ad Açıklama
ad Özelliğin adı. Çoğu durumda bu, üst düzey Genkit akışı olur.
durum Özellik isteğinin başarılı olup olmamasına bağlı olarak "success" veya "failure"
hata Yalnızca status=failure olduğunda ayarlanır. Başarısızlığa neden olan hata türünü içerir
source Genkit kaynak dili. Ör. 'ts'
sourceVersion Genkit çerçeve sürümü

İşlem metrikleri

İşlemler, Genkit'te genel bir yürütme adımını temsil eder. Bu adımların her biri için aşağıdaki metrikler izlenir:

Ad Tür Açıklama
genkit/action/requests Sayaç Bu işlemin gerçekleştirilme sayısı
genkit/action/latency Histogram ms cinsinden yürütme gecikmesi

Her işlem metriği aşağıdaki boyutları içerir:

Ad Açıklama
ad İşlemin adı
featureName Çalıştırılan üst özelliğin adı
yol Özellik kökünden bu işleme kadar olan yürütme yolu. Ör. '/myFeature/parentAction/thisAction'
durum İşlemin başarılı olup olmamasına bağlı olarak "success" veya "failure"
hata Yalnızca status=failure olduğunda ayarlanır. Başarısızlığa neden olan hata türünü içerir
source Genkit kaynak dili. Ör. 'ts'
sourceVersion Genkit çerçeve sürümü

Metrik oluşturma

Bunlar, bir modelle etkileşime geçen işlemlerle ilgili özel işlem metrikleridir. İsteklere ve gecikmeye ek olarak giriş ve çıkış da izlenir. Bu işlem, hata ayıklama ve yapılandırma ayarlarını kolaylaştıran modele özgü boyutlarla gerçekleştirilir.

Ad Tür Açıklama
genkit/ai/generate/requests Sayaç Bu modelin çağrılma sayısı
genkit/ai/generate/latency Histogram ms cinsinden yürütme gecikmesi
genkit/ai/generate/input/tokens Sayaç Giriş jetonları
genkit/ai/generate/output/tokens Sayaç Çıkış jetonları
genkit/ai/generate/input/characters Sayaç Karakter girişi
genkit/ai/generate/output/characters Sayaç Çıkış karakterleri
genkit/ai/generate/input/images Sayaç Giriş resimleri
genkit/ai/generate/output/images Sayaç Çıkış resimleri
genkit/ai/generate/input/audio Sayaç Ses dosyası ekleme
genkit/ai/generate/output/audio Sayaç Ses dosyaları oluşturma

Her oluşturma metriği aşağıdaki boyutları içerir:

Ad Açıklama
modelName Modelin adı
featureName Çalıştırılan üst özelliğin adı
yol Özellik kökünden bu işleme kadar olan yürütme yolu. Ör. '/myFeature/parentAction/thisAction'
latencyMs Modelin yanıt verme süresi
durum Özellik isteğinin başarılı olup olmamasına bağlı olarak "success" veya "failure"
hata Yalnızca status=failure olduğunda ayarlanır. Başarısızlığa neden olan hata türünü içerir
source Genkit kaynak dili. Ör. 'ts'
sourceVersion Genkit çerçeve sürümü

Metrikleri görselleştirmek için Metrik Gezgini'ni kullanabilirsiniz. Sol menüden "Keşfet" başlığı altındaki "Metrik gezgini"ni tıklayın.

"Metrik seçin" açılır menüsünü tıklayıp "Genel Düğüm", "Genkit" ve bir metrik seçerek metrik belirleyin.

Metriklerin görselleştirmesi, türüne (sayaç, histogram vb.) bağlıdır. Metrik Gezgini, metrikleri çeşitli boyutlarına göre grafik haline getirmenize yardımcı olmak için güçlü toplama ve sorgulama olanakları sunar.

Telemetri gecikmesi

Bir akıştaki belirli bir yürütmenin telemetrisinin Cloud'un operasyonlar paketinde gösterilmesi biraz zaman alabilir. Çoğu durumda bu gecikme 1 dakikadan kısadır.

Kotalar ve sınırlar

Dikkate alınması gereken birkaç kota vardır:

Maliyet

Cloud Logging, Cloud Trace ve Cloud Monitoring'in cömert ücretsiz katmanları vardır. Fiyatlandırmayla ilgili ayrıntılı bilgi için aşağıdaki bağlantıları inceleyebilirsiniz: