Menggunakan Remote Config sisi server dengan Cloud Functions dan Vertex AI

Panduan ini menjelaskan cara mulai menggunakan Cloud Functions generasi ke-2 dengan Remote Config sisi server untuk melakukan panggilan sisi server ke Vertex AI Gemini API.

Dalam tutorial ini, Anda akan menambahkan Remote Config ke fungsi seperti chatbot yang menggunakan model Gemini untuk menjawab pertanyaan pengguna. Remote Config akan mengelola input Gemini API (termasuk prompt yang akan ditambahkan ke kueri pengguna yang masuk), dan Anda dapat memperbarui input ini secara on demand dari Firebase console. Anda juga akan menggunakan Firebase Local Emulator Suite untuk menguji dan men-debug fungsi, kemudian, setelah memastikan bahwa fungsi tersebut berfungsi, Anda akan men-deploy dan mengujinya di Google Cloud.

Prasyarat

Panduan ini mengasumsikan bahwa Anda sudah memahami penggunaan JavaScript untuk mengembangkan aplikasi.

Menyiapkan project Firebase

Jika Anda belum memiliki project Firebase:

  1. Login ke Firebase console.

  2. Klik Buat project, lalu gunakan salah satu opsi berikut:

    • Opsi 1: Buat project Firebase baru (dan project Google Cloud dasarnya secara otomatis) dengan memasukkan nama project baru di langkah pertama alur kerja "Buat project".
    • Opsi 2: "Tambahkan Firebase" ke project Google Cloud yang sudah ada dengan memilih nama project Google Cloud dari menu drop-down pada langkah pertama alur kerja "Buat project".

  3. Saat diminta, Anda tidak perlu menyiapkan Google Analytics untuk menggunakan solusi ini.

  4. Lanjutkan mengikuti petunjuk di layar untuk membuat project Anda.

Jika Anda sudah memiliki project Firebase:

Lanjutkan ke Mengonfigurasi lingkungan pengembangan Anda.

Mengonfigurasi lingkungan pengembangan Anda

Anda memerlukan lingkungan Node.js untuk menulis fungsi, dan Anda memerlukan Firebase CLI untuk men-deploy fungsi ke runtime Cloud Functions.

  1. Instal Node.js dan npm.

    Untuk menginstal Node.js dan npm, sebaiknya gunakan Node Version Manager.

  2. Instal Firebase CLI menggunakan metode pilihan Anda. Misalnya, untuk menginstal CLI menggunakan npm, jalankan perintah ini:

    npm install -g firebase-tools@latest

    Perintah ini menginstal perintah firebase yang tersedia secara global. Jika perintah ini gagal, Anda mungkin perlu mengubah izin npm.

    Untuk mengupdate ke versi terbaru firebase-tools, jalankan kembali perintah yang sama.

  3. Instal firebase-functions dan firebase-admin, lalu gunakan --save untuk menyimpannya ke package.json:

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

Sekarang Anda siap untuk melanjutkan ke penerapan solusi ini.

Penerapan

Ikuti langkah-langkah berikut untuk membuat, menguji, dan men-deploy Cloud Functions generasi ke-2 dengan Remote Config dan Vertex AI:

  1. Aktifkan API yang direkomendasikan Vertex AI di Konsol Google Cloud.
  2. Lakukan inisialisasi project Anda dan instal dependensi Node.
  3. Konfigurasikan izin IAM untuk akun layanan Admin SDK dan simpan kunci Anda.
  4. Buat fungsi.
  5. Buat template Remote Config khusus server.
  6. Deploy fungsi Anda dan uji di Firebase Local Emulator Suite.
  7. Deploy fungsi Anda ke Google Cloud.

Langkah 1: Aktifkan API yang direkomendasikan Vertex AI di Konsol Google Cloud

  1. Buka Konsol Google Cloud dan jika diminta, pilih project Anda.
  2. Pada kolom Search di bagian atas konsol, masukkan Vertex AI dan tunggu hingga Vertex AI muncul sebagai hasilnya.
  3. Pilih Vertex AI. Dasbor Vertex AI akan muncul.

  4. Klik Enable All Recommended APIs.

    Mungkin perlu waktu beberapa saat hingga pengaktifan API selesai. Pastikan halaman tetap aktif dan terbuka hingga pengaktifan selesai.

  5. Jika penagihan tidak diaktifkan, Anda akan diminta untuk menambahkan atau menautkan akun Penagihan Cloud. Setelah mengaktifkan akun penagihan, kembali ke dasbor Vertex AI dan pastikan semua API yang direkomendasikan telah diaktifkan.

Langkah 2: Inisialisasi project Anda dan instal dependensi Node

  1. Buka terminal di komputer dan pilih direktori tempat Anda berencana membuat fungsi.

  2. Login ke Firebase:

    firebase login

  3. Jalankan perintah berikut untuk menginisialisasi Cloud Functions for Firebase:

    firebase init functions

  4. Pilih Use an existing project dan tentukan project ID Anda.

  5. Saat diminta memilih bahasa yang akan digunakan, pilih JavaScript, lalu tekan Enter.

  6. Untuk opsi lainnya, pilih default.

    Direktori functions dibuat di direktori saat ini. Di dalamnya, Anda akan menemukan file index.js yang akan digunakan untuk membangun fungsi, direktori node_modules yang berisi dependensi untuk fungsi Anda, dan file package.json yang berisi dependensi paket.

  7. Tambahkan paket Admin SDK dan Vertex AI dengan menjalankan perintah berikut, menggunakan --save untuk memastikan bahwa paket tersebut disimpan ke file package.json Anda:

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

File functions/package.json Anda sekarang akan terlihat seperti berikut, dengan versi terbaru yang ditentukan:

  {
    "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
  }

Perhatikan bahwa jika Anda menggunakan ESLint, Anda akan melihat stanza yang menyertakannya. Selain itu, pastikan versi node engine sesuai dengan versi Node.js yang diinstal dan versi yang pada akhirnya Anda jalankan di Google Cloud. Misalnya, jika stanza engines di package.json Anda dikonfigurasi sebagai Node versi 18 dan Anda menggunakan Node.js 20, perbarui file tersebut agar menggunakan 20:

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

Langkah 3: Konfigurasikan izin IAM untuk akun layanan Admin SDK dan simpan kunci Anda

Dalam solusi ini, Anda akan menggunakan akun layanan Firebase Admin SDK untuk menjalankan fungsi.

  1. Di konsol Google Cloud, buka halaman IAM & Admin, lalu cari akun layanan Admin SDK (bernama firebase-adminsdk).
  2. Pilih akun dan klik Edit akun utama. Halaman Edit akses akan muncul.
  3. Klik Tambahkan peran lain, pilih Remote Config Viewer.
  4. Klik Tambahkan peran lain, pilih pengembang platform AI.
  5. Klik Add another role, pilih Vertex AI user.
  6. Klik Add another role, pilih Cloud Run Invoker.
  7. Klik Save.

Selanjutnya, ekspor kredensial untuk akun layanan Admin SDK dan simpan di variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS Anda.

  1. Di konsol Google Cloud, buka halaman Credentials.
  2. Klik akun layanan Admin SDK untuk membuka halaman Details.
  3. Klik Kunci.
  4. Klik Add key > Create new key.
  5. Pastikan JSON dipilih sebagai Jenis kunci, lalu klik Buat.
  6. Download kunci ke tempat yang aman di komputer.

  7. Dari terminal Anda, ekspor kunci sebagai variabel lingkungan:

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

Langkah 4: Membuat fungsi

Pada langkah ini, Anda akan membuat fungsi yang menangani input pengguna dan menghasilkan respons yang didukung teknologi AI. Anda akan menggabungkan beberapa cuplikan kode untuk membangun fungsi komprehensif yang menginisialisasi Admin SDK dan Vertex AI Gemini API, mengonfigurasi parameter default menggunakan Remote Config, mengambil parameter Remote Config terbaru, memproses input pengguna, dan mengalirkan respons kembali ke pengguna.

  1. Di codebase Anda, buka functions/index.js di editor teks atau IDE.

  2. Hapus konten yang ada, lalu tambahkan Admin SDK, Remote Config, dan Vertex AI SDK, serta lakukan inisialisasi aplikasi dengan menempelkan kode berikut ke file:

    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. Konfigurasi nilai default yang akan digunakan fungsi Anda jika tidak dapat terhubung ke server Remote Config. Solusi ini mengonfigurasi textModel, generationConfig, safetySettings, textPrompt, dan location sebagai parameter Remote Config yang sesuai dengan parameter Remote Config yang akan Anda konfigurasi lebih lanjut dalam panduan ini. Untuk mengetahui informasi selengkapnya tentang parameter ini, lihat klien Node.js Vertex AI.

    Secara opsional, Anda juga dapat mengonfigurasi parameter untuk mengontrol apakah Anda mengakses Vertex AI Gemini API atau tidak (dalam contoh ini, parameter yang disebut vertex_enabled). Penyiapan ini dapat berguna saat menguji fungsi Anda. Dalam cuplikan kode berikut, nilai ini ditetapkan ke false, yang tidak akan dapat menggunakan Vertex AI selagi Anda menguji deployment fungsi dasar. Menetapkannya ke true akan memanggil Vertex AI Gemini API.

    // 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. Buat fungsi dan siapkan Remote Config sisi server:

    // 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. Siapkan Vertex AI dan tambahkan logika chat dan respons:

      // 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. Simpan dan tutup file tersebut.

Langkah 5: Buat template Remote Config khusus server

Selanjutnya, buat template Remote Config sisi server dan konfigurasikan parameter serta nilai yang akan digunakan dalam fungsi Anda. Untuk membuat template Remote Config khusus server:

  1. Buka Firebase console, lalu luaskan Run dari menu navigasi, lalu pilih Remote Config.

  2. Pilih Server dari pemilih Klien/Server di bagian atas halaman Remote Config.

    • Jika ini pertama kalinya Anda menggunakan Remote Config atau template server, klik Create Configuration. Panel Create your first server-side parameter akan muncul.
    • Jika ini bukan pertama kalinya Anda menggunakan template server Remote Config, klik Add parameter.

  3. Tentukan parameter Remote Config berikut:

    Nama parameter Deskripsi Type Nilai default
    model_name Nama model
    Untuk daftar terbaru nama model yang akan digunakan dalam kode Anda, lihat Versi dan siklus proses model atau Nama model yang tersedia.     		String gemini-1.5-pro-preview-0514
    prompt Minta untuk menambahkan awalan ke kueri pengguna. String 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 Parameter yang akan dikirim ke model. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings Setelan keamanan untuk Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location Lokasi untuk menjalankan layanan dan model Vertex AI. String us-central1
    is_vertex_enabled Parameter opsional yang mengontrol apakah kueri dikirim ke Vertex AI atau tidak. Boolean true

  4. Setelah selesai menambahkan parameter, periksa kembali parameter Anda dan apakah jenis datanya sudah benar, lalu klik Publish changes.

Langkah 6: Deploy fungsi dan uji di Firebase Local Emulator Suite

Sekarang Anda siap men-deploy dan menguji fungsi secara lokal dengan Firebase Local Emulator Suite.

  1. Pastikan Anda telah menetapkan GOOGLE_APPLICATION_CREDENTIALS sebagai variabel lingkungan seperti yang dijelaskan di Langkah 3: Konfigurasikan izin IAM untuk akun layanan Admin SDK dan simpan kunci Anda. Kemudian, dari direktori induk direktori functions, deploy fungsi Anda ke emulator Firebase:

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

  2. Buka halaman log emulator. Ini akan menunjukkan bahwa fungsi Anda telah dimuat.

  3. Akses fungsi Anda dengan menjalankan perintah berikut, dengan PROJECT_ID sebagai project ID Anda dan LOCATION sebagai region tempat fungsi di-deploy (misalnya us-central1):

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

  4. Tunggu respons, lalu kembali ke halaman log Firebase Emulator atau konsol Anda dan periksa apakah ada error atau peringatan.

  5. Coba kirim beberapa input pengguna, dengan catatan bahwa karena is_vertex_enabled dikonfigurasi dalam template server Remote Config Anda, kode ini akan mengakses Gemini melalui Vertex AI Gemini API dan hal ini dapat dikenai biaya:

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

  6. Buat perubahan pada template server Remote Config di Firebase console, lalu akses ulang fungsi Anda untuk mengamati perubahan.

Langkah 7: Deploy fungsi Anda ke Google Cloud

Setelah menguji dan memverifikasi fungsi, Anda siap men-deploy ke Google Cloud dan menguji fungsi langsung.

Men-deploy function

Deploy fungsi Anda menggunakan Firebase CLI:

firebase deploy --only functions

Memblokir akses yang tidak diautentikasi ke fungsi

Saat fungsi di-deploy menggunakan Firebase, pemanggilan yang tidak diautentikasi diizinkan secara default jika kebijakan organisasi Anda tidak membatasinya. Selama pengujian dan sebelum mengamankan dengan App Check, sebaiknya blokir akses yang tidak diautentikasi.

Untuk memblokir akses yang tidak diautentikasi ke fungsi:

  1. Di konsol Google Cloud, buka Cloud Run.

  2. Klik generateWithVertex, lalu klik tab Keamanan.

  3. Aktifkan Wajibkan autentikasi, lalu klik Simpan.

Konfigurasi akun pengguna Anda untuk menggunakan kredensial akun layanan Admin SDK

Karena akun layanan Admin SDK memiliki semua peran dan izin yang diperlukan untuk menjalankan fungsi dan berinteraksi dengan Remote Config dan Vertex AI Gemini API, sebaiknya gunakan akun tersebut untuk menjalankan fungsi Anda. Untuk melakukannya, Anda harus dapat membuat token untuk akun dari akun pengguna Anda.

Langkah-langkah berikut menjelaskan cara mengonfigurasi akun pengguna dan fungsi yang akan dijalankan dengan hak istimewa akun layanan Admin SDK.

  1. Di konsol Google Cloud, aktifkan IAM Service Account Credentials API.
  2. Beri akun pengguna peran Service Account Token Creator: Dari Konsol Google Cloud, buka IAM & Admin > IAM, pilih akun pengguna Anda, lalu klik Edit principal > Add another role.

  3. Pilih Service Account Token Creator, lalu klik Save.

    Untuk mengetahui informasi lebih mendetail tentang peniruan akun layanan, lihat Peniruan identitas akun layanan di dokumentasi Google Cloud.

  4. Buka halaman Cloud Functions di Konsol Google Cloud, lalu klik fungsi generateWithVertex dalam daftar Functions.

  5. Pilih Pemicu > Edit, lalu luaskan Setelan waktu proses, build, koneksi, dan keamanan.

  6. Dari tab Runtime, ubah Akun layanan runtime ke akun Admin SDK.

  7. Klik Next, lalu klik Deploy.

Menyiapkan gcloud CLI

Untuk menjalankan dan menguji fungsi Anda dengan aman dari command line, Anda harus melakukan autentikasi dengan layanan Cloud Functions dan mendapatkan token autentikasi yang valid.

Untuk mengaktifkan pembuatan token, instal dan konfigurasikan gcloud CLI:

  1. Jika belum diinstal di komputer, instal gcloud CLI seperti yang dijelaskan dalam Menginstal gcloud CLI.

  2. Dapatkan kredensial akses untuk akun Google Cloud Anda:

    gcloud auth login

  3. Tetapkan ID project Anda di gcloud:

    gcloud config set project PROJECT_ID

Menguji fungsi

Sekarang Anda siap menguji fungsi di Google Cloud. Untuk menguji fungsi, jalankan perintah berikut:

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

Coba lagi dengan data yang disediakan pengguna:

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"

Sekarang Anda dapat membuat perubahan pada template server Remote Config, memublikasikan perubahan tersebut, dan menguji berbagai opsi.

Langkah berikutnya