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

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

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

için uygun olup olmadığınızı kontrol edin.

Ön koşullar

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

Firebase projesi oluşturma

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 projesi) oluşturun.
    • 2. Seçenek: "Proje oluştur" iş akışının ilk adımındaki açılır menüden Google Cloud proje adınızı seçerek mevcut bir Google Cloud projesine "Firebase ekleyin".

  3. İstendiğinde bu çözümü kullanmak için Google Analytics'i kurmanı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

İşlev yazmak için bir Node.js ortamına, işlevleri Cloud Functionsçalışma zamanına dağıtmak için ise Firebase CLI'ye 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 KSA'yı yükleyin. Örneğin, npm kullanarak CLI'yi yüklemek için şu komutu çalıştırın:

    npm install -g firebase-tools@latest

    Bu komut, genel olarak kullanılabilir firebase komutunu yükler. Bu komut başarısız olursa npm izinlerini değiştirmeniz gerekebilir.

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

  3. firebase-functions ve firebase-admin'ü yükleyin ve --save'yi kullanarak package.json'inize kaydedin:

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

Artık bu çözümün uygulanması işlemine devam etmeye hazırsınız.

Uygulama

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

  1. Google Cloud konsolunda Vertex AI önerilen API'leri etkinleştirin.
  2. Projenizi başlatın ve Node bağımlılıklarını yükleyin.
  3. Admin SDK 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ın ve Firebase Local Emulator Suite'da test edin.
  7. İşlevinizi Google Cloud'a dağıtın.

1. adım: Google Cloud konsolunda Vertex AI önerilen API'leri etkinleştirin

  1. Google Cloud konsolunu açın ve istendiğinde projenizi seçin.
  2. Konsolu üst kısmındaki Arama alanına Vertex AI yazın ve Vertex AI'nin sonuç olarak görünmesini bekleyin.
  3. Vertex AI simgesini 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 Cloud Billing hesabı eklemeniz veya bağlamanız istenir. Faturalandırma hesabını etkinleştirdikten sonra Vertex AI kontrol paneline dönün ve önerilen tüm API'lerin etkin olduğunu doğrulayın.

2. Adım: Projenizi başlatın ve Node bağımlılarını yükleyin

  1. Bilgisayarınızda bir terminali 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 değişkenini başlatmak 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ılan değerleri seçin.

    Mevcut dizinde bir functions dizini oluşturulur. İçinde, işlevinizi oluşturmak için kullanacağınız bir index.js dosyası, işlevinize yönelik bağımlılıkları içeren bir node_modules dizini ve paket bağımlılıkları içeren bir package.json dosyası bulunur.

  7. Aşağıdaki komutları çalıştırarak Admin SDK ve Vertex AI paketlerini ekleyin. --save dosyasını package.json dosyanıza kaydettiğinizden emin olmak için kullanın:

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

functions/package.json dosyanız artık en son sürümlerin belirtildiği 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, bu ifadeyi içeren bir dize göreceğinize dikkat edin. Ayrıca, düğüm motoru sürümünün, yüklediğiniz Node.js sürümüyle ve Google Cloud'te çalıştırdığınız sürümle eşleştiğinden emin olun. Örneğin, package.json içindeki engines dizeleri Düğüm sürüm 18 olarak yapılandırılmışsa ve Node.js 20 kullanıyorsanız dosyayı 20 kullanacak şekilde güncelleyin:

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

3. Adım: Admin SDK 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ı kullanacaksınız.

  1. Google Cloud konsolunda IAM ve Yönetici sayfasını açın ve Admin SDK hizmet hesabını (firebase-adminsdk adlı) bulun.
  2. Hesabı seçin ve Temel kullanıcıyı düzenle'yi tıklayın. Erişimi düzenle sayfası görünür.
  3. Başka bir rol ekle'yi tıklayın, Remote Config Görüntüleyen'i seçin.
  4. Başka bir rol ekle'yi tıklayın, Yapay zeka platformu geliştiricisi'ni seçin.
  5. Başka rol ekle'yi tıklayın, Vertex AI kullanıcı'yı 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, Admin SDK hizmet hesabının kimlik bilgilerini dışa aktarın ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkeninize kaydedin.

  1. Google Cloud konsolunda Kimlik bilgileri sayfasını açın.
  2. Ayrıntılar sayfasını açmak için Admin SDK hizmet hesabını tıklayın.
  3. Anahtarlar'ı tıklayın.
  4. Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
  5. Anahtar türü olarak JSON'un seçili olduğundan emin olun ve Oluştur'u tıklayın.
  6. Anahtarı bilgisayarınızdaki güvenli bir yere indirin.

  7. Anahtarı terminalinizden 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 kullanarak varsayılan parametreleri yapılandıran, en son Remote Config parametrelerini getiren, kullanıcı girişini işleyen ve kullanıcıya yanıt aktaran kapsamlı bir işlev oluşturmak için birden fazla kod snippet'ini birleştirirsiniz.

  1. Kod tabanınızda, functions/index.js dosyasını 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'sını ekleyin ve dosyaya aşağıdaki kodu 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. İşleviniz Remote Config sunucusuna bağlanamazsa kullanacağı varsayılan değerleri yapılandırın. Bu çözüm, textModel, generationConfig, safetySettings, textPrompt ve location parametrelerini bu kılavuzun ilerleyen bölümlerinde yapılandıracağınız Remote Config parametreleriyle eşleşen Remote Config parametreleri olarak yapılandırır. Bu parametreler hakkında daha fazla bilgi için Vertex AI Node.js istemcisi başlıklı makaleyi inceleyin.

    İsteğe bağlı olarak, Vertex AI Gemini API öğesine erişip erişemeyeceğinizi kontrol edecek bir parametre de yapılandırabilirsiniz (bu örnekte vertex_enabled adlı parametre). Bu kurulum, işlevinizi test ederken yararlı olabilir. Aşağıdaki kod snippet'lerinde bu değer false olarak ayarlanmıştır. Bu durumda, temel işlev dağıtımını test ederken Vertex AI kullanımı atlanır. true olarak ayarlandığında 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-002",
  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 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 öğesini ayarlayın ve sohbet ile 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ı kaydedip kapatın.

5. adım: Sunucuya özel bir Remote Config şablonu oluşturun

Ardından, sunucu tarafı bir Remote Config şablonu oluşturun ve işlevinizde kullanılacak parametreleri ve değerleri yapılandırın. Sunucuya özgü bir şablon oluşturmak için:Remote Config

  1. Firebase konsolunu açın ve gezinme menüsünde Çalıştır'ı genişletip Remote Config seçeneğini belirleyin.

  2. Sayfanın üst kısmındaki İstemci/Sunucu seçicisinden Sunucu'yu seçinRemote Config.

    • Remote Config 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ünür.
    • Remote Config sunucu şablonlarını ilk kez kullanmı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ı makalelere bakın.     		Dize gemini-1.5-flash-002
    prompt Kullanıcının sorgusuna eklenecek metni isteyin. 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 için güvenlik ayarları JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Vertex AI hizmetini ve modelini çalıştırmak için konum izni Dize us-central1
    is_vertex_enabled Sorguların Vertex AI hedefine gönderilip gönderilmeyeceğini kontrol eden isteğe bağlı parametre. Boole true

  4. Parametre eklemeyi bitirdiğinizde parametrelerinizi ve veri türlerinin doğru olup olmadığını tekrar kontrol edin, ardından Değişiklikleri yayınla'yı tıklayın.

6. adım: İşlevinizi dağıtın ve Firebase Local Emulator Suite

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

  1. GOOGLE_APPLICATION_CREDENTIALS değerini, 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 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, işlevinizin yüklendiğini gösterir.

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

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

  4. Yanıt bekleyin, ardından Firebase Emulator günlükleri sayfasına veya konsolunuza dönüp hata veya uyarı olup olmadığını kontrol edin.

  5. is_vertex_enabled, Remote Config sunucu şablonunuzda yapılandırıldığı için bu girişin Vertex AI Gemini API üzerinden Gemini hizmetine erişeceğini ve bu işlem için ücret alınabileceğini belirterek kullanıcı girişi göndermeyi deneyin:

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

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

7. adım: İşlevinizi Google Cloud'e dağıtın

İşlevinizi test edip doğruladıktan sonra Google Cloud'e dağıtmaya ve canlı işlevi test etmeye hazırsınızdır.

İşlevinizi dağıtma

İşlevinizi Firebase CLI'yi kullanarak dağıtın:

firebase deploy --only functions

İşleve kimlik doğrulaması yapılmamış erişimi engelleme

İşlevler Firebase kullanılarak dağıtıldığında, kuruluşunuzun politikası bunu kısıtlamıyorsa kimlik doğrulaması yapılmayan çağrılara varsayılan olarak izin verilir. Test sırasında ve App Check ile güvenliği sağlamadan önce kimlik doğrulaması yapılmamış erişimi engellemenizi öneririz.

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

  1. Google Cloud konsolunda Cloud Run'u açın.

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

  3. Kimlik doğrulama gerektir'i etkinleştirin ve ardından Kaydet'i tıklayın.

Kullanıcı hesabınızı, Admin SDK hizmet hesabı kimlik bilgilerini kullanacak şekilde yapılandırın

Admin SDK hizmet hesabı, işlevi çalıştırmak ve Remote Config ile Vertex AI Gemini API ile etkileşimde bulunmak için gerekli tüm rollere ve izinlere sahip olduğundan işlevinizi çalıştırmak için bu hesabı kullanmanız gerekir. Bunu yapmak için kullanıcı hesabınızdan hesap için jeton oluşturabilmeniz gerekir.

Aşağıdaki adımlarda, kullanıcı hesabınızı ve Admin SDK hizmet hesabı ayrıcalıklarıyla çalışacak işlevi nasıl yapılandıracağınız açıklanmaktadır.

  1. Google Cloud konsolunda IAM Service Account Credentials API'yi etkinleştirin.
  2. Kullanıcı hesabınıza Hizmet Hesabı Jetonu Oluşturucu rolünü verin: Google Cloud Konsolda IAM ve Yönetici > IAM'ı açın, kullanıcı hesabınızı seçin ve Temel öğeyi düzenle > Başka rol ekle'yi tıklayın.

  3. Service Account Token Creator'ı (Hizmet Hesabı Jetonu Oluşturucu) seçip Save'i (Kaydet) tıklayın.

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

  4. Google Cloud konsol Cloud Functions sayfasını açın ve İşlevler listesinde generateWithVertex işlevini tıklayın.

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

  6. Çalışma zamanı sekmesinde, Çalışma zamanı hizmet hesabını Yönetici SDK'sı hesabı olarak değiştirin.

  7. Sonraki'yi, ardından Dağıt'ı tıklayın.

gcloud CLI'yi ayarlama

İşlevinizi komut satırından güvenli bir şekilde çalıştırmak ve 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 CLI'yi yükleyip yapılandırın:

  1. Bilgisayarınızda yüklü değilse gcloud CLI'yi gcloud CLI'yi yükleme bölümünde açıklandığı şekilde 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'te 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şiklik yapabilir, bu değişiklikleri yayınlayabilir ve farklı seçenekleri test edebilirsiniz.

Sonraki adımlar