Cloud Functions ve Vertex AI ile sunucu tarafı Remote Config'i kullanma

Bu kılavuzda, Vertex AI Gemini API'ye sunucu tarafı çağrılar yapmak için sunucu tarafı Remote Config ile 2. nesil Cloud Functions'ı kullanmaya nasıl başlayacağınız açıklanmaktadır.

Bu eğiticide, kullanıcı sorularını yanıtlamak için Gemini modelini kullanan chatbot benzeri bir işleve Remote Config'i ekleyeceksiniz. Remote Config, Gemini API girişlerini (gelen kullanıcı sorgularının başına ekleyeceğiniz istem dahil) yönetir. Bu girişleri Firebase konsolundan isteğe bağlı olarak güncelleyebilirsiniz. Ayrıca Firebase Local Emulator Suite'i kullanarak işlevi test edip hata ayıklarsınız. İşlevin çalıştığını doğruladıktan sonra Google Cloud'da dağıtıp test edersiniz.

Ön koşullar

Bu kılavuzda, uygulama geliştirmek için JavaScript kullanma konusunda bilgi sahibi olduğunuz varsayılır.

Firebase projesi oluşturun

Henüz bir Firebase projeniz yoksa:

  1. Firebase konsolunda oturum açın.

  2. Proje oluştur'u tıklayın ve ardından aşağıdaki seçeneklerden birini kullanın:

    • 1. Seçenek: "Proje oluştur" iş akışının ilk adımında yeni bir proje adı girerek yeni bir Firebase projesi (ve temel Google Cloud projesini otomatik olarak) oluşturun.
    • 2. Seçenek: "Proje oluştur" iş akışının ilk adımında açılır menüden Google Cloud projenizin adını seçerek mevcut bir Google Cloud projesine "Firebase'i ekleyin".

  3. İstendiğinde, bu çözümü kullanmak için Google Analytics'i ayarlamanız gerekmez.

  4. Projenizi oluşturmak için ekrandaki talimatları uygulamaya devam edin.

Zaten bir Firebase projeniz varsa:

Geliştirme ortamınızı yapılandırma bölümüne geçin.

Geliştirme ortamınızı yapılandırma

İşlevleri yazmak için Node.js ortamına ve işlevleri Cloud Functions çalışma zamanına dağıtmak için Firebase CLI'ya ihtiyacınız vardır.

  1. Node.js ve npm'yi yükleyin.

    Node.js ve npm'yi yüklemek için Düğüm Sürümü Yöneticisi'ni kullanmanızı öneririz.

  2. Tercih ettiğiniz yöntemi kullanarak Firebase CLI'yi yükleyin. Örneğin, npm kullanarak KSA'yı yüklemek için şu komutu çalıştırın:

    npm install -g firebase-tools@latest

    Bu komut, dünya genelinde kullanılabilen firebase komutunu yükler. Bu komut başarısız olursa npm izinlerini değiştirmeniz gerekebilir.

    En son firebase-tools sürümüne güncellemek için aynı komutu yeniden çalıştırın.

  3. firebase-functions ve firebase-admin uygulamasını yükleyin ve bunları package.json cihazınıza kaydetmek için --save kullanın:

    npm install firebase-functions@latest firebase-admin@latest --save

Artık bu çözümü uygulamaya hazırsınız.

Kullanım

Remote Config ve Vertex AI ile 2. nesil Cloud Functions işlevlerinizi oluşturmak, test etmek ve dağıtmak için aşağıdaki adımları uygulayın:

  1. Google Cloud Console'da Vertex AI tarafından önerilen API'leri etkinleştirin.
  2. Projenizi başlatın ve Düğüm bağımlılıklarını yükleyin.
  3. Yönetici SDK'sı hizmet hesabınız için IAM izinlerini yapılandırın ve anahtarınızı kaydedin.
  4. İşlevi oluşturun.
  5. Sunucuya özel bir Remote Config şablonu oluşturun.
  6. İşlevinizi dağıtıp Firebase Local Emulator Suite'te test edin.
  7. İşlevinizi Google Cloud'a dağıtın.

1. Adım: Google Cloud Console'da Vertex AI tarafından önerilen API'leri etkinleştirin

  1. Google Cloud Console'u açın ve istendiğinde projenizi seçin.
  2. Konsolun üst kısmındaki Arama alanına Vertex AI yazın ve sonuç olarak Vertex AI'ın görünmesini bekleyin.
  3. Vertex AI'ı seçin. Vertex AI kontrol paneli görüntülenir.

  4. Enable All Recommended APIs'ı (Önerilen Tüm API'leri Etkinleştir) tıklayın.

    API etkinleştirme işleminin tamamlanması birkaç dakika sürebilir. Etkinleştirme tamamlanana kadar sayfayı etkin ve açık tutun.

  5. Faturalandırma etkin değilse bir Cloud Faturalandırma hesabı eklemeniz veya bağlamanız istenir. Bir faturalandırma hesabını etkinleştirdikten sonra Vertex AI kontrol paneline dönün ve önerilen tüm API'lerin etkinleştirildiğini doğrulayın.

2. Adım: Projenizi başlatın ve Düğüm bağımlılıklarını yükleyin

  1. Bilgisayarınızda bir terminal penceresi açın ve işlevinizi oluşturmayı planladığınız dizine gidin.

  2. Firebase'e giriş yapın:

    firebase login

  3. Cloud Functions for Firebase'i ilk kullanıma hazırlamak için aşağıdaki komutu çalıştırın:

    firebase init functions

  4. Mevcut bir projeyi kullan'ı seçin ve proje kimliğinizi belirtin.

  5. Kullanılacak dili seçmeniz istendiğinde JavaScript'i seçin ve Enter tuşuna basın.

  6. Diğer tüm seçenekler için varsayılanları seçin.

    Geçerli dizinde bir functions dizini oluşturulur. İçinde işlevinizi derlemek için kullanacağınız bir index.js dosyası, işlevinizin bağımlılıklarını içeren bir node_modules dizini ve paket bağımlılıklarını içeren bir package.json dosyası bulacaksınız.

  7. Aşağıdaki komutları çalıştırarak Admin SDK ve Vertex AI paketlerini ekleyin ve --save ile paketin package.json dosyanıza kaydedildiğinden emin olun:

    cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save

functions/package.json dosyanız artık en son sürümler belirtilen şekilde aşağıdaki gibi görünecektir:

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

ESLint kullanıyorsanız bunu içeren bir dize göreceğinizi unutmayın. Ayrıca, düğüm motoru sürümünün, Node.js'nin yüklü sürümüyle ve Google Cloud'da çalıştırılan sürümle eşleştiğinden emin olun. Örneğin, package.json dosyanızdaki engines kıtası Düğüm sürümü 18 olarak yapılandırılmışsa ve Node.js 20'yi kullanıyorsanız dosyayı 20'yi kullanacak şekilde güncelleyin:

  "engines": {
    "node": "20"
  },

3. Adım: Yönetici SDK'si hizmet hesabınız için IAM izinlerini yapılandırın ve anahtarınızı kaydedin

Bu çözümde, işlevinizi çalıştırmak için Firebase Admin SDK hizmet hesabını kullanırsınız.

  1. Google Cloud Console'da IAM ve Yönetici sayfasını açın ve Yönetici SDK'si hizmet hesabını (firebase-adminsdk adlı) bulun.
  2. Hesabı seçin ve Ana hesabı düzenle'yi tıklayın. Erişimi düzenle sayfası görüntülenir.
  3. Başka bir rol ekle'yi tıklayıp Remote Config Görüntüleyici'yi seçin.
  4. Başka bir rol ekle'yi tıklayıp AI platform geliştiricisi'ni seçin.
  5. Başka bir rol ekle'yi tıklayıp Vertex AI kullanıcısı'nı seçin.
  6. Başka bir rol ekle'yi tıklayıp Cloud Run Çağırıcısı'nı seçin.
  7. Kaydet'i tıklayın.

Ardından, Yönetici SDK'si hizmet hesabı için kimlik bilgilerini dışa aktarın ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkeninize kaydedin.

  1. Google Cloud Console'da Kimlik Bilgileri sayfasını açın.
  2. Yönetici Paneli SDK'si hizmet hesabını tıklayarak Ayrıntılar sayfasını açın.
  3. Anahtarlar'ı tıklayın.
  4. Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
  5. Anahtar türü olarak JSON'nin seçildiğinden emin olun ve ardından Oluştur'u tıklayın.
  6. Anahtarı bilgisayarınızda güvenli bir yere indirin.

  7. Terminalinizden anahtarı ortam değişkeni olarak dışa aktarın:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

4. Adım: İşlevi oluşturun

Bu adımda kullanıcı girişini işleyen ve yapay zeka destekli yanıtlar oluşturan bir işlev oluşturacaksınız. Admin SDK ve Vertex AI Gemini API'yi başlatan, Remote Config'i kullanarak varsayılan parametreleri yapılandıran, en yeni Remote Config parametrelerini getiren, kullanıcı girişini işleyen ve kullanıcıya yanıt gönderen kapsamlı bir işlev oluşturmak için birden fazla kod snippet'ini birleştireceksiniz.

  1. Kod tabanınızda, functions/index.js kodunu bir metin düzenleyicide veya IDE'de açın.

  2. Mevcut içeriği silin, ardından Admin SDK, Remote Config ve Vertex AI SDK'yı ekleyin. Ardından aşağıdaki kodu dosyaya yapıştırarak uygulamayı başlatın:

    const { onRequest } = require("firebase-functions/v2/https");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();
    index.js

  3. İşlevinizin Remote Config sunucusuna bağlanamadığında kullanacağı varsayılan değerleri yapılandırın. Bu çözüm textModel, generationConfig, safetySettings, textPrompt ve location özelliklerini bu kılavuzda daha sonra yapılandıracağınız Remote Config parametrelerine karşılık gelen Remote Config parametreleri olarak yapılandırır. Bu parametreler hakkında daha fazla bilgi için Vertex AI Node.js istemcisi sayfasına bakın.

    İsteğe bağlı olarak, Vertex AI Gemini API'ye (bu örnekte, vertex_enabled adlı bir parametre) erişip erişemediğinizi kontrol etmek için bir parametre de yapılandırabilirsiniz. Bu kurulum, işlevinizi test ederken faydalı olabilir. Aşağıdaki kod snippet'lerinde bu değer false olarak ayarlanmıştır. Bu değer, siz temel işlev dağıtımını test ederken Vertex AI kullanımını atlar. Politika true olarak ayarlanırsa Vertex AI Gemini API çağrılır.

    // Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-preview-0514",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  prompt: "I'm a developer who wants to learn about Firebase and you are a \
    helpful assistant who knows everything there is to know about Firebase!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};
    index.js

  4. İşlevi oluşturun ve sunucu tarafı Remote Config'i ayarlayın:

    // Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;
    index.js

  5. Vertex AI'ı kurup sohbet ve yanıt mantığını ekleyin:

      // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Combine prompt from Remote Config with optional user input.
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    logger.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await generativeModel.generateContentStream(chatInput); 
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      logger.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    logger.error(error);
    response.status(500).send('Internal server error');
  }
});
    index.js

  6. Dosyayı kaydedin ve kapatın.

5. Adım: Sunucuya özgü bir Remote Config şablonu oluşturun

Şimdi, sunucu tarafında bir Remote Config şablonu oluşturup işlevinizde kullanmak için parametreleri ve değerleri yapılandırın. Sunucuya özgü Remote Config şablonu oluşturmak için:

  1. Firebase konsolunu açın ve gezinme menüsünden Çalıştır'ı genişletin ve Remote Config'i seçin.

  2. Remote Config sayfasının üst kısmındaki İstemci/Sunucu seçiciden Sunucu'yu seçin.

    • Remote Config'i veya sunucu şablonlarını ilk kez kullanıyorsanız Yapılandırma Oluştur'u tıklayın. İlk sunucu tarafı parametrenizi oluşturun bölmesi görüntülenir.
    • Remote Config sunucu şablonlarını ilk kez kullanıyorsanız Parametre ekle'yi tıklayın.

  3. Aşağıdaki Remote Config parametrelerini tanımlayın:

    Parametre adı Açıklama Tür Varsayılan değer
    model_name Model adı
    Kodunuzda kullanılacak model adlarının güncel listeleri için Model sürümleri ve yaşam döngüleri veya Kullanılabilir model adları başlıklı makaleleri inceleyin.     		Dize gemini-1.5-pro-preview-0514
    prompt Kullanıcının sorgusunun başına ekle. Dize I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!
    generation_config Modele gönderilecek parametreler. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Vertex AI güvenlik ayarları JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Vertex AI hizmetinin ve modelinin çalıştırılacağı konum. Dize us-central1
    is_vertex_enabled Sorguların Vertex AI'a gönderilip gönderilmeyeceğini kontrol eden isteğe bağlı parametre. Boole true

  4. Parametre eklemeyi tamamladıktan sonra, parametrelerinizi ve veri türlerinin doğru olduğunu tekrar kontrol edin, ardından Değişiklikleri yayınla'yı tıklayın.

6. Adım: İşlevinizi dağıtıp Firebase Local Emulator Suite'te test edin

Artık Firebase Local Emulator Suite ile işlevinizi yerel olarak dağıtıp test etmeye hazırsınız.

  1. 3. Adım: Admin SDK hizmet hesabınız için IAM izinlerini yapılandırın ve anahtarınızı kaydedin bölümünde açıklandığı şekilde GOOGLE_APPLICATION_CREDENTIALS'yi ortam değişkeni olarak ayarladığınızdan emin olun. Ardından, functions dizininizin üst dizininden işlevinizi Firebase emülatörüne dağıtın:

    firebase emulators:start --project PROJECT_ID --only functions

  2. Emülatörün günlükler sayfasını açın. Bu, fonksiyonunuzun yüklendiğini gösterir.

  3. Aşağıdaki komutu çalıştırarak işlevinize erişin. Burada PROJECT_ID proje kimliğiniz, LOCATION ise işlevi dağıttığınız bölgedir (örneğin, us-central1):

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. Yanıt için bekleyin, ardından Firebase Emulator günlükler sayfasına veya konsolunuza dönün ve hata ya da uyarı olup olmadığını kontrol edin.

  5. is_vertex_enabled Remote Config sunucu şablonunuzda yapılandırıldığı için bu işlemin Gemini'a Vertex AI Gemini API üzerinden erişmesi gerektiğini ve bunun için ücret alınabileceğini belirtmek üzere kullanıcı girişleri göndermeyi deneyin:

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. Firebase konsolundaki Remote Config sunucu şablonunuzda değişiklikler yapın, ardından değişiklikleri gözlemlemek için işlevinize yeniden erişin.

7. Adım: İşlevinizi Google Cloud'a dağıtın

İşlevinizi test edip doğruladıktan sonra Google Cloud'a dağıtım yapmaya ve canlı işlevi test etmeye hazırsınız demektir.

İşlevinizi dağıtma

Firebase CLI kullanarak işlevinizi dağıtın:

firebase deploy --only functions

İşleve kimlik doğrulamasız erişimi engelle

İşlevler Firebase kullanılarak dağıtıldığında kuruluşunuzun politikası tarafından kısıtlanmıyorsa kimliği doğrulanmamış çağrılara varsayılan olarak izin verilir. Test sırasında ve verileri Uygulama Kontrolü ile güvenlik altına almadan önce, kimlik doğrulamasız erişimi engellemenizi öneririz.

İşleve kimlik doğrulamasız erişimi engellemek için:

  1. Google Cloud Console'da Cloud Run'ı açın.

  2. generateWithVertex simgesini ve ardından Güvenlik sekmesini tıklayın.

  3. Kimlik doğrulaması iste'yi etkinleştirin ve ardından Kaydet'i tıklayın.

Kullanıcı hesabınızı, Yönetici SDK'si hizmet hesabı kimlik bilgilerini kullanacak şekilde yapılandırın

Yönetici SDK'si hizmet hesabı, işlevi çalıştırmak ve Remote Config ve Vertex AI Gemini API ile etkileşim kurmak için gerekli tüm rollere ve izinlere sahip olduğundan işlevinizi çalıştırmak için bu hesabı kullanmanız gerekir. Bunun için kullanıcı hesabınızdan ilgili hesap için jetonlar oluşturabilmeniz gerekir.

Aşağıdaki adımlarda, kullanıcı hesabınızın nasıl yapılandırılacağı ve Yönetici SDK'si hizmet hesabı ayrıcalıklarıyla çalıştırılacak işlev açıklanmaktadır.

  1. Google Cloud Console'da IAM Hizmet Hesabı Kimlik Bilgileri API'sini etkinleştirin.
  2. Kullanıcı hesabınıza Hizmet Hesabı Jetonu Oluşturucu rolünü verin: Google Cloud konsolunda IAM ve Yönetici > IAM'yi açın, kullanıcı hesabınızı seçin ve ardından Ana hesabı düzenle > Başka bir rol ekle'yi tıklayın.

  3. Hizmet Hesabı Jetonu Oluşturucu'yu seçin ve Kaydet'i tıklayın.

    Hizmet hesabı kimliğine bürünme hakkında daha ayrıntılı bilgi için Google Cloud belgelerindeki Hizmet hesabı kimliğe bürünme bölümüne bakın.

  4. Google Cloud Console Cloud Functions sayfasını açın ve Functions listesindeki generateWithVertex işlevini tıklayın.

  5. Tetikleyici > Düzenle'yi seçip Çalışma zamanı, derleme, bağlantılar ve güvenlik ayarları'nı genişletin.

  6. Çalışma zamanı sekmesinden Çalışma zamanı hizmet hesabını Admin SDK hesabı olarak değiştirin.

  7. Next'i (İleri), ardından Deploy'u (Dağıt) tıklayın.

gcloud KSA'yı ayarlama

İşlevinizi komut satırından güvenli bir şekilde çalıştırıp test etmek için Cloud Functions hizmetiyle kimlik doğrulamanız ve geçerli bir kimlik doğrulama jetonu almanız gerekir.

Jeton oluşturmayı etkinleştirmek için gcloud KSA'yı yükleyin ve yapılandırın:

  1. Bilgisayarınızda yüklü değilse gcloud KSA'yı yükleme bölümünde açıklandığı şekilde gcloud KSA'yı yükleyin.

  2. Google Cloud hesabınız için erişim kimlik bilgilerini edinin:

    gcloud auth login

  3. gcloud'da proje kimliğinizi ayarlayın:

    gcloud config set project PROJECT_ID

İşlevinizi test etme

Artık işlevinizi Google Cloud'da test etmeye hazırsınız. İşlevi test etmek için aşağıdaki komutu çalıştırın:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

Kullanıcı tarafından sağlanan verilerle tekrar deneyin:

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

Artık Remote Config sunucu şablonunuzda değişiklikler yapabilir, bu değişiklikleri yayınlayabilir ve farklı seçenekleri test edebilirsiniz.

Sonraki adımlar