שימוש בהגדרת תצורה מרחוק בצד השרת עם Cloud Functions ו-Vertex AI

במדריך הזה נסביר איך להתחיל להשתמש ב-Cloud Functions מדור שני עם Remote Config בצד השרת כדי לבצע קריאות בצד השרת ל-Vertex AI Gemini API.

במדריך הזה אנחנו מצרפים את Remote Config לפונקציה שדומה לצ'אט בוט משתמש במודל Gemini כדי לענות על שאלות של משתמשים. Remote Config ינהל את הקלט של Gemini API (כולל הנחיה שתוצמדת לשאילתות של המשתמשים הנכנסות), ותוכלו לעדכן את הקלט הזה על פי דרישה דרך מסוף Firebase. תוכלו גם להשתמש ב-Firebase Local Emulator Suite כדי לבדוק ולפתור באגים בפונקציה, ואז, אחרי שתאמתו שהיא פועלת, תוכלו לפרוס ולבדוק אותה ב-Google Cloud.

דרישות מוקדמות

במדריך הזה אנחנו יוצאים מנקודת הנחה שאתם מכירים את השימוש ב-JavaScript לפיתוח אפליקציות.

מגדירים פרויקט Firebase

אם עדיין אין לכם פרויקט ב-Firebase:

  1. נכנסים למסוף Firebase.

  2. לוחצים על Create project ומשתמשים באחת מהאפשרויות הבאות:

    • אפשרות 1: יצירת פרויקט Firebase חדש (והיסודות שלו פרויקט Google Cloud באופן אוטומטי) על ידי הזנת שם של פרויקט חדש ב- השלב הראשון של התהליך 'יצירת פרויקט' בתהליך העבודה.
    • אפשרות 2: 'הוספת Firebase' לפרויקט Google Cloud קיים. לשם כך, בוחרים את שם הפרויקט ב-Google Cloud בתפריט הנפתח בשלב הראשון בתהליך העבודה 'יצירת פרויקט'.

  3. כשמוצגת הנחיה, לא צריך להגדיר את Google Analytics כדי להשתמש בפתרון הזה.

  4. ממשיכים לפעול לפי ההוראות במסך כדי ליצור את הפרויקט.

אם כבר יש לכם פרויקט Firebase:

ממשיכים אל הגדרת סביבת הפיתוח.

הגדרת סביבת הפיתוח

כדי לכתוב פונקציות, תצטרכו סביבה של Node.js, ולפריסה של פונקציות בסביבת זמן הריצה Cloud Functions תצטרכו את ה-CLI של Firebase.

  1. מתקינים את Node.js ואת npm.

    כדי להתקין את Node.js ואת npm, מומלץ להשתמש מנהל גרסאות הצומת.

  2. מתקינים את ה-CLI של Firebase באמצעות לשיטה המועדפת עליכם. לדוגמה, כדי להתקין את ה-CLI באמצעות npm, הפקודה:

    npm install -g firebase-tools@latest

    הפקודה הזו מתקינה את הפקודה firebase שזמינה בכל העולם. אם הפקודה תיכשל, אולי יהיה צורך לשינוי ההרשאות של NPM.

    כדי לעדכן לגרסה האחרונה של firebase-tools, מריצים שוב את אותה הפקודה.

  3. כדי לחסוך, צריך להתקין את firebase-functions ואת firebase-admin ולהשתמש ב---save אותם אל package.json:

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

עכשיו אפשר להמשיך להטמעה של הפתרון הזה.

הטמעה

כדי ליצור, לבדוק ולפרוס את Cloud Functions מדור שני באמצעות Remote Config ו-Vertex AI:

  1. מפעילים את ממשקי ה-API המומלצים של Vertex AI במסוף Google Cloud.
  2. אתחול הפרויקט והתקנת יחסי תלות של Node.
  3. להגדיר הרשאות IAM לחשבון השירות שלך ב-Admin SDK ול שומרים את המפתח שלכם.
  4. יוצרים את הפונקציה.
  5. יוצרים תבנית Remote Config ספציפית לשרת.
  6. פורסים את הפונקציה ובודקים אותה ב-Firebase Local Emulator Suite.
  7. פורסים את הפונקציה ב-Google Cloud.

שלב 1: הפעלה של Vertex AI ממשקי API מומלצים במסוף Google Cloud

  1. פותחים את מסוף Google Cloud ובוחרים את הפרויקט הרלוונטי כשמתבקשים.
  2. בשדה חיפוש בחלק העליון של המסוף, מזינים Vertex AI וממתינים להופעת Vertex AI כתוצאה.
  3. לוחצים על Vertex AI. לוח הבקרה Vertex AI יופיע.

  4. לוחצים על Enable AllRecommended APIs (הפעלת כל ממשקי ה-API המומלצים).

    הפעלת ה-API עשויה להימשך כמה רגעים. שמירת הדף פעיל ופתוח עד לסיום ההפעלה.

  5. אם החיוב לא מופעל, תתבקשו להוסיף או לקשר חשבון Cloud Billing. אחרי שמפעילים חשבון לחיוב, חוזרים למרכז הבקרה Vertex AI ומוודאים שכל ממשקי ה-API המומלצים מופעלים.

שלב 2: אתחול הפרויקט והתקנת יחסי התלות של Node

  1. פותחים טרמינל במחשב ומנווטים אל הספרייה שבה כדי ליצור את הפונקציה.

  2. מתחברים ל-Firebase:

    firebase login

  3. מריצים את הפקודה הבאה כדי לאתחל את Cloud Functions for Firebase:

    firebase init functions

  4. בוחרים באפשרות שימוש בפרויקט קיים ומציינים את מזהה הפרויקט.

  5. כשמוצגת בקשה לבחור שפה, בוחרים באפשרות Javascript ומקישים על Enter.

  6. לכל שאר האפשרויות, בוחרים את ברירות המחדל.

    הספרייה functions תיווצר. בתוך התיקייה תמצאו קובץ index.js שבעזרתו תוכלו לפתח את הפונקציה, ספרייה node_modules שמכילה את יחסי התלות של הפונקציה וקובץ package.json שמכיל את יחסי התלות של החבילה.

  7. כדי להוסיף את החבילות Admin SDK ו-Vertex AI, מריצים את את הפקודות הבאות, באמצעות --save כדי לוודא שהוא נשמר קובץ package.json:

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

עכשיו קובץ functions/package.json אמור להיראות כמו בדוגמה הבאה, עם הגרסאות האחרונות שצוינו:

  {
    "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, תופיע סטנזה שכוללת אותו. בנוסף, חשוב לוודא שגרסת מנוע הצמתים תואמת לגרסה של Node.js שמותקנת אצלכם ולגרסה שאתם מריצים בסופו של דבר ב-Google Cloud. לדוגמה, אם הבית engines ב-package.json מוגדר כגרסה 18 ו- משתמשים ב-Node.js 20, מעדכנים את הקובץ כך שישתמשו ב-20:

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

שלב 3: מגדירים הרשאות IAM לחשבון השירות Admin SDK ושומרים את המפתח

בפתרון הזה, תשתמשו בחשבון השירות Admin SDK של Firebase כדי לפעול את הפונקציה.

  1. במסוף Google Cloud, פותחים את הדף IAM & Admin ומאתרים את חשבון השירות Admin SDK (שנקרא firebase-adminsdk).
  2. בוחרים את החשבון ולוחצים על Edit principal. הדף 'עריכת גישה' מופיעה.
  3. לוחצים על Add another role ובוחרים באפשרות Remote Config Viewer.
  4. לוחצים על Add another role (הוספת תפקיד נוסף) ובוחרים באפשרות AI platform developer (מפתח פלטפורמת AI).
  5. לוחצים על הוספת תפקיד נוסף ובוחרים באפשרות משתמש אחד (Vertex AI).
  6. לוחצים על Add another role ובוחרים באפשרות Cloud Run Invoker.
  7. לוחצים על שמירה.

בשלב הבא, צריך לייצא את פרטי הכניסה של חשבון השירות Admin SDK ולשמור אותם במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

  1. במסוף Google Cloud, פותחים את הדף 'פרטי כניסה'.
  2. לוחצים על חשבון השירות Admin SDK כדי לפתוח את דף פרטים.
  3. לוחצים על Keys.
  4. לוחצים על Add key > יצירת מפתח חדש.
  5. מוודאים שהאפשרות JSON מסומנת בתור Key type ולוחצים על Create.
  6. מורידים את המפתח למקום בטוח במחשב.

  7. מייצאים את המפתח כמשתנה סביבה מהמסוף:

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

שלב 4: יוצרים את הפונקציה

בשלב הזה, נתכנן פונקציה שתטפל בקלט של המשתמשים ותיצור תשובות שמבוססות על AI. תשלבו כמה קטעי קוד כדי ליצור פונקציה מקיפה שמאתחלת את Admin SDK Vertex AI Gemini API, מגדיר פרמטרים של ברירת מחדל באמצעות Remote Config, אחזור הפרמטרים והתהליכים האחרונים של Remote Config קלט של משתמשים, ומשדר תגובה חזרה למשתמש.

  1. ב-codebase, פותחים את functions/index.js בכלי לעריכת טקסט או בסביבת פיתוח משולבת (IDE).

  2. למחוק את התוכן הקיים ולהוסיף את Admin SDK, Remote Config, ואת ה-SDK Vertex AI ומפעילים את האפליקציה על ידי להדביק את הקוד הבא בקובץ:

    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. מגדירים את ערכי ברירת המחדל שהפונקציה תשתמש בהם אם היא לא יכולה להתחבר אליהם השרת Remote Config. הפתרון הזה מגדיר את הערכים textModel,‏ generationConfig,‏ safetySettings,‏ textPrompt ו-location כפרמטרים של Remote Config שתואמים לפרמטרים של Remote Config שתגדירו בהמשך המדריך. למידע נוסף על הפרמטרים האלה, ראו לקוח Node.js של Vertex AI.

    אפשר גם להגדיר פרמטר כדי לקבוע אם תהיה גישה ל-Vertex AI Gemini API או לא (בדוגמה הזו, פרמטר שנקרא vertex_enabled). ההגדרה הזו יכולה להיות שימושית כשבודקים את הפונקציה. לחשבון את קטעי הקוד הבאים, הערך הזה מוגדר ל-false, שידלג באמצעות Vertex AI בזמן שבודקים את פריסת הפונקציה הבסיסית. הגדרה של הערך true תפעיל את 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. יצירת הפונקציה והגדרה Remote Config בצד השרת:

    // 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 ומוסיפים את הלוגיקה של הצ'אט והתשובות:

      // 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. שומרים וסוגרים את הקובץ.

שלב 5: יוצרים תבנית Remote Config ספציפית לשרת

בשלב הבא, יוצרים תבנית Remote Config בצד השרת ומגדירים פרמטרים וערכים לשימוש בפונקציה. כדי ליצור תבנית Remote Config ספציפית לשרת:

  1. פותחים את המסוף של Firebase, ובתפריט הניווט מרחיבים הפעלה ובוחרים Remote Config

  2. בוחרים באפשרות Server (שרת) מהבורר Client/Server בחלק העליון של הדף דף Remote Config.

    • אם זו הפעם הראשונה שאתם משתמשים ב-Remote Config או בתבניות שרת, לוחצים על Create Configuration. מופיעה החלונית יצירת הפרמטר הראשון בצד השרת.
    • אם זו לא הפעם הראשונה שאתם משתמשים בתבניות השרת של Remote Config, לוחצים על Add parameter.

  3. מגדירים את הפרמטרים הבאים של Remote Config:

    שם הפרמטר תיאור סוג ערך ברירת מחדל
    model_name שם המודל
    לרשימות עדכניות של שמות מודלים לשימוש בקוד, אפשר לעיין במאמרים גרסאות ותקופות חיים של מודלים או שמות מודלים זמינים.     		String gemini-1.5-pro-preview-0514
    prompt בקשה שתתווסף בתחילת השאילתה של המשתמש. 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 פרמטרים לשלוח למודל. JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings הגדרות הבטיחות של Vertex AI. JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location המיקום שבו מריצים את השירות והמודל Vertex AI. String us-central1
    is_vertex_enabled פרמטר אופציונלי שקובע אם שאילתות נשלחות אל Vertex AI. בוליאני true

  4. אחרי שמסיימים להוסיף פרמטרים, מומלץ לבדוק שוב את הפרמטרים שסוגי הנתונים שלהם נכונים, ולאחר מכן לוחצים על פרסום השינויים.

שלב 6: פורסים את הפונקציה ובודקים אותה ב-Firebase Local Emulator Suite

עכשיו אתם מוכנים לפרוס ולבדוק את הפונקציה שלכם באופן מקומי באמצעות Firebase Local Emulator Suite

  1. חשוב לוודא שהגדרתם את GOOGLE_APPLICATION_CREDENTIALS כמשתנה סביבה, כפי שמתואר בקטע שלב 3: מגדירים הרשאות IAM לחשבון השירות Admin SDK ושומרים את המפתח. לאחר מכן, מתוך של ספריית ההורה functions, פורסים את הפונקציה אמולטור Firebase:

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

  2. פותחים את דף היומנים של המהדר‬. הפונקציה אמורה להיטען.

  3. מריצים את הפקודה הבאה כדי לגשת לפונקציה, כאשר PROJECT_ID הוא מזהה הפרויקט ו LOCATION הוא האזור שפרסת הפונקציה כדי (לדוגמה, us-central1):

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

  4. מחכים לתגובה, חוזרים לדף היומנים של Firebase Emulator או למסוף ובודקים אם יש שגיאות או אזהרות.

  5. כדאי לנסות לשלוח קלט ממשתמשים. לתשומת ליבך, מכיוון ש-is_vertex_enabled הוא מוגדר בתבנית השרת של Remote Config, צריכה להיות גישה Gemini דרך Vertex AI Gemini API, וייתכן שהדבר עשוי כרוכים בחיובים:

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

  6. מבצעים שינויים בתבנית השרת Remote Config במסוף Firebase, ואז ניגשים מחדש לפונקציה כדי לראות את השינויים.

שלב 7: פריסת הפונקציה ב-Google Cloud

אחרי שבדקתם ואימתתם את הפונקציה, אתם מוכנים לפרוס Google Cloud ובודקים את הפונקציה הפעילה.

פריסת הפונקציה

פורסים את הפונקציה באמצעות CLI של Firebase:

firebase deploy --only functions

חסימת גישה לא מאומתת לפונקציה

כשפורסים פונקציות באמצעות Firebase, הפעלות לא מאומתות מותרת כברירת מחדל אם מדיניות הארגון לא מגבילה אותו. במהלך הבדיקה, לפני שמבצעים אבטחה באמצעות App Check, מומלץ לחסום גישה לא מאומתת.

כדי לחסום גישה לא מאומתת לפונקציה:

  1. במסוף Google Cloud, פותחים את Cloud Run.

  2. לוחצים על generateWithVertex ואז על הכרטיסייה Security (אבטחה).

  3. מפעילים את האפשרות דרישת אימות ולוחצים על שמירה.

מגדירים את חשבון המשתמש כך שישתמש בפרטי הכניסה של חשבון השירות Admin SDK

כי לחשבון השירות של Admin SDK יש את כל התפקידים הנדרשים הרשאות להפעלת הפונקציה ולקיים אינטראקציה עם Remote Config Vertex AI Gemini API, עליך להשתמש בו כדי להריץ את הפונקציה. לבצע זו צריכה להיות אפשרות ליצור אסימונים לחשבון דרך חשבון המשתמש.

השלבים הבאים מתארים איך להגדיר את חשבון המשתמש ואת הפונקציה להריץ עם ההרשאות Admin SDK של חשבון השירות.

  1. במסוף Google Cloud, מפעילים את IAM Service Account Credentials API.
  2. מקצים לחשבון המשתמש את התפקיד יצירת אסימונים בחשבון שירות: מסוף Google Cloud, פותחים את IAM & אדמין > IAM, בוחרים את המשתמש ואז לוחצים על Edit principal > הוספת תפקיד.

  3. בוחרים באפשרות יצירת אסימונים בחשבון שירות ולוחצים על שמירה.

    למידע מפורט יותר על התחזות לחשבון שירות: חשבון שירות התחזות במסמכי התיעוד בנושא Google Cloud.

  4. פותחים את הדף Cloud Functions במסוף Google Cloud ולוחצים על הפונקציה generateWithVertex ברשימה Functions.

  5. בוחרים באפשרות Trigger (טריגר) > Edit (עריכה) ומרחיבים את הקטע Runtime, build, connections and security settings (זמן ריצה, build, חיבורים והגדרות אבטחה).

  6. בכרטיסייה סביבת זמן הריצה, משנים את חשבון השירות של סביבת זמן הריצה לערך חשבון Admin SDK.

  7. לוחצים על Next (הבא) ואז על Deploy (פריסה).

הגדרת ה-CLI של gcloud

כדי להריץ ולבדוק את הפונקציה באופן מאובטח משורת הפקודה, צריך לבצע אימות מול השירות Cloud Functions ולקבל קוד אימות אסימון האימות.

כדי להפעיל את יצירת האסימונים, מתקינים ומגדירים את ה-CLI של gcloud:

  1. אם עדיין לא התקנתם את ה-CLI של gcloud במחשב, התקינו את ה-CLI של gcloud שמתואר במאמר התקנת gcloud CLI.

  2. מקבלים את פרטי הכניסה לחשבון Google Cloud:

    gcloud auth login

  3. מגדירים את מזהה הפרויקט ב-gcloud:

    gcloud config set project PROJECT_ID

בדיקת הפונקציה

עכשיו אפשר לבדוק את הפונקציה ב-Google Cloud. כדי לבדוק את הפונקציה, מריצים את הפקודה הבאה:

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

ניסיון חוזר עם נתונים שהמשתמשים סיפקו:

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"

עכשיו אפשר לבצע שינויים בתבנית השרת של Remote Config ולפרסם ולבדוק אפשרויות שונות.

השלבים הבאים