Cloud Functions ve Agent Platform ile sunucu tarafında Remote Config'i kullanma

Bu kılavuzda, Agent Platform Gemini API (formerly Vertex AI)'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ının başına ekleyeceğiniz bir istem dahil) yönetecek ve bu girişleri Firebase konsolundan istediğiniz zaman güncelleyebilirsiniz. Ayrıca işlevi test etmek ve hatalarını ayıklamak için Firebase Local Emulator Suite kullanacaksınız. Ardından, çalıştığını doğruladıktan sonra işlevi Google Cloud üzerinde dağıtıp test edeceksiniz.

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

Ön koşullar

Bu kılavuzda, uygulama geliştirmek için JavaScript kullanmayı bildiğiniz 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 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 projesini otomatik olarak) 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 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, işlevleri Cloud Functions çalışma zamanına dağıtmak için ise Firebase KSA'ya ihtiyacınız vardır.

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

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

  2. Tercih ettiğiniz yöntemi kullanarak Firebase KSA'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, genel olarak kullanılabilen firebase komutunu yükler. Bu komut başarısız olursa npm izinlerini değiştirmeniz gerekebilir.

    firebase-tools aracını en yeni sürüme güncellemek için aynı komutu tekrar çalıştırın.

  3. firebase-functions ve firebase-admin uygulamalarını 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ı aşamasına geçmeye hazırsınız.

Uygulama

Remote Config ve Agent Platform 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 Agent Platform önerilen API'yi etkinleştirin.
  2. Projenizi ilk kullanıma hazırlama ve Node bağımlılıklarını yükleme
  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ıp Firebase Local Emulator Suite test edin.
  7. İşlevinizi Google Cloud platformuna dağıtın.

1. adım: Google Cloud konsolunda Agent Platform önerilen API'yi etkinleştirin

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

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

    API'nin etkinleştirilmesi birkaç dakika sürebilir. Etkinleştirme işlemi tamamlanana kadar sayfayı etkin ve açık tutun.

  5. Faturalandırma etkinleştirilmemişse bir Cloud Billing hesabı eklemeniz veya bağlamanız istenir. Faturalandırma hesabını etkinleştirdikten sonra Agent Platform kontrol paneline dönün ve önerilen tüm API'lerin etkinleştirildiğini doğrulayın.

2. adım: Projenizi ilk kullanıma hazırlayı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 aracını 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 seçin.

    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 Agent Platform paketlerini ekleyin. --save komutunu 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, en yeni sürümler belirtilmiş şekilde aşağıdaki gibi görünmelidir:

  {
    "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 stanza görürsünüz. Ayrıca, düğüm motoru sürümünün, yüklü Node.js sürümünüzle ve 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 Edit principal'ı (Yetkiyi düzenle) tıklayın. Düzenleme erişimi sayfası açılır.
  3. Add another role'u (Başka bir rol ekle) tıklayın ve Remote Config Viewer'ı (Görüntüleyici) seçin.
  4. Add another role'u (Başka bir rol ekle) tıklayın ve AI platform developer'ı (AI platformu geliştiricisi) seçin.
  5. Başka bir rol ekle'yi tıklayın, Agent Platform kullanıcısı'nı seçin.
  6. Add another role'u (Başka bir rol ekle) tıklayın ve Cloud Run Invoker'ı (Cloud Run Çağırıcısı) 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. Add key (Anahtar ekle) > Create new key'i (Yeni anahtar oluştur) 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ı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 üreten bir işlev oluşturacaksınız. Birden fazla kod snippet'ini birleştirerek Admin SDK ve Agent Platform Gemini API (formerly Vertex AI)'yi başlatan, Remote Config kullanarak varsayılan parametreleri yapılandıran, en güncel Remote Config parametrelerini alan, kullanıcı girişini işleyen ve kullanıcıya yanıt akışı sağlayan kapsamlı bir işlev oluşturacaksınız.

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

  2. Mevcut içeriği silip Admin SDK, Remote Config ve Agent Platform SDK'larını ekleyin ve aşağıdaki kodu dosyaya yapıştırarak uygulamayı ilk kullanıma hazırlayın:

    const { onRequest } = require("firebase-functions/https");
const { requiresRole, requiresAPI } = require("firebase-functions");
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");

requiresRole("roles/aiplatform.user");
requiresRole("roles/cloudconfig.viewer");
requiresAPI("aiplatform.googleapis.com", "Needed to query Vertex AI Gemini models");
requiresAPI("firebaseremoteconfig.googleapis.com", "Needed to fetch server-side Remote Config templates");

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

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

  3. İşlevinizin Remote Config sunucusuna bağlanamadığı durumlarda 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 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 başlıklı makaleyi inceleyin.

    İsteğe bağlı olarak, Agent Platform Gemini API (formerly Vertex AI) 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 ayarlanmıştır. Bu sayede, temel işlev dağıtımını test ederken Agent Platform kullanımı atlanır. true olarak ayarlanması Agent Platform Gemini API (formerly Vertex AI) çağrısını yapar.

    // 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
};

  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;

  5. Agent Platform ö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');
  }
});

  6. Dosyayı kaydedip kapatın.

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

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

  1. Firebase konsolunda DevOps & Engagement > Remote Config'e gidin.

  2. Sayfanın üst kısmındaki İstemci/Sunucu seçiciden 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 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ı bölümüne 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 Agent Platform için güvenlik ayarları JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Agent Platform hizmetinin ve modelinin çalıştırılacağı konum Dize global
    is_vertex_enabled Sorguların Agent Platform adresine gönderilip gönderilmeyeceğini kontrol eden isteğe bağlı parametre. Boole true

  4. Parametre eklemeyi tamamladığınızda 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ı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 bölümünde açıklandığı şekilde GOOGLE_APPLICATION_CREDENTIALS değerini bir ortam değişkeni olarak ayarladığınızdan emin olun. Ardından, functions dizininizin ana 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 ve LOCATION, işlevi dağıttığınız bölgedir (ör. us-central1):

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

  4. Yanıt gelmesini 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. Kullanıcı girişi göndermeyi deneyin. is_vertex_enabled, Remote Config sunucu şablonunuzda yapılandırıldığından bu işlem, Agent Platform Gemini API (formerly Vertex AI) üzerinden Gemini modeline erişir ve ücrete tabi olabilir:

    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şiklikler yapın, ardından değişiklikleri görmek için işlevinize yeniden erişin.

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

İşlevinizi test edip doğruladıktan sonra Google Cloud ortamına dağıtmaya ve canlı işlevi test etmeye hazırsınız demektir.

İşlevinizi dağıtma

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

firebase deploy --only functions

İşleve 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ğrılara varsayılan olarak izin verilir. Test sırasında ve App Check ile güvenli hale getirmeden ö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, ardından Güvenlik sekmesini tıklayın.

  3. Kimlik doğrulaması zorunlu olsun'u 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ı, işlevi çalıştırmak ve Remote Config ile Agent Platform Gemini API (formerly Vertex AI) 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. 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 işlevinizi Admin SDK hizmet hesabı ayrıcalıklarıyla çalışacak şekilde 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 konsolundan IAM ve Yönetici > IAM'i 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ğine bürünme bölümüne bakın.

  4. Google Cloud konsol Cloud Functions sayfasını açın ve Functions 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. Next'i (Sonraki), ardından Deploy'u (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 hizmetiyle kimlik doğrulaması yapmanız ve geçerli bir kimlik doğrulama jetonu almanız gerekir.

Jeton oluşturmayı etkinleştirmek için gcloud CLI'yı 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 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