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

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

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

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

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

הגדרת פרויקט Firebase

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

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

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

    • אפשרות 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, מומלץ להשתמש ב-Node Version Manager.

  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: מפעילים את ממשקי ה-API המומלצים של Vertex AI במסוף Google Cloud

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

  4. לוחצים על Enable All Recommended APIs.

    הפעלת ה-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 מוגדר כ-Node בגרסה 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. הדף Edit access יופיע.
  3. לוחצים על Add another role ובוחרים באפשרות Remote Config Viewer.
  4. לוחצים על Add another role ובוחרים באפשרות AI platform developer.
  5. לוחצים על Add another role ובוחרים באפשרות Vertex AI user.
  6. לוחצים על Add another role ובוחרים באפשרות Cloud Run Invoker.
  7. לוחצים על שמירה.

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

  1. במסוף Google Cloud, פותחים את הדף Credentials.
  2. לוחצים על חשבון השירות Admin SDK כדי לפתוח את הדף פרטים.
  3. לוחצים על Keys.
  4. לוחצים על Add key (הוספת מפתח) > Create new 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. בקוד, פותחים את functions/index.js בכלי לעריכת טקסט או בסביבת פיתוח משולבת (IDE).

  2. מוחקים את התוכן הקיים, מוסיפים את ערכות ה-SDK של Admin SDK, ‏ Remote Config ו-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-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. יוצרים את הפונקציה ומגדירים 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, בתפריט הניווט מרחיבים את הקטע Run ובוחרים באפשרות 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-flash-002
    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 ושומרים את המפתח. לאחר מכן, מפריסים את הפונקציה במהנתח Firebase מהספרייה הראשית של ספריית functions:

    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 & Admin‏ > IAM, בוחרים את חשבון המשתמש ולוחצים על Edit principal‏ > Add another role.

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

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

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

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

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

  7. לוחצים על Next ואז על Deploy.

הגדרת ה-CLI של gcloud

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

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

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

  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, לפרסם את השינויים ולבדוק אפשרויות שונות.

השלבים הבאים