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

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

Bu eğitimde, kullanıcı sorularını yanıtlamak için Gemini modelini kullanan sohbet botu 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 edip hata ayıklamak için de Firebase Local Emulator Suite'yı kullanırsınız. İşlevin çalıştığını doğruladıktan sonra Google Cloud üzerinde dağıtıp test edersiniz.

Ön koşullar

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

Firebase projesi oluşturma

Henüz bir Firebase projeniz yoksa:

  1. Firebase Console'da oturum açın.

  2. Proje oluştur'u tıklayın ve 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 temelindeki Google Cloud projesi) otomatik olarak oluşturun.
    • 2. seçenek: "Proje oluşturma" 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 projeye "Firebase 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 gidin.

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

İşlev yazmak için Node.js ortamına, işlevleri Cloud Functions çalışma zamanına dağıtmak için ise 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 Node Version Manager'ı kullanmanızı öneririz.

  2. Tercih ettiğiniz yöntemi kullanarak Firebase CLI'yı yükleyin. Örneğin, CLI'yı npm kullanarak 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.

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

  3. firebase-functions ve firebase-admin'ı yükleyin ve --save'ı kullanarak bunları package.json cihazınıza kaydedin:

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

Artık bu çözümün uygulanmasına geçebilirsiniz.

Uygulama

Remote Config ve Vertex AI ile 2. nesil Cloud Functions 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 içinde test edin.
  7. İşlevinizi Google Cloud'e dağıtın.

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

  1. Google Cloud konsolunu açın ve istendiğinde projenizi seçin.
  2. Konsolun üst kısmındaki Arama alanına Vertex AI girin ve Vertex AI simgesinin sonuç olarak görünmesini bekleyin.
  3. Vertex AI simgesini seçin. Vertex AI kontrol paneli gösterilir.

  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 işlemi 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 etkinleştirildiğini doğrulayın.

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

  1. Bilgisayarınızda bir terminal 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'ı 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çip Enter tuşuna basın.

  6. Diğer tüm seçenekler için varsayılan değerleri belirleyin.

    Geçerli dizinde bir functions dizini oluşturulur. İçinde, işlevinizi oluşturmak 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ı bulunur.

  7. Aşağıdaki komutları çalıştırarak Admin SDK ve Vertex AI paketlerini ekleyin. --save kullanarak 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 aşağıdaki gibi görünmelidir. En son sürümler belirtilmiştir:

  {
    "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 kıta göreceğinizi unutmayın. Ayrıca, düğüm motoru sürümünün, Node.js'nin yüklü sürümünüzle ve nihayetinde Google Cloud üzerinde çalıştırdığınız sürümle eşleştiğinden emin olun. Örneğin, package.json dosyanızdaki engines bölümü Node sürüm 18 olarak yapılandırılmışsa ve Node.js 20 kullanıyorsanız dosyayı 20'yi 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çip Asıl öğeyi düzenle'yi tıklayın. Düzenleme erişimi sayfası gösterilir.
  3. Başka bir rol ekle'yi tıklayın ve Remote Config Görüntüleyici'yi seçin.
  4. Başka bir rol ekle'yi tıklayın ve Yapay zeka platformu geliştiricisi'ni seçin.
  5. Başka rol ekle'yi tıklayın ve Vertex AI kullanıcısı'nı seçin.
  6. Başka rol ekle'yi tıklayın ve Cloud Run Invoker'ı 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. Admin SDK 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çili olduğundan emin olun ve 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 öğelerini 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 akışı sağlayan kapsamlı bir işlev oluşturmak için birden fazla kod snippet'ini birleştireceksiniz.

  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 ve ardından Admin SDK, Remote Config ve Vertex AI SDK'sını ekleyin. 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ğlanamaması durumunda kullanacağı varsayılan değerleri yapılandırın. Bu çözüm, textModel, generationConfig, safetySettings, textPrompt ve location değerlerini, bu kılavuzda daha sonra yapılandıracağınız Remote Config parametrelerine karşılık gelen Remote Config parametreleri olarak ayarlar. 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 ürününe erişip erişmeyeceğinizi kontrol etmek için bir parametre de yapılandırabilirsiniz (bu örnekte vertex_enabled adlı bir parametre). Bu kurulum, işlevinizi test ederken yararlı olabilir. Aşağıdaki kod snippet'lerinde bu değer false olarak ayarlanır. Bu da temel işlev dağıtımını test ederken Vertex AI kullanımını atlamanızı sağlar. true olarak ayarladığınızda 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şturma ve sunucu tarafı Remote Config kurulumunu yapma:

    // 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 özelliğini 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ında bir Remote Config şablonu oluşturun ve işlevinizde kullanılacak parametreleri ve değerleri yapılandırın. Sunucuya özel Remote Config şablon oluşturmak için:

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

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

    • Remote Config veya sunucu şablonlarını ilk kez kullanıyorsanız Yapılandırma Oluştur'u tıklayın. İlk sunucu taraflı 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 kullanacağınız 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-2.0-flash
    prompt Kullanıcının sorgusunun başına eklenecek istem. 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. Dize us-central1
    is_vertex_enabled Sorguların Vertex AI adresine gönderilip gönderilmeyeceğini kontrol eden isteğe bağlı parametre. Boole true

  4. Parametre eklemeyi bitirdikten sonra parametrelerinizi ve veri türlerinin doğru olup olmadığını iki kez 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 içinde test edin

Artık işlevinizi Firebase Local Emulator Suite ile yerel olarak dağıtmaya ve 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 başlıklı makalede açıklandığı gibi GOOGLE_APPLICATION_CREDENTIALS öğesini bir 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şlem, işlevinizin 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ı bekleyin, ardından Firebase Emulator günlükleri sayfasına veya konsolunuza dönüp hata ya da uyarı olup olmadığını kontrol edin.

  5. is_vertex_enabled, Remote Config sunucu şablonunuzda yapılandırıldığından Gemini modeline Vertex AI Gemini API üzerinden erişilmesi gerektiğini ve bunun ücretlere tabi olabileceğini göz önünde bulundurarak bazı kullanıcı girişleri göndermeyi deneyin:

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

  6. Remote Config konsolunda Firebase 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'ya dağıtın

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

İşlevinizi dağıtma

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

firebase deploy --only functions

Fonksiyona kimliği doğrulanmamış erişimi engelleme

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

İşleve kimliği doğrulanmamış erişimi engellemek için:

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

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

  3. Kimlik doğrulama gerektir'i etkinleştirin ve 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ında işlevi çalıştırmak ve Remote Config ile Vertex AI Gemini API ile etkileşimde bulunmak için gerekli tüm roller ve izinler bulunduğ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ü atayın: Google Cloud konsolunda IAM ve Yönetici > IAM'i açın, kullanıcı hesabınızı seçin ve Asıl öğeyi düzenle > Başka 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 dokümanlarındaki Hizmet hesabı kimliğine bürünme başlıklı makaleyi inceleyin.

  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ı Admin SDK hesabı olarak değiştirin.

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

gcloud CLI'yı ayarlama

İşlevinizi komut satırından güvenli bir şekilde çalıştırmak ve test etmek için Cloud Functions hizmetinde kimliğinizi 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 henüz 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 alın:

    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 içinde 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