במדריך הזה מוסבר איך להתחיל להשתמש ב-2nd gen Cloud Functions עם server-side 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 הבסיסי שלו באופן אוטומטי) על ידי הזנת שם פרויקט חדש בשלב הראשון של תהליך העבודה 'יצירת פרויקט'.
- אפשרות 2: מוסיפים את Firebase לפרויקט Google Cloud קיים על ידי בחירת שם הפרויקט Google Cloud מהתפריט הנפתח בשלב הראשון של תהליך העבודה 'יצירת פרויקט'.
כשמוצגת בקשה, לא צריך להגדיר את Google Analytics כדי להשתמש בפתרון הזה.
ממשיכים לפעול לפי ההוראות במסך כדי ליצור את הפרויקט.
אם כבר יש לכם פרויקט Firebase:
ממשיכים אל הגדרת סביבת הפיתוח.
הגדרת סביבת הפיתוח
כדי לכתוב פונקציות, תצטרכו סביבת Node.js, וכדי לפרוס פונקציות בסביבת זמן הריצה Cloud Functions, תצטרכו את Firebase CLI.
-
כדי להתקין את Node.js ואת npm, מומלץ להשתמש ב-Node Version Manager.
מתקינים את Firebase CLI באמצעות השיטה המועדפת. לדוגמה, כדי להתקין את ה-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: הפעלת ממשקי API מומלצים במסוף Google CloudVertex AI
- פותחים את מסוף 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). מוחקים את התוכן הקיים ואז מוסיפים את Admin SDK, Remote Config ואת Vertex AI SDK ומפעילים את האפליקציה על ידי הדבקת הקוד הבא בקובץ:
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();
מגדירים ערכי ברירת מחדל שהפונקציה תשתמש בהם אם היא לא תוכל להתחבר לשרת 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 };
יוצרים את הפונקציה ומגדירים אימות בצד השרת 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;
מגדירים את 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'); } });
שומרים את הקובץ וסוגרים אותו.
שלב 5: יצירת תבנית Remote Config ספציפית לשרת
לאחר מכן, יוצרים תבנית Remote Config בצד השרת ומגדירים פרמטרים וערכים לשימוש בפונקציה. כדי ליצור תבנית Remote Configספציפית לשרת:
- פותחים את מסוף Firebase, בתפריט הניווט מרחיבים את Run ובוחרים באפשרות Remote Config.
בוחרים באפשרות Server (שרת) בבורר Client/Server (לקוח/שרת) בחלק העליון של הדף Remote Config.
- אם זו הפעם הראשונה שאתם משתמשים ב-Remote Config או בתבניות שרת, לוחצים על יצירת הגדרה. מופיעה החלונית יצירת הפרמטר הראשון בצד השרת.
- אם זאת לא הפעם הראשונה שאתם משתמשים בRemote Config תבניות של שרתים, לוחצים על Add parameter (הוספת פרמטר).
מגדירים את הפרמטרים הבאים של 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פותחים את דף היומנים של האמולטור. אמור להופיע שהפונקציה נטענה.
מריצים את הפקודה הבאה כדי לגשת לפונקציה, כאשר PROJECT_ID הוא מזהה הפרויקט ו-LOCATION הוא האזור שבו הפונקציה נפרסה (לדוגמה,
us-central1
):curl http://localhost:5001/
PROJECT_ID /LOCATION /generateWithVertexמחכים לתגובה, ואז חוזרים לדף היומנים של Firebase Emulator או למסוף ובודקים אם יש שגיאות או אזהרות.
נסו לשלוח קלט משתמש, תוך שימו לב לכך שהמודל Gemini מוגדר בתבנית השרת Remote Config שלכם, ולכן הוא אמור לגשת למודל דרך Vertex AI Gemini API, ושיכול להיות שייגבו מכם על כך תשלומים:
is_vertex_enabled
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 service account (חשבון שירות של זמן הריצה) לAdmin SDK account (חשבון Admin 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 במאמר הפעלת Vertex AI Gemini API עם Remote Config ועם App Check.
- מידע נוסף על Cloud Functions ל-Firebase
- מידע נוסף על שימוש ב-Remote Config בסביבות שרת