این راهنما نحوه شروع استفاده از Cloud Functions نسل دوم را با Remote Config سمت سرور برای برقراری تماسهای سمت سرور با Vertex AI Gemini API توضیح میدهد.
در این آموزش، Remote Config به تابعی شبیه ربات چت اضافه میکنید که از مدل Gemini برای پاسخ به سؤالات کاربر استفاده میکند. Remote Config ورودیهای Gemini API را مدیریت میکند (از جمله درخواستی که به درخواستهای کاربر وارد میشود)، و میتوانید این ورودیها را بر حسب تقاضا از کنسول Firebase بهروزرسانی کنید. همچنین Firebase Local Emulator Suite برای آزمایش و اشکالزدایی عملکرد استفاده میکنید، و پس از تأیید عملکرد آن، آن را در Google Cloud اجرا و آزمایش خواهید کرد.
پیش نیازها
این راهنما فرض می کند که شما با استفاده از جاوا اسکریپت برای توسعه برنامه ها آشنا هستید.
یک پروژه 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 فعال کنید .
- پروژه خود را راه اندازی کنید و Dependencies Node را نصب کنید .
- مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید .
- تابع را ایجاد کنید .
- یک الگوی Remote Config مخصوص سرور ایجاد کنید .
- تابع خود را اجرا کنید و آن را در Firebase Local Emulator Suite آزمایش کنید .
- تابع خود را در Google Cloud مستقر کنید .
مرحله 1: API های توصیه شده Vertex AI در کنسول 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
استفاده از پروژه موجود را انتخاب کنید و ID پروژه خود را مشخص کنید.
هنگامی که از شما خواسته شد زبان مورد استفاده را انتخاب کنید، جاوا اسکریپت را انتخاب کنید و 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 خود پیکربندی کنید و کلید خود را ذخیره کنید
در این راه حل، از حساب سرویس Firebase Admin SDK برای اجرای عملکرد خود استفاده خواهید کرد.
- در کنسول Google Cloud ، صفحه IAM & Admin را باز کنید و حساب سرویس Admin SDK (با نام
firebase-adminsdk
) را پیدا کنید. - حساب را انتخاب کنید و روی Edit principal کلیک کنید. صفحه دسترسی ویرایش ظاهر می شود.
- روی افزودن نقش دیگری کلیک کنید، Remote Config Viewer را انتخاب کنید.
- روی افزودن نقش دیگری کلیک کنید، توسعه دهنده پلتفرم هوش مصنوعی را انتخاب کنید.
- روی افزودن نقش دیگری کلیک کنید، Vertex AI user را انتخاب کنید.
- روی افزودن نقش دیگری کلیک کنید، Cloud Run Invoker را انتخاب کنید.
- روی ذخیره کلیک کنید.
سپس، اعتبارنامههای حساب سرویس Admin SDK را صادر کرده و در متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS
خود ذخیره کنید.
- در کنسول Google Cloud ، صفحه اعتبارنامه ها را باز کنید.
- روی حساب سرویس Admin SDK کلیک کنید تا صفحه جزئیات باز شود.
- روی کلیدها کلیک کنید.
- روی افزودن کلید > ایجاد کلید جدید کلیک کنید.
- مطمئن شوید که JSON به عنوان نوع کلید انتخاب شده است، سپس روی Create کلیک کنید.
- کلید یک مکان امن را در رایانه خود دانلود کنید.
از ترمینال خود، کلید را به عنوان یک متغیر محیطی صادر کنید:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
مرحله 4: تابع را ایجاد کنید
در این مرحله، تابعی می سازید که ورودی کاربر را مدیریت می کند و پاسخ های مبتنی بر هوش مصنوعی را تولید می کند. چند قطعه کد را برای ایجاد یک تابع جامع ترکیب میکنید که 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 مطابقت دارد، پیکربندی می کند که در ادامه در این راهنما پیکربندی می کنید. برای اطلاعات بیشتر در مورد این پارامترها، مشتری Vertex AI Node.js را ببینید.به صورت اختیاری، همچنین می توانید پارامتری را برای کنترل دسترسی یا عدم دسترسی به 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 یا الگوهای سرور استفاده میکنید، روی Create Configuration کلیک کنید. صفحه پارامتر Create your first سمت سرور ظاهر می شود.
- اگر این اولین بار نیست که از الگوهای سرور Remote Config استفاده میکنید، روی افزودن پارامتر کلیک کنید.
پارامترهای Remote Config زیر را تعریف کنید:
نام پارامتر توضیحات تایپ کنید مقدار پیش فرض model_name
نام مدل
برای لیستهای بهروز نام مدلها برای استفاده در کدتان، نسخههای مدل و چرخههای عمر یا نامهای مدل موجود را ببینید.رشته gemini-1.5-flash-002
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 یا کنسول خود بازگردید و خطاها یا هشدارها را بررسی کنید.
سعی کنید مقداری از ورودی کاربر را ارسال کنید، توجه داشته باشید که چون
is_vertex_enabled
در الگوی سرور Remote Config پیکربندی شده است، باید از طریق Vertex AI Gemini API به Gemini دسترسی داشته باشد و ممکن است هزینههایی در پی داشته باشد:curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
در کنسول Firebase تغییراتی را در قالب سرور Remote Config ایجاد کنید، سپس دوباره به عملکرد خود برای مشاهده تغییرات دسترسی داشته باشید.
مرحله 7: تابع خود را در Google Cloud مستقر کنید
بعد از اینکه عملکرد خود را آزمایش و تأیید کردید، آماده استقرار در Google Cloud و آزمایش عملکرد زنده هستید.
عملکرد خود را مستقر کنید
تابع خود را با استفاده از Firebase CLI مستقر کنید:
firebase deploy --only functions
دسترسی بدون احراز هویت به عملکرد را مسدود کنید
هنگامی که توابع با استفاده از Firebase مستقر می شوند، اگر خط مشی سازمان شما آن را محدود نکند، فراخوان های احراز هویت نشده به طور پیش فرض مجاز هستند. در حین آزمایش و قبل از ایمن سازی با App Check ، توصیه می کنیم دسترسی های غیرقانونی را مسدود کنید.
برای مسدود کردن دسترسی غیرقانونی به عملکرد:
در کنسول Google Cloud ، Cloud Run را باز کنید.
روی
generateWithVertex
کلیک کنید، سپس روی زبانه Security کلیک کنید.Require authentication را فعال کنید و سپس روی Save کلیک کنید.
حساب کاربری خود را برای استفاده از اعتبار حساب سرویس Admin SDK پیکربندی کنید
از آنجایی که حساب سرویس Admin SDK دارای تمام نقشها و مجوزهای لازم برای اجرای عملکرد و تعامل با Remote Config و Vertex AI Gemini API است، باید از آن برای اجرای عملکرد خود استفاده کنید. برای انجام این کار، باید بتوانید از حساب کاربری خود، توکن هایی برای حساب ایجاد کنید.
مراحل زیر نحوه پیکربندی حساب کاربری خود و عملکرد اجرا با امتیازات حساب سرویس Admin SDK را شرح می دهد.
- در کنسول Google Cloud ، IAM Service Account Credentials API را فعال کنید.
- به حساب کاربری خود نقش ایجاد کننده رمز حساب حساب سرویس بدهید: از کنسول Google Cloud ، IAM & Admin > IAM را باز کنید، حساب کاربری خود را انتخاب کنید و سپس روی ویرایش اصلی > افزودن نقش دیگری کلیک کنید.
Service Account Token Creator را انتخاب کنید، سپس روی Save کلیک کنید.
برای اطلاعات بیشتر درباره جعل هویت حساب سرویس، به جعل هویت حساب سرویس در اسناد Google Cloud مراجعه کنید.
صفحه Google Cloud Console Cloud Functions را باز کنید و روی تابع generateWithVertex در لیست توابع کلیک کنید.
Trigger > Edit را انتخاب کنید و Runtime، ساخت، اتصالات و تنظیمات امنیتی را گسترش دهید.
از تب Runtime ، حساب سرویس Runtime را به حساب Admin SDK تغییر دهید.
روی Next کلیک کنید، سپس روی Deploy کلیک کنید.
gcloud CLI را راه اندازی کنید
برای اجرای ایمن و آزمایش عملکرد خود از طریق خط فرمان، باید با سرویس Cloud Functions احراز هویت کنید و یک نشانه احراز هویت معتبر دریافت کنید.
برای فعال کردن تولید توکن، gcloud CLI را نصب و پیکربندی کنید:
اگر قبلاً روی رایانه شما نصب نشده است، gcloud CLI را همانطور که در Install the gcloud CLI توضیح داده شده است نصب کنید.
اعتبار دسترسی برای حساب 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 مراجعه کنید.
- در Call the Vertex AI Gemini API with Remote Config و App Check یک نمونه تابع قابل فراخوانی را با Remote Config سمت سرور و App Check برنامه امتحان کنید.
- درباره Cloud Functions for Firebase بیشتر بیاموزید.
- درباره استفاده از Remote Config در محیط های سرور بیشتر بیاموزید.