Üretken Yapay Zeka Node.js Genkit Web Uygulamasını Sürüm Denetimi'nden Cloud Run'a Otomatik Olarak Dağıtma

1. Genel Bakış

Bir web uygulamasını ilk kez dağıtmak korkutucu olabilir. İlk dağıtımdan sonra bile, süreç çok fazla iş gerektiriyorsa uygulamanızın yeni sürümlerini dağıtmaktan kaçınabilirsiniz. Sürekli dağıtım sayesinde, uygulamanızdaki değişiklikleri otomatik olarak kolayca dağıtabilirsiniz.

Bu laboratuvarda bir web uygulaması yazar ve uygulamanızın kaynak kodunda değişiklik yapıldığında uygulamanızı otomatik olarak dağıtacak şekilde Cloud Run'u yapılandırırsınız. Ardından, uygulamanızı değiştirip tekrar dağıtın.

Öğrenecekleriniz

  • Cloud Shell Düzenleyici ile web uygulaması yazma
  • Uygulama kodunuzu GitHub'da depolama
  • Uygulamanızı Cloud Run'a otomatik olarak dağıtma
  • Genkit'i kullanarak üretken yapay zekayı uygulamanıza ekleme
  • dotprompt kitaplığını kullanarak LLM istemlerini yönetme

2. Ön koşullar

  1. Google Hesabınız yoksa Google Hesabı oluşturmanız gerekir.
    • İş veya okul hesabı yerine kişisel hesap kullanıyorsanız. İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.
  2. GitHub hesabınız yoksa GitHub hesabı oluşturmanız gerekir

3. Proje ayarlama

  1. Google Cloud Console'da oturum açın.
  2. Cloud Console'da faturalandırmayı etkinleştirin.
    • Bu laboratuvarı tamamlamak, bulut kaynaklarında 1 ABD dolarından az maliyete mal olur.
    • Daha fazla ödeme alınmaması için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
    • Yeni kullanıcılar 300 ABD doları tutarındaki ücretsiz denemeden yararlanabilir.
    • Geliştiriciler için Üretken Yapay Zeka etkinliğine mi katılıyorsunuz? 1 ABD doları kredi alabilirsiniz.
  3. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin.

4. Cloud Shell Düzenleyici'yi açma

  1. Cloud Shell Düzenleyici'ye gidin
  2. Terminal ekranın alt kısmında görünmüyorsa açın:
    • Hamburger menüsünü Hamburger menü simgesi tıklayın.
    • Terminal'i tıklayın.
    • Yeni Terminal'i tıklayınCloud Shell Düzenleyici'de yeni terminal açma
  3. Terminalde projenizi şu komutla ayarlayın:
    • Biçim:
      gcloud config set project [PROJECT_ID]
    • Örnek:
      gcloud config set project lab-project-id-example
    • Proje kimliğinizi hatırlamıyorsanız:
      • Tüm proje kimliklerinizi şu komutla listeleyebilirsiniz:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  4. Yetkilendirme isteğinde bulunulursa devam etmek için Yetkilendir'i tıklayın. Cloud Shell'e yetki vermek için tıklayın
  5. Şu mesajı görürsünüz:
    Updated property [core/project].
    WARNING görüyorsanız ve Do you want to continue (Y/N)? soruyorsa proje kimliğini yanlış girmiş olabilirsiniz. N, Enter tuşlarına basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.

5. API'leri etkinleştir

Terminalde API'leri etkinleştirin:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com

Bu komutun tamamlanması birkaç dakika sürebilir ancak sonunda şuna benzer bir başarılı mesaj gösterilir:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

6. Git'i yapılandırma

  1. Global git kullanıcı e-postanızı ayarlama:
    git config --global user.email "you@example.com"
  2. Global git kullanıcı adınızı ayarlayın:
    git config --global user.name "Your Name"
  3. Genel git varsayılan dalınızı main olarak ayarlayın:
    git config --global init.defaultBranch main

7. Kodunuzu yazın

Node.js'de uygulama yazmak için:

  1. Ana dizine gidin:
    cd ~
  2. codelab-genai dizinini oluşturun:
    mkdir codelab-genai
  3. codelab-genai dizinine gidin:
    cd codelab-genai
  4. index.js dosyası oluşturun:
    touch index.js
  5. package.json dosyasını oluşturun:
    npm init es6 -y
  6. Bağımlılık olarak express ekleyin
    npm install express
  7. node_modules
    echo node_modules/ >> .gitignore
    dosyasının kaydetmesini önlemek için .gitignore dosyası ekleme
  8. Cloud Shell Düzenleyici'de index.js dosyasını açın:
    cloudshell edit index.js
    Artık ekranın üst kısmında boş bir dosya görünecektir. Bu index.js dosyasını buradan düzenleyebilirsiniz. Kodun ekranın üst kısmına yerleştirildiğini gösterin
  9. Aşağıdaki kodu kopyalayıp açılan index.js dosyasına yapıştırın:
    import express from 'express';

const app = express();
app.get('/', async (req, res) => {
    res.send('Hello world!');
});

const port = process.env.PORT || 8080;
app.listen(port, () => {
    console.log(`codelab-genai: listening on port ${port}`);
});
    Cloud Shell Düzenleyici, birkaç saniye sonra kodunuzu otomatik olarak kaydeder. Bu kod, http isteklerine "Merhaba dünya!" karşılama mesajıyla yanıt verir.

Uygulamanız için ilk kodunuz tamamlandı ve sürüm kontrolünde depolanmaya hazır.

8. Kod deposu oluştur

  1. Ekranınızın alt kısmındaki Cloud Shell terminaline dönün.
  2. Hâlâ doğru dizinde olduğunuzdan emin olun:
    cd ~/codelab-genai
  3. Git deponuzu başlatma
    git init -b main
  4. GitHub CLI'ye giriş yapın
    gh auth login
    Varsayılan seçenekleri kabul etmek için Enter tuşuna basın ve GitHub CLI aracındaki talimatları uygulayın. Örneğin:
    1. Hangi hesaba giriş yapmak istiyorsunuz? GitHub.com
    2. Bu ana makinede Git işlemleri için tercih ettiğiniz protokol nedir? HTTPS
    3. Git'in kimliğini GitHub kimlik bilgilerinizle doğrulama Y (Bu görünmüyorsa atlayın.)
    4. GitHub CLI'yi nasıl doğrulamak istersiniz? Login with a web browser
    5. Tek seferlik kodunuzu kopyalama
    6. https://github.com/login/device adresini açın
    7. Tek seferlik kodunuzu yapıştırın
    8. GitHub'ı yetkilendir'i tıklayın.
    9. Girişinizi tamamlayın
  5. Oturum açtığınızı onaylayın:
    gh api user -q ".login"
    Girişiniz başarılı olduysa GitHub kullanıcı adınız gösterilir.
  6. GITHUB_USERNAME değişkeni
    GITHUB_USERNAME=$(gh api user -q ".login")
    oluşturma
  7. Ortam değişkenini oluşturduğunuzu onaylayın:
    echo ${GITHUB_USERNAME}
    Değişkeni başarıyla oluşturduysanız GitHub kullanıcı adınız gösterilir.
  8. codelab-genai adlı boş bir GitHub deposu oluşturun:
    gh repo create codelab-genai --private
    Aşağıdaki hatayı alırsanız:
    GraphQL: Name already exists on this account (createRepository)
    codelab-genai adlı bir depo zaten mevcuttur. Bu eğitime devam etmek için iki seçeneğiniz vardır:
  9. codelab-genai deposunu uzak origin olarak ekleyin:
    git remote add origin https://github.com/${GITHUB_USERNAME}/codelab-genai

9. Kodunuzu paylaşma

  1. Doğru dizinde olduğunuzu onaylayın:
    cd ~/codelab-genai
  2. Geçerli dizindeki tüm dosyaları bu kayda ekleyin:
    git add .
  3. İlk commit'i oluşturun:
    git commit -m "add http server"
  4. Kaydı, origin deposunun main dalına aktarın:
    git push -u origin main

Bu komutu çalıştırıp uygulamanızın kodunu GitHub'da görüntülemek için ortaya çıkan URL'yi ziyaret edebilirsiniz:

echo -e "\n\nTo see your code, visit this URL:\n \
    https://github.com/${GITHUB_USERNAME}/codelab-genai/blob/main/index.js \n\n"

10. Otomatik dağıtımlar oluşturma

  1. Cloud Shell Düzenleyici sekmesini açık bırakın. Bu sekmeye daha sonra geri döneceğiz.
  2. Yeni bir sekmede Cloud Run sayfasını ziyaret edin.
  3. Console'da doğru Google Cloud projesini seçin Google Cloud Console proje açılır menüsü
  4. REPOYU BAĞLA'yı tıklayın.
  5. CLOUD BUILD İLE KURULUMU YAP'ı tıklayın
    1. Depo Sağlayıcı olarak GitHub'ı seçin
      • Tarayıcıda GitHub hesabınıza giriş yapmadıysanız kimlik bilgilerinizle giriş yapın.
    2. Kimlik doğrula'yı ve ardından Devam'ı tıklayın.
    3. Giriş yaptıktan sonra Cloud Run sayfasında GitHub Uygulaması, hiçbir deponuzda kurulu değil yazan bir mesaj görürsünüz.
    4. GOOGLE CLOUD BUILD'İ YÜKLE düğmesini tıklayın.
      • Kurulum Ayarları sayfasında Yalnızca belirli depoları seç'i ve CLI üzerinden oluşturduğunuz codelab-genai deposunu seçin.
      • Yükle'yi tıklayın.
      • Not: Çok sayıda GitHub deponuz varsa bu işlemin yüklenmesi birkaç dakika sürebilir.
    5. Depo olarak your-user-name/codelab-genai'ü seçin
      • Depo mevcut değilse Bağlı Depoları Yönet bağlantısını tıklayın.
    6. Branch değerini ^main$ olarak bırakın.
    7. Google Cloud'ın Buildpacks'i aracılığıyla Go, Node.js, Python, Java, .NET Core, Ruby veya PHP'yi tıklayın
      • Diğer alanları (Build context directory, Entrypoint ve Function target) olduğu gibi bırakın.
    8. Kaydet'i tıklayın
  6. Kimlik doğrulama'ya gidin.
  7. Kimliği doğrulanmayan çağrılara izin ver'i tıklayın.
  8. OLUŞTUR'u tıklayın.

Derleme işlemi tamamlandıktan sonra (bu işlem birkaç dakika sürer) bu komutu çalıştırın ve çalışan uygulamanızı görüntülemek için oluşturulan URL'yi ziyaret edin:

echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

11. Kodunuzu değiştirme

Cloud Shell Düzenleyici'ye dönme

Cloud Shell Düzenleyici hâlâ açıksa bu adımları atlayabilirsiniz.

  1. Cloud Shell Düzenleyici'ye gidin
  2. Terminal ekranın alt kısmında görünmüyorsa açın:
    • Hamburger menüsünü Hamburger menü simgesi tıklayın.
    • Terminal'i tıklayın.
    • Yeni Terminal'i tıklayınCloud Shell Düzenleyici'de yeni terminal açma
  3. Terminalde projenizi şu komutla ayarlayın:
    • Biçim:
      gcloud config set project [PROJECT_ID]
    • Örnek:
      gcloud config set project lab-project-id-example
    • Proje kimliğinizi hatırlamıyorsanız:
      • Tüm proje kimliklerinizi şu komutla listeleyebilirsiniz:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  4. Yetkilendirme isteğinde bulunulursa devam etmek için Yetkilendir'i tıklayın. Cloud Shell'e yetki vermek için tıklayın
  5. Şu mesajı görürsünüz:
    Updated property [core/project].
    WARNING görüyorsanız ve Do you want to continue (Y/N)? soruyorsa proje kimliğini yanlış girmiş olabilirsiniz. N, Enter tuşlarına basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.

Vertex AI'ı uygulamanıza ekleme

  1. Ekranınızın alt kısmındaki Cloud Shell terminaline dönün.
  2. Hâlâ doğru dizinde olduğunuzdan emin olun:
    cd ~/codelab-genai
  3. Node.js Genkit SDK'sını yükleyin:
    npm install @genkit-ai/ai
  4. Vertex AI için Node.js Genkit SDK'sını yükleyin:
    npm install @genkit-ai/vertexai
  5. Node.js Google Auth SDK'sını yükleyin:
    npm install google-auth-library
  6. index.js dosyasını Cloud Shell Düzenleyici'de yeniden açın
    cloudshell edit ~/codelab-genai/index.js
  7. index.js dosyanızın içindeki kodu şu kodla değiştirin:
    import express from 'express';
const app = express();

import { generate } from '@genkit-ai/ai';
import { gemini15Flash, vertexAI } from '@genkit-ai/vertexai';

import { GoogleAuth } from 'google-auth-library';
const auth = new GoogleAuth();

app.get('/', async (req, res) => {
    const project = await auth.getProjectId();

    const animal = req.query.animal || 'dog';
    const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
    const result = await generate({
        plugins: [
            vertexAI({ projectId: project, location: 'us-central1' }),
        ],
        model: gemini15Flash,
        prompt,
    });
    const html = result.text;
    res.send(html);
});

const port = process.env.PORT || 8080;
app.listen(port, () => {
    console.log(`codelab-genai: listening on port ${port}`);
});

12. Yeniden dağıt

  1. Cloud Shell'de hâlâ doğru dizinde olduğunuzdan emin olun:
    cd ~/codelab-genai
  2. Uygulamanızın yeni bir sürümünü yerel git deponuza kaydetmek için şu komutları çalıştırın:
    git add .
git commit -m "add latest changes"
  3. Değişiklikleri GitHub'a gönderin:
    git push
  4. Derleme işlemi tamamlandıktan sonra şu komutu çalıştırın ve dağıtılan uygulamanızı ziyaret edin:
    echo -e "\n\nOnce the build finishes, visit your live application:\n \
    "$( \
        gcloud run services list | \
        grep codelab-genai | \
        awk '/URL/{print $2}' | \
        head -1 \
    )" \n\n"

Değişikliklerinizi görebilmeniz için derlemenin tamamlanması birkaç dakika sürebilir.

Tüm düzeltmelerin geçmişini burada görebilirsiniz: https://console.cloud.google.com/run/detail/us-central1/codelab-genai/revisions

13. (İsteğe bağlı) Vertex AI kullanımınızı denetleme

Diğer Google Cloud hizmetlerinde olduğu gibi Vertex AI işlemlerini denetleyebilirsiniz. Denetleme günlükleri, "Kim neyi, nerede ve ne zaman yaptı?" sorularını yanıtlamanıza yardımcı olur. Vertex AI için yönetim denetleme günlükleri varsayılan olarak etkindir. İçerik oluşturma isteklerini denetlemek için Veri Erişimi denetleme günlüklerini etkinleştirmeniz gerekir:

  1. Google Cloud Console'da Denetleme Günlükleri sayfasına gidin:

    Bu sayfayı bulmak için arama çubuğunu kullanırsanız alt başlığı IAM ve Yönetici olan sonucu seçin.
  2. Cloud Run uygulamanızı oluşturduğunuz mevcut Google Cloud projesinin olduğundan emin olun.
  3. Veri Erişimi denetleme günlükleri yapılandırması tablosunda Hizmet sütunundan Vertex AI API'yi seçin.
  4. Günlük Türleri sekmesinde, Veri Erişimi denetleme günlüğü türleri Admin read ve Data read'ı seçin.
  5. Kaydet'i tıklayın.

Bu özelliği etkinleştirdikten sonra, uygulamanın her çağrılmasıyla ilgili denetleme günlüklerini görebilirsiniz. Çağırma ayrıntılarını içeren denetleme günlüklerini görmek için aşağıdakileri yapın:

  1. Yayınlanan uygulamanıza dönün ve günlüğü tetiklemek için sayfayı yenileyin.
  2. Google Cloud Console'da Günlük Gezgini sayfasına gidin:

  3. Sorgu penceresine şunu yazın:
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access")
protoPayload.serviceName="aiplatform.googleapis.com"
  4. Sorguyu çalıştır'ı tıklayın.

Denetleme günlükleri, Vertex AI API'nin kullanımını yakalar ancak istemler veya yanıt ayrıntıları gibi iş yüküyle ilgili verileri gözlemlemenize izin vermez.

14. (İsteğe bağlı) Yapay zeka iş yükünüzün gözlemlenebilirliğini artırma

Denetleme günlükleri, iş yüküyle ilgili bilgileri yakalamaz. İş yüklerinizin gözlemlenebilirliğini artırmak için bu bilgileri açıkça günlüğe kaydetmeniz gerekir. Bunu yapmak için favori günlük kaydı çerçevenizi kullanabilirsiniz. Aşağıdaki adımlarda, yerel Node.js günlük kaydı mekanizması kullanılarak bunun nasıl yapılacağı gösterilmektedir.

  1. index.js dosyasını Cloud Shell Düzenleyici'de yeniden açın
    cloudshell edit ~/codelab-genai/index.js
  2. await generativeModel.generateContent(prompt) çağrısından (19. satır) sonra aşağıdaki satırı ekleyin:
        console.log(JSON.stringify({
        severity: 'DEBUG',
        message: 'Content is generated',
        prompt: prompt,
        response: resp.response,
    }));
    Bu kod, oluşturulan içerikle ilgili bilgileri yapılandırılmış günlük kaydı biçimini kullanarak stdout dosyasına yazar. Cloud Run'daki bir günlük kaydı aracısı, stdout üzerine yazdırılan çıkışı yakalar ve bu biçimi Cloud Logging'e yazar.
  3. Cloud Shell'i yeniden açın ve doğru dizinde olduğunuzdan emin olmak için aşağıdaki komutu yazın:
    cd ~/codelab-genai
  4. Değişiklikleri kaydetme:
    git commit -am "observe generated content"
  5. Değiştirilen sürümün yeniden dağıtılmasını tetiklemek için değişiklikleri GitHub'a aktarın:
    git push

Yeni sürüm dağıtıldıktan sonra Vertex AI'a yapılan çağrılarla ilgili hata ayıklama bilgilerini gözlemleyebilirsiniz.

Uygulama günlüklerinizi görmek için şunları yapın:

  1. Google Cloud Console'da Günlük Gezgini sayfasına gidin:

  2. Sorgu penceresine şunu yazın:
    LOG_ID("run.googleapis.com%2Fstdout")
severity=DEBUG
  3. Sorguyu çalıştır'ı tıklayın.

Sorgunun sonucu, güvenlik uygulamalarını izlemek için kullanılabilecek "güvenlik derecelendirmeleri" içeren istem ve Vertex AI yanıtını içeren günlükleri gösterir.

15. (İsteğe bağlı) Temizleme

Cloud Run, hizmet kullanılmadığında ücret almaz ancak container görüntüsünü Artifact Registry'de depolamak için sizden ücret alınabilir. Ücret ödememek için Cloud projenizi silebilirsiniz. Cloud projenizi sildiğinizde, söz konusu projede kullanılan tüm kaynakların faturalandırması durdurulur.

İsterseniz projeyi silin:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Gereksiz kaynakları CloudShell diskinizden de silebilirsiniz. Şunları yapabilirsiniz:

  1. Codelab proje dizinini silin: 
    rm -rf ~/codelab-genai
  2. Uyarı! Bu işlem geri alınamaz. Yer açmak için Cloud Shell'ınızdaki her şeyi silmek istiyorsanız tüm ana dizininizi silebilirsiniz. Saklamak istediğiniz her şeyin başka bir yere kaydedildiğinden emin olun. 
    sudo rm -rf $HOME

16. Tebrikler

Bu laboratuvarda bir web uygulaması yazdınız ve Cloud Run'u, uygulamanızın kaynak kodunda değişiklik yapıldığında uygulamanızı otomatik olarak dağıtacak şekilde yapılandırdınız. Ardından uygulamanızı değiştirip tekrar dağıttınız.

Bu laboratuvarı beğendiyseniz başka bir kodlama dilinde veya çerçevede tekrar deneyebilirsiniz:

Şu anda kullandığınız ürünleri iyileştirmek için bir kullanıcı deneyimi (UX) araştırmasına katılmak istiyorsanız buradan kaydolun.

Öğrenmeye devam etmek için kullanabileceğiniz bazı seçenekler: