این راهنما نحوه شروع به استفاده از Cloud Functions نسل دوم با Remote Config سمت سرور را برای برقراری تماسهای سمت سرور به API Vertex AI Gemini شرح میدهد.
در این آموزش، Remote Config به یک تابع شبیه به چتبات اضافه خواهید کرد که از مدل Gemini برای پاسخ به سوالات کاربر استفاده میکند. Remote Config ورودیهای API Gemini (از جمله اعلانی که به درخواستهای ورودی کاربر اضافه میکنید) را مدیریت میکند و میتوانید این ورودیها را به صورت درخواست از کنسول Firebase بهروزرسانی کنید. همچنین Firebase Local Emulator Suite برای آزمایش و اشکالزدایی تابع استفاده خواهید کرد و سپس، پس از تأیید عملکرد، آن را در Google Cloud مستقر و آزمایش خواهید کرد.
پیشنیازها
این راهنما فرض میکند که شما با استفاده از جاوا اسکریپت برای توسعه برنامهها آشنا هستید.
راهاندازی یک پروژه فایربیس
اگر از قبل پروژه Firebase ندارید:
وارد کنسول Firebase شوید.
روی ایجاد پروژه کلیک کنید و سپس از یکی از گزینههای زیر استفاده کنید:
- گزینه ۱ : با وارد کردن نام پروژه جدید در اولین مرحله از گردش کار «ایجاد پروژه»، یک پروژه Firebase جدید (و پروژه Google Cloud زیربنایی آن به طور خودکار) ایجاد کنید.
- گزینه ۲ : با انتخاب نام پروژه Google Cloud خود از منوی کشویی در مرحله اول گردش کار «ایجاد پروژه»، «افزودن فایربیس» را به یک پروژه Google Cloud موجود اضافه کنید.
وقتی از شما خواسته شد، برای استفاده از این راهکار نیازی به تنظیم Google Analytics ندارید .
برای ایجاد پروژه خود، دستورالعملهای روی صفحه را دنبال کنید.
اگر از قبل یک پروژه Firebase دارید:
به پیکربندی محیط توسعه خود ادامه دهید.
محیط توسعه خود را پیکربندی کنید
برای نوشتن توابع به یک محیط Node.js و برای استقرار توابع در زمان اجرای Cloud Functions به Firebase CLI نیاز خواهید داشت.
برای نصب Node.js و npm ، توصیه میکنیم از Node Version Manager استفاده کنید.
رابط خط Firebase را با استفاده از روش دلخواه خود نصب کنید . برای مثال، برای نصب رابط خط فرمان با استفاده از 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 مستقر کنید .
مرحله ۱: فعال کردن API های پیشنهادی Vertex AI در کنسول Google Cloud
- کنسول Google Cloud را باز کنید و در صورت درخواست، پروژه خود را انتخاب کنید.
- در قسمت جستجو در بالای کنسول، عبارت Vertex AI را وارد کنید و منتظر بمانید تا Vertex AI به عنوان نتیجه نمایش داده شود.
- Vertex AI را انتخاب کنید. داشبورد Vertex AI ظاهر میشود.
روی فعال کردن همه API های توصیه شده کلیک کنید.
ممکن است فعالسازی API چند لحظه طول بکشد. صفحه را فعال و باز نگه دارید تا فعالسازی تمام شود.
اگر صورتحساب فعال نباشد، از شما خواسته میشود که یک حساب Cloud Billing اضافه یا پیوند دهید. پس از فعال کردن حساب صورتحساب، به داشبورد Vertex AI برگردید و تأیید کنید که همه API های توصیه شده فعال هستند.
مرحله ۲: پروژه خود را راهاندازی کنید و وابستگیهای Node را نصب کنید
- یک ترمینال روی رایانه خود باز کنید و به دایرکتوری که قصد دارید تابع خود را در آن ایجاد کنید، بروید.
وارد فایربیس شوید:
firebase login
برای مقداردهی اولیه Cloud Functions for Firebase دستور زیر را اجرا کنید:
firebase init functions
گزینه «استفاده از یک پروژه موجود» را انتخاب کنید و شناسه پروژه خود را مشخص کنید.
وقتی از شما خواسته شد زبان مورد استفاده را انتخاب کنید، جاوا اسکریپت را انتخاب کرده و 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"
},
مرحله ۳: مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید
در این راهکار، از حساب کاربری سرویس Firebase Admin SDK برای اجرای تابع خود استفاده خواهید کرد.
- در کنسول Google Cloud ، صفحه IAM & Admin را باز کنید و حساب سرویس Admin SDK (با نام
firebase-adminsdk
) را پیدا کنید. - حساب را انتخاب کنید و روی «ویرایش مدیر» کلیک کنید. صفحه «ویرایش دسترسی» ظاهر میشود.
- روی افزودن یک نقش دیگر کلیک کنید، نمایشگر Remote Config را انتخاب کنید.
- روی «افزودن یک نقش دیگر» کلیک کنید، توسعهدهنده پلتفرم هوش مصنوعی را انتخاب کنید.
- روی افزودن نقش دیگر کلیک کنید، کاربر Vertex AI را انتخاب کنید.
- روی افزودن نقش دیگر کلیک کنید، Cloud Run Invoker را انتخاب کنید.
- روی ذخیره کلیک کنید.
در مرحله بعد، اعتبارنامههای حساب سرویس Admin SDK را صادر کرده و آنها را در متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS
خود ذخیره کنید.
- در کنسول Google Cloud ، صفحه اعتبارنامهها (Credentials) را باز کنید.
- برای باز کردن صفحه جزئیات ، روی حساب سرویس Admin SDK کلیک کنید.
- روی کلیدها کلیک کنید.
- روی افزودن کلید > ایجاد کلید جدید کلیک کنید.
- مطمئن شوید که نوع کلید (Key type) از نوع JSON انتخاب شده باشد، سپس روی Create کلیک کنید.
- کلید را در یک مکان امن در رایانه خود دانلود کنید.
از ترمینال خود، کلید را به عنوان یک متغیر محیطی صادر کنید:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
مرحله ۴: ایجاد تابع
در این مرحله، تابعی خواهید ساخت که ورودی کاربر را مدیریت کرده و پاسخهای مبتنی بر هوش مصنوعی تولید میکند. شما چندین قطعه کد را برای ساخت یک تابع جامع ترکیب خواهید کرد که 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/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 client مراجعه کنید.به صورت اختیاری، میتوانید پارامتری را برای کنترل دسترسی یا عدم دسترسی به API مربوط به Vertex AI Gemini پیکربندی کنید (در این مثال، پارامتری به نام
vertex_enabled
). این تنظیم میتواند هنگام آزمایش تابع شما مفید باشد. در قطعه کد زیر، این مقدار رویfalse
تنظیم شده است که در هنگام آزمایش استقرار اولیه تابع، از استفاده از Vertex AI صرف نظر میکند. تنظیم آن رویtrue
، API مربوط به Vertex AI Gemini را فراخوانی میکند.// 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'); } });
فایل را ذخیره کنید و ببندید.
مرحله ۵: ایجاد یک الگوی Remote Config مخصوص سرور
در مرحله بعد، یک الگوی Remote Config سمت سرور ایجاد کنید و پارامترها و مقادیری را که میخواهید در تابع خود استفاده کنید، پیکربندی کنید. برای ایجاد یک الگوی Remote Config مخصوص سرور:
- کنسول Firebase را باز کنید و از منوی ناوبری، Run را باز کرده و Remote Config انتخاب کنید.
از قسمت انتخاب کلاینت/سرور در بالای صفحه Remote Config ، گزینه سرور را انتخاب کنید.
- اگر این اولین بار است که از Remote Config یا الگوهای سرور استفاده میکنید، روی Create Configuration کلیک کنید. پنجره Create your first server-side parameter ظاهر میشود.
- اگر این اولین بار نیست که از قالبهای سرور 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
پارامترهایی که باید به مدل ارسال شوند . جیسون [{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]
safety_settings
تنظیمات ایمنی برای هوش مصنوعی ورتکس جیسون [{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]
location
مکانی برای اجرای سرویس هوش مصنوعی و مدلسازی Vertex . رشته 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 یا کنسول خود برگردید و هرگونه خطا یا هشداری را بررسی کنید.
سعی کنید ورودی کاربر را ارسال کنید، توجه داشته باشید که از آنجا که
is_vertex_enabled
در الگوی سرور Remote Config شما پیکربندی شده است، این باید از طریق API Vertex AI Gemini به مدل Gemini دسترسی پیدا کند و این ممکن است هزینههایی را متحمل شود:curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
در کنسول Firebase تغییراتی در الگوی سرور Remote Config خود ایجاد کنید، سپس برای مشاهده تغییرات، دوباره به تابع خود دسترسی پیدا کنید.
مرحله ۷: تابع خود را در Google Cloud مستقر کنید
پس از اینکه تابع خود را آزمایش و تأیید کردید، آمادهاید تا آن را در Google Cloud مستقر کنید و تابع را به صورت زنده آزمایش کنید.
تابع خود را مستقر کنید
تابع خود را با استفاده از Firebase CLI مستقر کنید:
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 ، API مربوط به اعتبارنامههای حساب کاربری سرویس IAM را فعال کنید.
- به حساب کاربری خود نقش Service Account Token Creator (ایجادکننده توکن حساب سرویس) را بدهید: از کنسول Google Cloud ، IAM & Admin > IAM را باز کنید، حساب کاربری خود را انتخاب کنید و سپس روی Edit principal > Add another role (ویرایش مدیر اصلی) کلیک کنید.
گزینه «ایجادکننده توکن حساب سرویس» را انتخاب کنید، سپس روی ذخیره کلیک کنید.
برای اطلاعات بیشتر در مورد جعل هویت حساب سرویس، به جعل هویت حساب سرویس در مستندات Google Cloud مراجعه کنید.
صفحه Cloud Functions کنسول Google Cloud را باز کنید و در لیست توابع ، روی تابع generateWithVertex کلیک کنید.
Trigger > Edit را انتخاب کنید و Runtime, build, connections and security settings را باز کنید.
از تب Runtime ، حساب سرویس Runtime را به حساب Admin SDK تغییر دهید.
روی «بعدی» کلیک کنید، سپس روی «استقرار» کلیک کنید.
تنظیمات رابط خط فرمان gcloud
برای اجرای ایمن و آزمایش تابع خود از خط فرمان، باید با سرویس Cloud Functions احراز هویت کنید و یک توکن احراز هویت معتبر دریافت کنید.
برای فعال کردن تولید توکن، رابط خط فرمان gcloud را نصب و پیکربندی کنید:
اگر از قبل gcloud CLI روی رایانه شما نصب نشده است، آن را همانطور که در بخش «نصب 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 خود ایجاد کنید، آن تغییرات را منتشر کنید و گزینههای مختلف را آزمایش کنید.
مراحل بعدی
- فایربیس استفاده از App Check را برای ایمنسازی Cloud Functions توصیه میکند. برای اطلاعات بیشتر در مورد ایمنسازی تابع خود با App Check به Cloud Functions Enable App Check enforcement for Cloud Functions مراجعه کنید.
- یک تابع نمونه قابل فراخوانی با Remote Config و App Check سمت سرور را در Call the Vertex AI Gemini API with Remote Config and App Check امتحان کنید.
- درباره Cloud Functions برای فایربیس بیشتر بدانید.
- درباره استفاده از Remote Config در محیطهای سرور بیشتر بدانید.