דף זה תורגם על ידי Cloud Translation API.

שימוש בהגדרת תצורה מרחוק בצד השרת עם 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:

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

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

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

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

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

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

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

חשוב: מומלץ להשתמש ב-Node.js מגרסה 20 ואילך. במאמר הגדרת אפשרויות בסביבת זמן הריצה מפורט מידע חשוב על התמיכה המתמשכת בגרסאות של Node.js.
מתקינים את ה-CLI של Firebase באמצעות השיטה המועדפת עליכם. לדוגמה, כדי להתקין את ה-CLI באמצעות npm, מריצים את הפקודה הבאה:
```
npm install -g firebase-tools@latest
```
הפקודה הזו מתקינה את הפקודה firebase שזמינה בכל העולם. אם הפקודה הזו נכשלת, יכול להיות שתצטרכו לשנות את ההרשאות של npm.

כדי לעדכן לגרסה האחרונה של firebase-tools, מריצים שוב את אותה הפקודה.
מתקינים את firebase-functions ואת firebase-admin ומשתמשים ב---save כדי לשמור אותם ב-package.json:
```
npm install firebase-functions@latest firebase-admin@latest --save
```

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

הטמעה

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

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

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

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

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

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

פותחים מסוף במחשב ועוברים לספרייה שבה רוצים ליצור את הפונקציה.
מתחברים ל-Firebase:
```
firebase login
```
מריצים את הפקודה הבאה כדי לאתחל את Cloud Functions for Firebase:
```
firebase init functions
```
בוחרים באפשרות שימוש בפרויקט קיים ומציינים את מזהה הפרויקט.
כשתוצג בקשה לבחור שפה, בוחרים באפשרות Javascript ומקישים על Enter.
בכל שאר האפשרויות, בוחרים את ערכי ברירת המחדל.

נוצרת ספרייה functions בספרייה הנוכחית. בתוכו תמצאו קובץ index.js שבו תשתמשו כדי ליצור את הפונקציה, ספריית node_modules שמכילה את יחסי התלות של הפונקציה וקובץ package.json שמכיל את יחסי התלות של החבילות.
מוסיפים את החבילות 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 כדי להריץ את הפונקציה.

במסוף Google Cloud, פותחים את הדף IAM &Admin ומאתרים את חשבון השירות Admin SDK (בשם firebase-adminsdk).
בוחרים את החשבון ולוחצים על Edit principal. הדף Edit access יופיע.
לוחצים על הוספת תפקיד נוסף, בוחרים באפשרות Remote Config צפייה.
לוחצים על Add another role (הוספת תפקיד נוסף) ובוחרים באפשרות AI platform developer (מפתח פלטפורמת AI).
לוחצים על Add another role (הוספת תפקיד נוסף), בוחרים באפשרות Vertex AI user (משתמש Vertex AI).
לוחצים על Add another role ובוחרים באפשרות Cloud Run Invoker.
לוחצים על שמירה.

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

במסוף Google Cloud, פותחים את הדף Credentials.
לוחצים על חשבון השירות Admin SDK כדי לפתוח את הדף פרטים.
לוחצים על Keys.
לוחצים על Add key (הוספת מפתח) > Create new key (יצירת מפתח חדש).
מוודאים שהאפשרות JSON מסומנת בתור סוג המפתח, ולאחר מכן לוחצים על יצירה.
מורידים את המפתח למקום בטוח במחשב.

מייצאים את המפתח כמשתנה סביבה מהטרמינל:

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

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

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

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

מוחקים את התוכן הקיים, מוסיפים את ערכות ה-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

מגדירים ערכים שמוגדרים כברירת מחדל, שבהם הפונקציה תשתמש אם היא לא תצליח להתחבר לשרת 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
```

יוצרים את הפונקציה ומגדירים את 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

מגדירים את 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

שומרים וסוגרים את הקובץ.

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

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

פותחים את מסוף Firebase, בתפריט הניווט מרחיבים את הקטע Run ובוחרים באפשרות Remote Config.
בוחרים את האפשרות Server מהבורר Client/Server בחלק העליון של הדף Remote Config.
- אם זו הפעם הראשונה שאתם משתמשים ב-Remote Config או בתבניות של שרתים, לוחצים על Create Configuration. מופיעה החלונית יצירת הפרמטר הראשון בצד השרת.
- אם זו לא הפעם הראשונה שאתם משתמשים בתבניות השרת של Remote Config, לוחצים על Add parameter.

מגדירים את הפרמטרים הבאים של 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`

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

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

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

חשוב לוודא שהגדרתם את GOOGLE_APPLICATION_CREDENTIALS כמשתנה סביבה, כפי שמתואר בקטע שלב 3: מגדירים הרשאות IAM לחשבון השירות Admin SDK ושומרים את המפתח. לאחר מכן, מספריית ההורה של ספריית functions, פורסים את הפונקציה לאמולטור של Firebase:
```
firebase emulators:start --project PROJECT_ID --only functions
```
טיפ: אפשר גם להריץ פונקציות במהלך ההדמיה על ידי הפעלת npm run serve מהספרייה functions.
פותחים את דף היומנים של המהדר‬. הפונקציה אמורה להיטען.
כדי לגשת לפונקציה, מריצים את הפקודה הבאה, שבה PROJECT_ID הוא מזהה הפרויקט ו-LOCATION הוא האזור שבו פרסתם את הפונקציה (לדוגמה, us-central1):
```
curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex
```
טיפ: הקישור הזה יופיע גם בפלט של המסוף אחרי שמפעילים את האמולטור. אפשר גם לגזור ולהדביק אותו בדפדפן.
מחכים לתגובה, חוזרים לדף היומנים של Firebase Emulator או למסוף ובודקים אם יש שגיאות או אזהרות.
נסו לשלוח קלט של משתמש. חשוב לזכור ש-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
```
מבצעים שינויים בתבנית השרת Remote Config במסוף Firebase, ואז ניגשים מחדש לפונקציה כדי לראות את השינויים.

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

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

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

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

firebase deploy --only functions

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

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

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

במסוף Google Cloud, פותחים את Cloud Run.
לוחצים על generateWithVertex ואז על הכרטיסייה Security (אבטחה).
מפעילים את האפשרות דרישה לאימות ולוחצים על שמירה.

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

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

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

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

מידע מפורט יותר על התחזות לחשבון שירות זמין במאמר התחזות לחשבון שירות במסמכי העזרה של Google Cloud.
פותחים את הדף Cloud Functions במסוף Google Cloud ולוחצים על הפונקציה generateWithVertex ברשימה Functions.
בוחרים באפשרות Trigger (טריגר) > Edit (עריכה) ומרחיבים את הקטע Runtime, build, connections and security settings (זמן ריצה, build, חיבורים והגדרות אבטחה).
בכרטיסייה Runtime, משנים את חשבון השירות בסביבת זמן הריצה לחשבון Admin SDK.
לוחצים על Next (הבא) ואז על Deploy (פריסה).

הגדרת ה-CLI של gcloud

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

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

אם עדיין לא התקנתם את ה-CLI של gcloud במחשב, כמו שמתואר במאמר התקנת ה-CLI של gcloud.
מקבלים את פרטי הכניסה לחשבון Google Cloud:
```
gcloud auth login
```
מגדירים את מזהה הפרויקט ב-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, לפרסם את השינויים ולבדוק אפשרויות שונות.

השלבים הבאים

ההמלצה של Firebase היא להשתמש ב-App Check כדי לאבטח את Cloud Functions. מידע נוסף על אבטחת הפונקציה באמצעות App Check זמין במאמר הפעלת אכיפה של App Check עבור Cloud Functions.
אפשר לנסות פונקציה לדוגמה שניתן להפעיל עם Remote Config ו-App Check בצד השרת במאמר קריאה לפונקציה Vertex AI Gemini API באמצעות Remote Config ו-App Check.
מידע נוסף על Cloud Functions ב-Firebase
מידע נוסף על שימוש ב-Remote Config בסביבות שרת