Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

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

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

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

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

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

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

הערה: אפשר גם להריץ פקודות של Firebase CLI ב-Cloud Shell. ‫Cloud Shell היא סביבת שורת פקודה מבוססת-דפדפן שעברה אימות מראש, שאפשר לגשת אליה ממסוף Firebase, וכוללת את Firebase CLI מותקן מראש. זו אפשרות נוחה להתחלת עבודה מהירה, בתנאי שמוסיפים את קובצי הפרויקט לסביבת Cloud Shell.
מתקינים את 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: הפעלת ממשקי API מומלצים במסוף Vertex AIGoogle Cloud

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

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

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

פותחים טרמינל במחשב ועוברים לספרייה שבה רוצים ליצור את הפונקציה.
מתחברים ל-Firebase:
```
firebase login
```
מריצים את הפקודה הבאה כדי לאתחל את Cloud Functions for Firebase:
```
firebase init functions
```
בוחרים באפשרות Use an existing project (שימוש בפרויקט קיים) ומציינים את מזהה הפרויקט.
כשמוצגת בקשה לבחירת השפה שבה רוצים להשתמש, בוחרים באפשרות 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 מוגדרת כגרסה 18 של Node ואתם משתמשים ב-Node.js 20, צריך לעדכן את הקובץ לגרסה 20:

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

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

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

במסוף Google Cloud, פותחים את הדף IAM & Admin ומאתרים את חשבון השירות Admin SDK (בשם firebase-adminsdk).
בוחרים את החשבון ולוחצים על עריכת הגורם המורשה. יופיע הדף 'עריכת הגישה'.
לוחצים על הוספת תפקיד נוסף ובוחרים באפשרות Remote Config צפייה.
לוחצים על Add another role (הוספת תפקיד נוסף) ובוחרים באפשרות AI platform developer (מפתח פלטפורמת AI).
לוחצים על הוספת תפקיד נוסף ובוחרים באפשרות משתמש 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 נבחרה בתור Key type ולוחצים על Create.
מורידים את המפתח למקום בטוח במחשב.

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

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/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 מידע נוסף על הפרמטרים האלה זמין במאמר Vertex AI Node.js client.

אפשר גם להגדיר פרמטר כדי לקבוע אם תהיה לכם גישה ל-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, עוברים אל DevOps & Engagement (פיתוח אפליקציות ואינטראקציה עם משתמשים) > הגדרת תצורה מרחוק.
בתפריט Client/Server בחלק העליון של הדף, בוחרים באפשרות Server.
- אם זו הפעם הראשונה שאתם משתמשים ב-Remote Config או בתבניות שרת, לוחצים על יצירת הגדרה. מופיעה החלונית יצירת הפרמטר הראשון בצד השרת.
- אם זאת לא הפעם הראשונה שאתם משתמשים בRemote Config תבניות של שרתים, לוחצים על הוספת פרמטר.

מגדירים את הפרמטרים הבאים של 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`	הגדרות הבטיחות של Vertex AI.	JSON	`[{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]`
`location`	מיקום להפעלת השירות והמודל של Vertex AI.	מחרוזת	`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 ולבדוק את הפונקציה הפעילה.

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

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

firebase deploy --only functions

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

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

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

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

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

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

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

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

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

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

השלבים הבאים

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