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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    כדי להתקין את Node.js ואת npm, מומלץ להשתמש ב-Node Version Manager.

  2. מתקינים את Firebase CLI באמצעות השיטה המועדפת. לדוגמה, כדי להתקין את ה-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 ו-Agent Platform:

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

שלב 1: הפעלת ממשקי API מומלצים במסוף Agent PlatformGoogle Cloud

  1. פותחים את מסוף Google Cloud, וכשמתבקשים, בוחרים את הפרויקט.
  2. בשדה חיפוש בחלק העליון של המסוף, מזינים Agent Platform ומחכים שAgent Platform יופיע כתוצאה.
  3. בוחרים באפשרות Agent Platform. מוצג מרכז הבקרה Agent Platform.
  4. לוחצים על הפעלת כל ממשקי ה-API המומלצים.

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

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

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

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

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

    firebase init functions
    
  4. בוחרים באפשרות Use an existing project (שימוש בפרויקט קיים) ומציינים את מזהה הפרויקט.

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

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

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

  7. מריצים את הפקודות הבאות כדי להוסיף את החבילות Admin SDK ו-Agent Platform, ומשתמשים ב---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. לדוגמה, אם ה-stanza‏ engines בקובץ package.json מוגדר כ-Node גרסה 18 ואתם משתמשים ב-Node.js 20, צריך לעדכן את הקובץ לשימוש בגרסה 20:

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

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

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

  1. במסוף Google Cloud, פותחים את הדף IAM & Admin ומאתרים את חשבון השירות Admin SDK (בשם firebase-adminsdk).
  2. בוחרים את החשבון ולוחצים על עריכת הגורם המורשה. יופיע הדף 'עריכת הגישה'.
  3. לוחצים על הוספת תפקיד נוסף ובוחרים באפשרות Remote Config צפייה.
  4. לוחצים על Add another role (הוספת תפקיד נוסף) ובוחרים באפשרות AI platform developer (מפתח פלטפורמת AI).
  5. לוחצים על הוספת תפקיד נוסף ובוחרים באפשרות משתמש Agent Platform.
  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 ואת Agent Platform Gemini API (formerly Vertex AI), מגדירה פרמטרים שמוגדרים כברירת מחדל באמצעות Remote Config, מאחזרת את הפרמטרים האחרונים של Remote Config, מעבדת את קלט של משתמשים ומעבירה תגובה למשתמש.

  1. בבסיס הקוד, פותחים את functions/index.js בכלי לעריכת טקסט או בסביבת פיתוח משולבת (IDE).
  2. מוחקים את התוכן הקיים ואז מוסיפים את ערכות ה-SDK‏ Admin SDK, Remote Config ו-Agent Platform ומפעילים את האפליקציה על ידי הדבקת הקוד הבא בקובץ:

    const { onRequest } = require("firebase-functions/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();
    
  3. מגדירים ערכי ברירת מחדל שהפונקציה תשתמש בהם אם היא לא תוכל להתחבר לשרת Remote Config. בפתרון הזה, המערכת מגדירה את textModel, ‏ generationConfig, ‏ safetySettings, ‏ textPrompt ו-location כפרמטרים של Remote Config שתגדירו בהמשך המדריך הזה.Remote Config מידע נוסף על הפרמטרים האלה זמין במאמר בנושא לקוח Node.js של Vertex AI.

    אפשר גם להגדיר פרמטר כדי לקבוע אם תהיה לכם גישה ל-Agent Platform Gemini API (formerly Vertex AI) (בדוגמה הזו, פרמטר בשם vertex_enabled). ההגדרה הזו יכולה להיות שימושית כשבודקים את הפונקציה. בקטעי הקוד הבאים, הערך הזה מוגדר כ-false, כך שדילוג על השימוש ב-Agent Platform יתבצע בזמן בדיקת הפריסה של הפונקציה הבסיסית. הגדרת הערך true תפעיל את Agent Platform Gemini API (formerly Vertex AI).

    // 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. יוצרים את הפונקציה ומגדירים 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;
    
  5. מגדירים את Agent Platform ומוסיפים את הלוגיקה של הצ'אט והתשובות:

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

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

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

  1. במסוף Firebase, עוברים אל DevOps & Engagement (פיתוח אפליקציות ואינטראקציה עם משתמשים) >‏ הגדרת תצורה מרחוק.

  2. בתפריט Client/Server בחלק העליון של הדף, בוחרים באפשרות Server.

    • אם זו הפעם הראשונה שאתם משתמשים ב-Remote Config או בתבניות שרת, לוחצים על יצירת הגדרה. מופיע החלונית Create your first server-side parameter (יצירת הפרמטר הראשון בצד השרת).
    • אם זאת לא הפעם הראשונה שאתם משתמשים בRemote Config תבניות של שרתים, לוחצים על הוספת פרמטר.
  3. מגדירים את הפרמטרים הבאים של Remote Config:

    שם הפרמטר תיאור סוג ערך ברירת המחדל
    model_name שם המודל
    כדי לראות רשימות עדכניות של שמות המודלים שאפשר להשתמש בהם בקוד, אפשר לעיין במאמרים בנושא גרסאות של מודלים ומחזורי חיים או שמות מודלים זמינים.
    מחרוזת gemini-2.0-flash
    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!
    generation_config פרמטרים לשליחה למודל JSON [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
    safety_settings הגדרות בטיחות ל-Agent Platform JSON [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
    location המיקום שבו יופעלו שירות Agent Platform והמודל מחרוזת global
    is_vertex_enabled פרמטר אופציונלי שקובע אם השאילתות יישלחו אל Agent Platform. בוליאני 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 דרך Agent Platform Gemini API (formerly Vertex AI). שימו לב שייתכן שיהיו עלויות על הפעולה הזו:

    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 ולבדוק את הפונקציה הפעילה.

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

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

firebase deploy --only functions

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

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

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

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

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

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

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

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

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

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

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

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

  5. בוחרים באפשרות Trigger (טריגר) > Edit (עריכה) ומרחיבים את ההגדרות של זמן הריצה, ה-build, החיבורים והאבטחה.

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

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

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

השלבים הבאים