استفاده از پیکربندی از راه دور سمت سرور با توابع Cloud و Vertex AI، استفاده از پیکربندی از راه دور سمت سرور با توابع ابری و Vertex AI

این راهنما نحوه شروع استفاده از Cloud Functions نسل دوم را با Remote Config سمت سرور برای برقراری تماس‌های سمت سرور با Gemini API در Vertex AI شرح می‌دهد.

در این آموزش، Remote Config به یک تابع شبیه ربات چت اضافه می کنید که از یک مدل Gemini برای پاسخ به سؤالات کاربر استفاده می کند. Remote Config ورودی‌های Gemini API را مدیریت می‌کند (از جمله درخواستی که به درخواست‌های کاربر وارد می‌شود)، و می‌توانید این ورودی‌ها را بر حسب تقاضا از کنسول Firebase به‌روزرسانی کنید. همچنین از Firebase Local Emulator Suite برای آزمایش و اشکال‌زدایی عملکرد استفاده می‌کنید، و پس از تأیید عملکرد آن، آن را در Google Cloud اجرا و آزمایش خواهید کرد.

پیش نیازها

این راهنما فرض می کند که شما با استفاده از جاوا اسکریپت برای توسعه برنامه ها آشنا هستید.

یک پروژه Firebase راه اندازی کنید

اگر قبلاً پروژه Firebase ندارید:

  1. وارد کنسول Firebase شوید.

  2. روی ایجاد پروژه کلیک کنید و سپس از یکی از گزینه های زیر استفاده کنید:

    • گزینه 1 : با وارد کردن نام پروژه جدید در اولین مرحله از گردش کار «ایجاد پروژه»، یک پروژه Firebase جدید (و پروژه Google Cloud زیربنایی آن به صورت خودکار) ایجاد کنید.
    • گزینه 2 : «افزودن Firebase» به پروژه Google Cloud موجود با انتخاب نام پروژه Google Cloud خود از منوی کشویی در مرحله اول گردش کار «ایجاد پروژه».

  3. وقتی از شما خواسته شد، برای استفاده از این راه حل نیازی به راه اندازی Google Analytics ندارید .

  4. برای ایجاد پروژه خود، دستورالعمل های روی صفحه را دنبال کنید.

اگر قبلاً یک پروژه Firebase دارید:

به پیکربندی محیط توسعه خود ادامه دهید.

محیط توسعه خود را پیکربندی کنید

برای نوشتن توابع به یک محیط Node.js نیاز دارید و برای استقرار توابع در زمان اجرای Cloud Functions به Firebase CLI نیاز دارید.

  1. Node.js و npm را نصب کنید.

    برای نصب Node.js و npm ، توصیه می کنیم از Node Version Manager استفاده کنید.

  2. Firebase CLI را با استفاده از روش دلخواه خود نصب کنید . به عنوان مثال، برای نصب CLI با استفاده از npm، این دستور را اجرا کنید:

    npm install -g firebase-tools@latest

    این دستور دستور firebase جهانی را نصب می کند. اگر این دستور ناموفق باشد، ممکن است لازم باشد مجوزهای npm را تغییر دهید .

    برای به روز رسانی به آخرین نسخه firebase-tools ، همان دستور را دوباره اجرا کنید.

  3. firebase-functions و firebase-admin را نصب کنید و از --save برای ذخیره آنها در package.json خود استفاده کنید:

    npm install firebase-functions@latest firebase-admin@latest --save

اکنون برای ادامه اجرای این راه حل آماده هستید.

پیاده سازی

برای ایجاد، آزمایش و استقرار Cloud Functions نسل دوم خود با Remote Config و Vertex AI این مراحل را دنبال کنید:

  1. APIهای توصیه شده با هوش مصنوعی Vertex را در کنسول Google Cloud فعال کنید .
  2. پروژه خود را راه اندازی کنید و Dependencies Node را نصب کنید .
  3. مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید .
  4. تابع را ایجاد کنید .
  5. یک الگوی Remote Config مخصوص سرور ایجاد کنید .
  6. تابع خود را اجرا کنید و آن را در Firebase Local Emulator Suite آزمایش کنید .
  7. تابع خود را در Google Cloud مستقر کنید .

مرحله 1: API های توصیه شده با هوش مصنوعی Vertex را در کنسول Google Cloud فعال کنید

  1. کنسول Google Cloud را باز کنید و وقتی از شما خواسته شد، پروژه خود را انتخاب کنید.
  2. در قسمت Search در بالای کنسول، Vertex AI را وارد کرده و منتظر بمانید تا Vertex AI در نتیجه ظاهر شود.
  3. Vertex AI را انتخاب کنید. داشبورد Vertex AI ظاهر می شود.

  4. روی Enable All Recommended APIs کلیک کنید.

    ممکن است چند لحظه طول بکشد تا فعال کردن API کامل شود. صفحه را فعال و باز نگه دارید تا زمانی که فعال سازی به پایان برسد.

  5. اگر صورت‌حساب فعال نباشد، از شما خواسته می‌شود یک حساب Cloud Billing اضافه یا پیوند دهید. پس از فعال کردن حساب صورت‌حساب، به داشبورد Vertex AI برگردید و بررسی کنید که همه APIهای توصیه شده فعال هستند.

مرحله 2: پروژه خود را راه اندازی کنید و وابستگی های Node را نصب کنید

  1. یک ترمینال در رایانه خود باز کنید و به دایرکتوری که قصد ایجاد عملکرد خود را دارید بروید.

  2. وارد Firebase شوید:

    firebase login

  3. دستور زیر را برای مقداردهی اولیه Cloud Functions for Firebase اجرا کنید:

    firebase init functions

  4. استفاده از پروژه موجود را انتخاب کنید و ID پروژه خود را مشخص کنید.

  5. هنگامی که از شما خواسته شد زبان مورد استفاده را انتخاب کنید، جاوا اسکریپت را انتخاب کنید و Enter را فشار دهید.

  6. برای همه گزینه های دیگر، پیش فرض ها را انتخاب کنید.

    دایرکتوری functions در دایرکتوری فعلی ایجاد می شود. در داخل، یک فایل index.js را پیدا خواهید کرد که از آن برای ایجاد تابع خود استفاده می‌کنید، یک فهرست node_modules که حاوی وابستگی‌های تابع شما است و یک فایل package.json که حاوی وابستگی‌های بسته است.

  7. بسته‌های 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 برای اجرای عملکرد خود استفاده خواهید کرد.

  1. در کنسول Google Cloud ، صفحه IAM & Admin را باز کنید و حساب سرویس Admin SDK (با نام firebase-adminsdk ) را پیدا کنید.
  2. حساب را انتخاب کنید و روی Edit principal کلیک کنید. صفحه دسترسی ویرایش ظاهر می شود.
  3. روی افزودن نقش دیگری کلیک کنید، Remote Config Viewer را انتخاب کنید.
  4. روی افزودن نقش دیگری کلیک کنید، توسعه دهنده پلتفرم هوش مصنوعی را انتخاب کنید.
  5. روی افزودن نقش دیگری کلیک کنید، Vertex AI user را انتخاب کنید.
  6. روی افزودن نقش دیگری کلیک کنید، Cloud Run Invoker را انتخاب کنید.
  7. روی ذخیره کلیک کنید.

سپس، اعتبارنامه‌های حساب سرویس Admin SDK را صادر کرده و در متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS خود ذخیره کنید.

  1. در کنسول Google Cloud ، صفحه اعتبارنامه ها را باز کنید.
  2. روی حساب سرویس Admin SDK کلیک کنید تا صفحه جزئیات باز شود.
  3. روی کلیدها کلیک کنید.
  4. روی افزودن کلید > ایجاد کلید جدید کلیک کنید.
  5. مطمئن شوید که JSON به عنوان نوع کلید انتخاب شده است، سپس روی Create کلیک کنید.
  6. کلید یک مکان امن را در رایانه خود دانلود کنید.

  7. از ترمینال خود، کلید را به عنوان یک متغیر محیطی صادر کنید:

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

مرحله 4: تابع را ایجاد کنید

در این مرحله، تابعی می سازید که ورودی کاربر را مدیریت می کند و پاسخ های مبتنی بر هوش مصنوعی را تولید می کند. چند قطعه کد را برای ایجاد یک تابع جامع ترکیب می‌کنید که Admin SDK و Gemini API را در Vertex AI تنظیم می‌کند، پارامترهای پیش‌فرض را با استفاده از Remote Config پیکربندی می‌کند، آخرین پارامترهای Remote Config را واکشی می‌کند، ورودی کاربر را پردازش می‌کند و پاسخ را به کاربر ارسال می‌کند.

  1. در پایگاه کد خود، functions/index.js در یک ویرایشگر متن یا IDE باز کنید.

  2. محتوای موجود را حذف کنید و سپس 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();
    index.js

  3. مقادیر پیش‌فرض را پیکربندی کنید که اگر تابع شما نتواند به سرور Remote Config متصل شود، استفاده می‌کند. این راه حل textModel ، generationConfig ، safetySettings ، textPrompt و location به عنوان پارامترهای Remote Config که با پارامترهای Remote Config مطابقت دارد، پیکربندی می کند که در ادامه در این راهنما پیکربندی می کنید. برای اطلاعات بیشتر در مورد این پارامترها، مشتری Vertex AI Node.js را ببینید.

    به صورت اختیاری، همچنین می‌توانید پارامتری را برای کنترل دسترسی یا عدم دسترسی به Gemini API در Vertex AI پیکربندی کنید (در این مثال، پارامتری به نام vertex_enabled ). این تنظیمات می تواند هنگام آزمایش عملکرد شما مفید باشد. در قطعه کد زیر، این مقدار روی false تنظیم شده است، که با استفاده از Vertex AI در حین آزمایش استقرار عملکرد اصلی، از آن صرفنظر می کند. تنظیم آن روی true باعث فراخوانی Gemini API در Vertex AI می شود. 

    // 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

  4. عملکرد را ایجاد کنید و 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

  5. 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

  6. فایل را ذخیره کرده و ببندید.

مرحله 5: یک الگوی Remote Config مخصوص سرور ایجاد کنید

سپس، یک الگوی Remote Config سمت سرور ایجاد کنید و پارامترها و مقادیر را برای استفاده در عملکرد خود پیکربندی کنید. برای ایجاد یک الگوی Remote Config مخصوص سرور:

  1. کنسول Firebase را باز کرده و از منوی پیمایش، Run را باز کرده و Remote Config انتخاب کنید.

  2. Server را از انتخابگر Client/Server در بالای صفحه Remote Config انتخاب کنید.

    • اگر اولین باری است که از Remote Config یا الگوهای سرور استفاده می‌کنید، روی Create Configuration کلیک کنید. صفحه پارامتر Create your first سمت سرور ظاهر می شود.
    • اگر این اولین بار نیست که از الگوهای سرور Remote Config استفاده می‌کنید، روی افزودن پارامتر کلیک کنید.

  3. پارامترهای 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

  4. پس از اتمام افزودن پارامترها، پارامترهای خود را مجدداً بررسی کنید و اینکه انواع داده‌های آنها درست است، سپس روی انتشار تغییرات کلیک کنید.

مرحله 6: تابع خود را اجرا کنید و آن را در Firebase Local Emulator Suite آزمایش کنید

اکنون آماده استقرار و آزمایش عملکرد خود به صورت محلی با Firebase Local Emulator Suite هستید.

  1. مطمئن شوید که GOOGLE_APPLICATION_CREDENTIALS به‌عنوان یک متغیر محیطی تنظیم کرده‌اید، همانطور که در مرحله 3 توضیح داده شده است: مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید . سپس، از دایرکتوری والد دایرکتوری functions خود، تابع خود را در شبیه ساز Firebase مستقر کنید: 

    firebase emulators:start --project PROJECT_ID --only functions

  2. صفحه گزارش های شبیه ساز را باز کنید. این باید نشان دهد که تابع شما بارگذاری شده است.

  3. با اجرای دستور زیر به تابع خود دسترسی پیدا کنید، جایی که PROJECT_ID شناسه پروژه شما است و LOCATION منطقه ای است که تابع را در آن مستقر کرده اید (به عنوان مثال، us-central1 ): 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. منتظر پاسخ باشید، سپس به صفحه گزارش های Firebase Emulator یا کنسول خود بازگردید و خطاها یا هشدارها را بررسی کنید.

  5. برخی از ورودی های کاربر را ارسال کنید، توجه داشته باشید که چون is_vertex_enabled در قالب سرور Remote Config پیکربندی شده است، این باید از طریق Gemini API در Vertex AI به مدل Gemini دسترسی داشته باشد و ممکن است هزینه هایی را در پی داشته باشد: 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. در کنسول Firebase تغییراتی را در قالب سرور Remote Config ایجاد کنید، سپس دوباره به عملکرد خود برای مشاهده تغییرات دسترسی داشته باشید.

مرحله 7: تابع خود را در Google Cloud مستقر کنید

بعد از اینکه عملکرد خود را آزمایش و تأیید کردید، آماده استقرار در Google Cloud و آزمایش عملکرد زنده هستید.

عملکرد خود را مستقر کنید

تابع خود را با استفاده از Firebase CLI مستقر کنید: 

firebase deploy --only functions

دسترسی بدون احراز هویت به عملکرد را مسدود کنید

هنگامی که توابع با استفاده از Firebase مستقر می شوند، اگر خط مشی سازمان شما آن را محدود نکند، فراخوان های احراز هویت نشده به طور پیش فرض مجاز هستند. در حین آزمایش و قبل از ایمن سازی با App Check ، توصیه می کنیم دسترسی های غیرقانونی را مسدود کنید.

برای مسدود کردن دسترسی غیرقانونی به عملکرد:

  1. در کنسول Google Cloud ، Cloud Run را باز کنید.

  2. روی generateWithVertex کلیک کنید، سپس روی زبانه Security کلیک کنید.

  3. Require authentication را فعال کنید و سپس روی Save کلیک کنید.

حساب کاربری خود را برای استفاده از اعتبار حساب سرویس Admin SDK پیکربندی کنید

از آنجایی که حساب سرویس Admin SDK دارای تمام نقش ها و مجوزهای لازم برای اجرای عملکرد و تعامل با Remote Config و Gemini API در Vertex AI است، باید از آن برای اجرای عملکرد خود استفاده کنید. برای انجام این کار، باید بتوانید از حساب کاربری خود، توکن هایی برای حساب ایجاد کنید.

مراحل زیر نحوه پیکربندی حساب کاربری خود و عملکرد اجرا با امتیازات حساب سرویس Admin SDK را شرح می دهد.

  1. در کنسول Google Cloud ، IAM Service Account Credentials API را فعال کنید.
  2. به حساب کاربری خود نقش ایجاد کننده رمز حساب حساب سرویس بدهید: از کنسول Google Cloud ، IAM & Admin > IAM را باز کنید، حساب کاربری خود را انتخاب کنید و سپس روی ویرایش اصلی > افزودن نقش دیگری کلیک کنید.

  3. Service Account Token Creator را انتخاب کنید، سپس روی Save کلیک کنید.

    برای اطلاعات بیشتر درباره جعل هویت حساب سرویس، به جعل هویت حساب سرویس در اسناد Google Cloud مراجعه کنید.

  4. صفحه Google Cloud Console Cloud Functions را باز کنید و روی تابع generateWithVertex در لیست توابع کلیک کنید.

  5. Trigger > Edit را انتخاب کنید و Runtime، ساخت، اتصالات و تنظیمات امنیتی را گسترش دهید.

  6. از تب Runtime ، حساب سرویس Runtime را به حساب Admin SDK تغییر دهید.

  7. روی Next کلیک کنید، سپس روی Deploy کلیک کنید.

gcloud CLI را راه اندازی کنید

برای اجرای ایمن و آزمایش عملکرد خود از طریق خط فرمان، باید با سرویس Cloud Functions احراز هویت کنید و یک نشانه احراز هویت معتبر دریافت کنید.

برای فعال کردن تولید توکن، gcloud CLI را نصب و پیکربندی کنید:

  1. اگر قبلاً روی رایانه شما نصب نشده است، gcloud CLI را همانطور که در Install the gcloud CLI توضیح داده شده است نصب کنید.

  2. اعتبار دسترسی برای حساب Google Cloud خود را دریافت کنید: 

    gcloud auth login

  3. شناسه پروژه خود را در 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 خود ایجاد کنید، آن تغییرات را منتشر کنید و گزینه های مختلف را آزمایش کنید.

مراحل بعدی

،

این راهنما نحوه شروع استفاده از Cloud Functions نسل دوم را با Remote Config سمت سرور برای برقراری تماس‌های سمت سرور با Gemini API در Vertex AI شرح می‌دهد.

در این آموزش، Remote Config به یک تابع شبیه ربات چت اضافه می کنید که از یک مدل Gemini برای پاسخ به سؤالات کاربر استفاده می کند. Remote Config ورودی‌های Gemini API را مدیریت می‌کند (از جمله درخواستی که به درخواست‌های کاربر وارد می‌شود)، و می‌توانید این ورودی‌ها را بر حسب تقاضا از کنسول Firebase به‌روزرسانی کنید. همچنین از Firebase Local Emulator Suite برای آزمایش و اشکال‌زدایی عملکرد استفاده می‌کنید، و پس از تأیید عملکرد آن، آن را در Google Cloud اجرا و آزمایش خواهید کرد.

پیش نیازها

این راهنما فرض می کند که شما با استفاده از جاوا اسکریپت برای توسعه برنامه ها آشنا هستید.

یک پروژه Firebase راه اندازی کنید

اگر قبلاً پروژه Firebase ندارید:

  1. وارد کنسول Firebase شوید.

  2. روی ایجاد پروژه کلیک کنید و سپس از یکی از گزینه های زیر استفاده کنید:

    • گزینه 1 : با وارد کردن نام پروژه جدید در اولین مرحله از گردش کار «ایجاد پروژه»، یک پروژه Firebase جدید (و پروژه Google Cloud زیربنایی آن به صورت خودکار) ایجاد کنید.
    • گزینه 2 : «افزودن Firebase» به پروژه Google Cloud موجود با انتخاب نام پروژه Google Cloud خود از منوی کشویی در مرحله اول گردش کار «ایجاد پروژه».

  3. وقتی از شما خواسته شد، برای استفاده از این راه حل نیازی به راه اندازی Google Analytics ندارید .

  4. برای ایجاد پروژه خود، دستورالعمل های روی صفحه را دنبال کنید.

اگر قبلاً پروژه Firebase دارید:

به پیکربندی محیط توسعه خود ادامه دهید.

محیط توسعه خود را پیکربندی کنید

برای نوشتن توابع به یک محیط Node.js نیاز دارید و برای استقرار توابع در زمان اجرای Cloud Functions به Firebase CLI نیاز دارید.

  1. Node.js و npm را نصب کنید.

    برای نصب Node.js و npm ، توصیه می کنیم از Node Version Manager استفاده کنید.

  2. Firebase CLI را با استفاده از روش دلخواه خود نصب کنید . به عنوان مثال، برای نصب CLI با استفاده از npm، این دستور را اجرا کنید:

    npm install -g firebase-tools@latest

    این دستور دستور firebase جهانی را نصب می کند. اگر این دستور ناموفق باشد، ممکن است لازم باشد مجوزهای npm را تغییر دهید .

    برای به روز رسانی به آخرین نسخه firebase-tools ، همان دستور را دوباره اجرا کنید.

  3. firebase-functions و firebase-admin را نصب کنید و از --save برای ذخیره آنها در package.json خود استفاده کنید:

    npm install firebase-functions@latest firebase-admin@latest --save

اکنون برای ادامه اجرای این راه حل آماده هستید.

پیاده سازی

برای ایجاد، آزمایش و استقرار Cloud Functions نسل دوم خود با Remote Config و Vertex AI این مراحل را دنبال کنید:

  1. APIهای توصیه شده با هوش مصنوعی Vertex را در کنسول Google Cloud فعال کنید .
  2. پروژه خود را راه اندازی کنید و Dependencies Node را نصب کنید .
  3. مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید .
  4. تابع را ایجاد کنید .
  5. یک الگوی Remote Config مخصوص سرور ایجاد کنید .
  6. تابع خود را اجرا کنید و آن را در Firebase Local Emulator Suite آزمایش کنید .
  7. تابع خود را در Google Cloud مستقر کنید .

مرحله 1: API های توصیه شده با هوش مصنوعی Vertex را در کنسول Google Cloud فعال کنید

  1. کنسول Google Cloud را باز کنید و وقتی از شما خواسته شد، پروژه خود را انتخاب کنید.
  2. در قسمت Search در بالای کنسول، Vertex AI را وارد کرده و منتظر بمانید تا Vertex AI در نتیجه ظاهر شود.
  3. Vertex AI را انتخاب کنید. داشبورد Vertex AI ظاهر می شود.

  4. روی Enable All Recommended APIs کلیک کنید.

    ممکن است چند لحظه طول بکشد تا فعال کردن API کامل شود. صفحه را فعال و باز نگه دارید تا زمانی که فعال سازی به پایان برسد.

  5. اگر صورت‌حساب فعال نباشد، از شما خواسته می‌شود یک حساب Cloud Billing اضافه یا پیوند دهید. پس از فعال کردن حساب صورت‌حساب، به داشبورد Vertex AI برگردید و بررسی کنید که همه APIهای توصیه شده فعال هستند.

مرحله 2: پروژه خود را راه اندازی کنید و وابستگی های Node را نصب کنید

  1. یک ترمینال در رایانه خود باز کنید و به دایرکتوری که قصد ایجاد عملکرد خود را دارید بروید.

  2. وارد Firebase شوید:

    firebase login

  3. دستور زیر را برای مقداردهی اولیه Cloud Functions for Firebase اجرا کنید:

    firebase init functions

  4. استفاده از پروژه موجود را انتخاب کنید و ID پروژه خود را مشخص کنید.

  5. هنگامی که از شما خواسته شد زبان مورد استفاده را انتخاب کنید، جاوا اسکریپت را انتخاب کنید و Enter را فشار دهید.

  6. برای همه گزینه های دیگر، پیش فرض ها را انتخاب کنید.

    دایرکتوری functions در دایرکتوری فعلی ایجاد می شود. در داخل، یک فایل index.js را پیدا خواهید کرد که از آن برای ایجاد تابع خود استفاده می‌کنید، یک فهرست node_modules که حاوی وابستگی‌های تابع شما است و یک فایل package.json که حاوی وابستگی‌های بسته است.

  7. بسته‌های 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 برای اجرای عملکرد خود استفاده خواهید کرد.

  1. در کنسول Google Cloud ، صفحه IAM & Admin را باز کنید و حساب سرویس Admin SDK (با نام firebase-adminsdk ) را پیدا کنید.
  2. حساب را انتخاب کنید و روی Edit principal کلیک کنید. صفحه دسترسی ویرایش ظاهر می شود.
  3. روی افزودن نقش دیگری کلیک کنید، Remote Config Viewer را انتخاب کنید.
  4. روی افزودن نقش دیگری کلیک کنید، توسعه دهنده پلتفرم هوش مصنوعی را انتخاب کنید.
  5. روی افزودن نقش دیگری کلیک کنید، Vertex AI user را انتخاب کنید.
  6. روی افزودن نقش دیگری کلیک کنید، Cloud Run Invoker را انتخاب کنید.
  7. روی ذخیره کلیک کنید.

سپس، اعتبارنامه‌های حساب سرویس Admin SDK را صادر کرده و در متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS خود ذخیره کنید.

  1. در کنسول Google Cloud ، صفحه اعتبارنامه ها را باز کنید.
  2. روی حساب سرویس Admin SDK کلیک کنید تا صفحه جزئیات باز شود.
  3. روی کلیدها کلیک کنید.
  4. روی افزودن کلید > ایجاد کلید جدید کلیک کنید.
  5. مطمئن شوید که JSON به عنوان نوع کلید انتخاب شده است، سپس روی Create کلیک کنید.
  6. کلید یک مکان امن را در رایانه خود دانلود کنید.

  7. از ترمینال خود، کلید را به عنوان یک متغیر محیطی صادر کنید:

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

مرحله 4: تابع را ایجاد کنید

در این مرحله، تابعی می سازید که ورودی کاربر را مدیریت می کند و پاسخ های مبتنی بر هوش مصنوعی را تولید می کند. چند قطعه کد را برای ایجاد یک تابع جامع ترکیب می‌کنید که Admin SDK و Gemini API را در Vertex AI تنظیم می‌کند، پارامترهای پیش‌فرض را با استفاده از Remote Config پیکربندی می‌کند، آخرین پارامترهای Remote Config را واکشی می‌کند، ورودی کاربر را پردازش می‌کند و پاسخ را به کاربر ارسال می‌کند.

  1. در پایگاه کد خود، functions/index.js در یک ویرایشگر متن یا IDE باز کنید.

  2. محتوای موجود را حذف کنید و سپس 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();
    index.js

  3. مقادیر پیش‌فرض را پیکربندی کنید که اگر تابع شما نتواند به سرور Remote Config متصل شود، استفاده می‌کند. این راه حل textModel ، generationConfig ، safetySettings ، textPrompt و location به عنوان پارامترهای Remote Config که با پارامترهای Remote Config مطابقت دارد، پیکربندی می کند که در ادامه در این راهنما پیکربندی می کنید. برای اطلاعات بیشتر در مورد این پارامترها، مشتری Vertex AI Node.js را ببینید.

    به صورت اختیاری، همچنین می‌توانید پارامتری را برای کنترل دسترسی یا عدم دسترسی به Gemini API در Vertex AI پیکربندی کنید (در این مثال، پارامتری به نام vertex_enabled ). این تنظیمات می تواند هنگام آزمایش عملکرد شما مفید باشد. در قطعه کد زیر، این مقدار روی false تنظیم شده است، که با استفاده از Vertex AI در حین آزمایش استقرار عملکرد اصلی، از آن صرفنظر می کند. تنظیم آن روی true باعث فراخوانی Gemini API در Vertex AI می شود. 

    // 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

  4. عملکرد را ایجاد کنید و 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

  5. 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

  6. فایل را ذخیره کرده و ببندید.

مرحله 5: یک الگوی Remote Config مخصوص سرور ایجاد کنید

سپس، یک الگوی Remote Config سمت سرور ایجاد کنید و پارامترها و مقادیر را برای استفاده در عملکرد خود پیکربندی کنید. برای ایجاد یک الگوی Remote Config مخصوص سرور:

  1. کنسول Firebase را باز کرده و از منوی پیمایش، Run را باز کرده و Remote Config انتخاب کنید.

  2. Server را از انتخابگر Client/Server در بالای صفحه Remote Config انتخاب کنید.

    • اگر اولین باری است که از Remote Config یا الگوهای سرور استفاده می‌کنید، روی Create Configuration کلیک کنید. صفحه پارامتر Create your first سمت سرور ظاهر می شود.
    • اگر این اولین بار نیست که از الگوهای سرور Remote Config استفاده می‌کنید، روی افزودن پارامتر کلیک کنید.

  3. پارامترهای 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

  4. پس از اتمام افزودن پارامترها، پارامترهای خود را مجدداً بررسی کنید و اینکه انواع داده‌های آنها درست است، سپس روی انتشار تغییرات کلیک کنید.

مرحله 6: تابع خود را اجرا کنید و آن را در Firebase Local Emulator Suite آزمایش کنید

اکنون آماده استقرار و آزمایش عملکرد خود به صورت محلی با Firebase Local Emulator Suite هستید.

  1. مطمئن شوید که GOOGLE_APPLICATION_CREDENTIALS به‌عنوان یک متغیر محیطی تنظیم کرده‌اید، همانطور که در مرحله 3 توضیح داده شده است: مجوزهای IAM را برای حساب سرویس Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید . سپس، از دایرکتوری والد دایرکتوری functions خود، تابع خود را در شبیه ساز Firebase مستقر کنید: 

    firebase emulators:start --project PROJECT_ID --only functions

  2. صفحه گزارش های شبیه ساز را باز کنید. این باید نشان دهد که تابع شما بارگذاری شده است.

  3. با اجرای دستور زیر به تابع خود دسترسی پیدا کنید، جایی که PROJECT_ID شناسه پروژه شما است و LOCATION منطقه ای است که تابع را در آن مستقر کرده اید (به عنوان مثال، us-central1 ): 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. منتظر پاسخ باشید، سپس به صفحه گزارش های Firebase Emulator یا کنسول خود بازگردید و خطاها یا هشدارها را بررسی کنید.

  5. برخی از ورودی های کاربر را ارسال کنید، توجه داشته باشید که چون is_vertex_enabled در قالب سرور Remote Config پیکربندی شده است، این باید از طریق Gemini API در Vertex AI به مدل Gemini دسترسی داشته باشد و ممکن است هزینه هایی را در پی داشته باشد: 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. در کنسول Firebase تغییراتی را در قالب سرور Remote Config ایجاد کنید، سپس دوباره به عملکرد خود برای مشاهده تغییرات دسترسی داشته باشید.

مرحله 7: تابع خود را در Google Cloud مستقر کنید

بعد از اینکه عملکرد خود را آزمایش و تأیید کردید، آماده استقرار در Google Cloud و آزمایش عملکرد زنده هستید.

عملکرد خود را مستقر کنید

تابع خود را با استفاده از Firebase CLI مستقر کنید: 

firebase deploy --only functions

دسترسی بدون احراز هویت به عملکرد را مسدود کنید

هنگامی که توابع با استفاده از Firebase مستقر می شوند، اگر خط مشی سازمان شما آن را محدود نکند، فراخوان های احراز هویت نشده به طور پیش فرض مجاز هستند. در حین آزمایش و قبل از ایمن سازی با App Check ، توصیه می کنیم دسترسی های غیرقانونی را مسدود کنید.

برای مسدود کردن دسترسی غیرقانونی به عملکرد:

  1. در کنسول Google Cloud ، Cloud Run را باز کنید.

  2. روی generateWithVertex کلیک کنید، سپس روی زبانه Security کلیک کنید.

  3. Require authentication را فعال کنید و سپس روی Save کلیک کنید.

حساب کاربری خود را برای استفاده از اعتبار حساب سرویس Admin SDK پیکربندی کنید

از آنجایی که حساب سرویس Admin SDK دارای تمام نقش ها و مجوزهای لازم برای اجرای عملکرد و تعامل با Remote Config و Gemini API در Vertex AI است، باید از آن برای اجرای عملکرد خود استفاده کنید. برای انجام این کار، باید بتوانید از حساب کاربری خود، توکن هایی برای حساب ایجاد کنید.

مراحل زیر نحوه پیکربندی حساب کاربری خود و عملکرد اجرا با امتیازات حساب سرویس Admin SDK را شرح می دهد.

  1. در کنسول Google Cloud ، IAM Service Account Credentials API را فعال کنید.
  2. به حساب کاربری خود نقش ایجاد کننده رمز حساب حساب سرویس بدهید: از کنسول Google Cloud ، IAM & Admin > IAM را باز کنید، حساب کاربری خود را انتخاب کنید و سپس روی ویرایش اصلی > افزودن نقش دیگری کلیک کنید.

  3. Service Account Token Creator را انتخاب کنید، سپس روی Save کلیک کنید.

    برای اطلاعات بیشتر درباره جعل هویت حساب سرویس، به جعل هویت حساب سرویس در اسناد Google Cloud مراجعه کنید.

  4. صفحه Google Cloud Console Cloud Functions را باز کنید و روی تابع generateWithVertex در لیست توابع کلیک کنید.

  5. Trigger > Edit را انتخاب کنید و Runtime، ساخت، اتصالات و تنظیمات امنیتی را گسترش دهید.

  6. از تب Runtime ، حساب سرویس Runtime را به حساب Admin SDK تغییر دهید.

  7. روی Next کلیک کنید، سپس روی Deploy کلیک کنید.

gcloud CLI را راه اندازی کنید

برای اجرای ایمن و آزمایش عملکرد خود از طریق خط فرمان، باید با سرویس Cloud Functions احراز هویت کنید و یک نشانه احراز هویت معتبر دریافت کنید.

برای فعال کردن تولید توکن، gcloud CLI را نصب و پیکربندی کنید:

  1. اگر قبلاً روی رایانه شما نصب نشده است، gcloud CLI را همانطور که در Install the gcloud CLI توضیح داده شده است نصب کنید.

  2. اعتبار دسترسی برای حساب Google Cloud خود را دریافت کنید: 

    gcloud auth login

  3. شناسه پروژه خود را در 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 خود ایجاد کنید، آن تغییرات را منتشر کنید و گزینه های مختلف را آزمایش کنید.

مراحل بعدی

،

این راهنما نحوه شروع استفاده از Cloud Functions نسل دوم را با Remote Config سمت سرور برای برقراری تماس‌های سمت سرور با Gemini API در Vertex AI شرح می‌دهد.

در این آموزش، Remote Config به یک تابع شبیه ربات چت اضافه می کنید که از یک مدل Gemini برای پاسخ به سؤالات کاربر استفاده می کند. Remote Config ورودی‌های Gemini API را مدیریت می‌کند (از جمله درخواستی که به درخواست‌های کاربر وارد می‌شود)، و می‌توانید این ورودی‌ها را بر حسب تقاضا از کنسول Firebase به‌روزرسانی کنید. همچنین از Firebase Local Emulator Suite برای آزمایش و اشکال‌زدایی عملکرد استفاده می‌کنید، و پس از تأیید عملکرد آن، آن را در Google Cloud اجرا و آزمایش خواهید کرد.

پیش نیازها

این راهنما فرض می کند که شما با استفاده از جاوا اسکریپت برای توسعه برنامه ها آشنا هستید.

یک پروژه Firebase راه اندازی کنید

اگر قبلاً پروژه Firebase ندارید:

  1. وارد کنسول Firebase شوید.

  2. روی ایجاد پروژه کلیک کنید و سپس از یکی از گزینه های زیر استفاده کنید:

    • گزینه 1 : با وارد کردن نام پروژه جدید در اولین مرحله از گردش کار «ایجاد پروژه»، یک پروژه Firebase جدید (و پروژه Google Cloud زیربنایی آن به صورت خودکار) ایجاد کنید.
    • گزینه 2 : «افزودن Firebase» به پروژه Google Cloud موجود با انتخاب نام پروژه Google Cloud خود از منوی کشویی در مرحله اول گردش کار «ایجاد پروژه».

  3. وقتی از شما خواسته شد، برای استفاده از این راه حل نیازی به راه اندازی Google Analytics ندارید .

  4. برای ایجاد پروژه خود، دستورالعمل های روی صفحه را دنبال کنید.

اگر قبلاً پروژه Firebase دارید:

برای پیکربندی محیط توسعه خود ادامه دهید.

محیط توسعه خود را پیکربندی کنید

برای نوشتن توابع به یک محیط node.js نیاز دارید و برای استقرار توابع در زمان اجرا به Cloud Functions نیاز به CLI Firebase دارید.

  1. node.js و npm را نصب کنید.

    برای نصب Node.js و NPM ، توصیه می کنیم از Node Version Manager استفاده کنید.

  2. CLI Firebase را با استفاده از روش مورد نظر خود نصب کنید . به عنوان مثال ، برای نصب CLI با استفاده از NPM ، این دستور را اجرا کنید:

    npm install -g firebase-tools@latest

    این دستور فرمان firebase در سطح جهانی را در دسترس قرار می دهد. در صورت عدم موفقیت این دستور ، ممکن است نیاز به تغییر مجوزهای NPM داشته باشید.

    برای به روزرسانی در آخرین نسخه از firebase-tools ، همان دستور را دوباره انجام دهید.

  3. firebase-functions و firebase-admin را نصب کنید و از آنها استفاده کنید --save برای ذخیره آنها در package.json : ذخیره کنید:

    npm install firebase-functions@latest firebase-admin@latest --save

اکنون شما آماده اجرای این راه حل هستید.

پیاده سازی

این مراحل را برای ایجاد ، آزمایش و استقرار Cloud Functions Gen 2 خود با Remote Config و Vertex AI دنبال کنید:

  1. API های توصیه شده Vertex AI را در کنسول Google Cloud فعال کنید .
  2. پروژه خود را اولیه کنید و وابستگی های گره را نصب کنید .
  3. مجوزهای IAM را برای حساب خدمات Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید .
  4. عملکرد را ایجاد کنید .
  5. یک الگوی Remote Config خاص سرور ایجاد کنید .
  6. عملکرد خود را مستقر کرده و آن را در Firebase Local Emulator Suite آزمایش کنید .
  7. عملکرد خود را در Google Cloud مستقر کنید .

مرحله 1: API های توصیه شده Vertex AI را در کنسول Google Cloud فعال کنید

  1. کنسول Google Cloud را باز کنید و در صورت درخواست ، پروژه خود را انتخاب کنید.
  2. در قسمت جستجو در بالای کنسول ، Vertex AI را وارد کنید و منتظر بمانید تا Vertex AI در نتیجه ظاهر شود.
  3. Vertex AI را انتخاب کنید. داشبورد Vertex AI ظاهر می شود.

  4. روی فعال کردن همه API های پیشنهادی کلیک کنید.

    ممکن است چند لحظه طول بکشد تا API Enablement تکمیل شود. صفحه را فعال و باز نگه دارید تا زمانی که Enablement تمام شود.

  5. اگر صورتحساب فعال نشده باشد ، از شما خواسته می شود یک حساب Cloud Billing اضافه یا پیوند دهید. پس از فعال کردن حساب صورتحساب ، به داشبورد AI Vertex برگردید و تأیید کنید که تمام API های توصیه شده فعال هستند.

مرحله 2: پروژه خود را آغاز کنید و وابستگی های گره را نصب کنید

  1. یک ترمینال را روی رایانه خود باز کنید و به دایرکتوری که قصد دارید عملکرد خود را ایجاد کنید ، حرکت کنید.

  2. وارد Firebase شوید:

    firebase login

  3. دستور زیر را اجرا کنید تا Cloud Functions for Firebase آغاز کنید:

    firebase init functions

  4. استفاده از یک پروژه موجود را انتخاب کنید و شناسه پروژه خود را مشخص کنید.

  5. هنگامی که از شما خواسته می شود زبان را برای استفاده انتخاب کنید ، JavaScript را انتخاب کرده و Enter را فشار دهید.

  6. برای همه گزینه های دیگر ، پیش فرض ها را انتخاب کنید.

    یک فهرست functions در فهرست فعلی ایجاد می شود. در داخل ، یک پرونده index.js را پیدا خواهید کرد که برای ساختن عملکرد خود استفاده می کنید ، یک دایرکتوری node_modules که شامل وابستگی های عملکرد شما است ، و یک پرونده package.json که شامل وابستگی های بسته است.

  7. بسته های 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 Engine با نسخه نصب شده Node.js و نسخه ای که در نهایت در Google Cloud اجرا می کنید مطابقت دارد. به عنوان مثال ، اگر engines موجود در package.json شما است. json به عنوان گره نسخه 18 پیکربندی شده است و از node.js 20 استفاده می کنید ، پرونده را برای استفاده از 20 به روز کنید:

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

مرحله 3: مجوزهای IAM را برای حساب خدمات Admin SDK خود پیکربندی کنید و کلید خود را ذخیره کنید

در این راه حل ، برای اجرای عملکرد خود از حساب سرویس SDK Admin SDK Firebase استفاده خواهید کرد.

  1. در کنسول Google Cloud ، صفحه IAM & Admin را باز کنید و حساب Admin SDK Service (با نام firebase-adminsdk ) را پیدا کنید.
  2. حساب را انتخاب کرده و روی ویرایش اصلی کلیک کنید. صفحه ویرایش دسترسی ظاهر می شود.
  3. روی افزودن نقش دیگری کلیک کنید ، Remote Config Viewer را انتخاب کنید.
  4. روی افزودن نقش دیگری کلیک کنید ، AI Platform Developer را انتخاب کنید.
  5. روی افزودن نقش دیگری کلیک کنید ، کاربر Vertex AI را انتخاب کنید.
  6. روی افزودن نقش دیگری کلیک کنید ، Cloud Run Invoker را انتخاب کنید.
  7. روی ذخیره کلیک کنید.

در مرحله بعد ، اعتبارنامه را برای حساب سرویس Admin SDK صادر کنید و آنها را در متغیر محیط GOOGLE_APPLICATION_CREDENTIALS خود ذخیره کنید.

  1. در کنسول Google Cloud ، صفحه اعتبار را باز کنید.
  2. برای باز کردن صفحه جزئیات ، روی حساب Admin SDK Service کلیک کنید.
  3. روی کلیدها کلیک کنید.
  4. روی افزودن کلید > ایجاد کلید جدید کلیک کنید.
  5. اطمینان حاصل کنید که JSON به عنوان نوع کلید انتخاب شده است ، سپس روی ایجاد کلیک کنید.
  6. کلید یک مکان امن در رایانه خود را بارگیری کنید.

  7. از ترمینال خود ، کلید را به عنوان یک متغیر محیط صادر کنید:

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

مرحله 4: عملکرد را ایجاد کنید

در این مرحله ، تابعی را ایجاد می کنید که ورودی کاربر را کنترل می کند و پاسخ های دارای هوش مصنوعی را ایجاد می کند. شما می توانید چندین قطعه کد را برای ساختن یک تابع جامع که اولیه Admin SDK و Gemini API را در Vertex AI آغاز می کند ، ترکیب کنید ، پارامترهای پیش فرض را با استفاده از Remote Config پیکربندی می کند ، آخرین پارامترهای Remote Config را می گیرد ، ورودی کاربر را پردازش می کند و پاسخ را به کاربر باز می گرداند.

  1. در پایگاه کد خود ، functions/index.js در یک ویرایشگر متن یا IDE باز کنید.

  2. محتوای موجود را حذف کرده و سپس 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();
    index.js

  3. مقادیر پیش فرض را که عملکرد شما از آن استفاده می کند اگر نتواند به سرور Remote Config وصل شود ، پیکربندی کنید. این راه حل پیکربندی textModel ، generationConfig ، safetySettings ، textPrompt و location به عنوان پارامترهای Remote Config که با پارامترهای Remote Config مطابقت دارد که در این راهنما پیکربندی می کنید ، پیکربندی می کند. برای اطلاعات بیشتر در مورد این پارامترها ، به مشتری vertex ai node.js مراجعه کنید.

    به صورت اختیاری ، همچنین می توانید یک پارامتر را برای کنترل اینکه آیا به API Gemini در Vertex AI دسترسی پیدا می کنید ، پیکربندی کنید (در این مثال ، پارامتر به نام vertex_enabled ). این تنظیم می تواند هنگام آزمایش عملکرد شما مفید باشد. در قطعه های کد زیر ، این مقدار روی false تنظیم شده است ، که در حالی که شما تست عملکرد اصلی را آزمایش می کنید ، با استفاده از Vertex AI پرش می شود. تنظیم آن در true ، API Gemini را در Vertex AI فراخوانی خواهد کرد. 

    // 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

  4. تابع را ایجاد کنید و 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

  5. 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

  6. فایل را ذخیره کرده و ببندید.

مرحله 5: یک الگوی Remote Config خاص سرور ایجاد کنید

در مرحله بعد ، یک الگوی Remote Config ایجاد کنید و پارامترها و مقادیر را برای استفاده در عملکرد خود پیکربندی کنید. برای ایجاد یک الگوی Remote Config خاص سرور:

  1. کنسول Firebase را باز کنید و از منوی ناوبری ، Run را گسترش داده و Remote Config انتخاب کنید.

  2. سرور را از انتخاب کننده مشتری/سرور در بالای صفحه Remote Config انتخاب کنید.

    • اگر این اولین بار است که با استفاده از Remote Config یا Templates Server ، روی ایجاد پیکربندی کلیک کنید. اولین صفحه Create Your Server Parameter ظاهر می شود.
    • اگر این اولین بار نیست که با استفاده از الگوهای سرور Remote Config ، روی Add Parameter کلیک کنید.

  3. پارامترهای 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 تنظیمات ایمنی برای راس 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

  4. هنگامی که اضافه کردن پارامترها را به پایان رسانده اید ، پارامترهای خود را دوبار بررسی کنید و انواع داده های آنها صحیح است ، سپس روی Publish Changes کلیک کنید.

مرحله ششم: عملکرد خود را مستقر کرده و آن را در Firebase Local Emulator Suite آزمایش کنید

اکنون شما آماده استقرار و آزمایش عملکرد خود به صورت محلی با Firebase Local Emulator Suite هستید.

  1. اطمینان حاصل کنید که GOOGLE_APPLICATION_CREDENTIALS به عنوان یک متغیر محیط تنظیم کرده اید همانطور که در مرحله 3 توضیح داده شده است: پیکربندی مجوزهای IAM را برای حساب خدمات Admin SDK خود پیکربندی کرده و کلید خود را ذخیره کنید . سپس ، از فهرست والدین دایرکتوری functions خود ، عملکرد خود را در شبیه ساز Firebase مستقر کنید: 

    firebase emulators:start --project PROJECT_ID --only functions

  2. صفحه سیاهههای مربوط به شبیه ساز را باز کنید. این باید نشان دهد که عملکرد شما بارگذاری شده است.

  3. با اجرای دستور زیر به عملکرد خود دسترسی پیدا کنید ، جایی که PROJECT_ID شناسه پروژه و LOCATION شما منطقه ای است که شما این تابع را به آن مستقر کرده اید (به عنوان مثال ، us-central1 ): 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex

  4. منتظر پاسخ باشید ، سپس به صفحه ورود به سیستم Firebase Emulator یا کنسول خود برگردید و هرگونه خطا یا هشدار را بررسی کنید.

  5. سعی کنید برخی از ورودی های کاربر را ارسال کنید ، زیرا به این دلیل که is_vertex_enabled در الگوی سرور Remote Config شما پیکربندی شده است ، این باید از طریق API Gemini در Vertex AI به مدل Gemini دسترسی پیدا کند و این ممکن است هزینه ها را متحمل شود: 

    curl http://localhost:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats

  6. در الگوی سرور Remote Config خود در کنسول Firebase تغییراتی ایجاد کنید ، سپس عملکرد خود را دوباره به آن دسترسی دهید تا تغییرات را مشاهده کنید.

مرحله 7: عملکرد خود را در Google Cloud مستقر کنید

بعد از آزمایش و تأیید عملکرد خود ، شما آماده استقرار در Google Cloud و آزمایش عملکرد زنده هستید.

عملکرد خود را مستقر کنید

عملکرد خود را با استفاده از Firebase CLI مستقر کنید: 

firebase deploy --only functions

دسترسی غیرمجاز به عملکرد را مسدود کنید

هنگامی که توابع با استفاده از Firebase مستقر می شوند ، اگر سیاست سازمان شما آن را محدود نکند ، دعوت های غیرمجاز به طور پیش فرض مجاز است. در حین آزمایش و قبل از اطمینان از App Check ، توصیه می کنیم دسترسی غیرمجاز را مسدود کنید.

برای جلوگیری از دسترسی غیرمجاز به عملکرد:

  1. در کنسول Google Cloud ، Cloud Run را باز کنید.

  2. روی generateWithVertex کلیک کنید ، سپس روی برگه امنیت کلیک کنید.

  3. Enable نیاز به احراز هویت و سپس روی ذخیره کلیک کنید.

حساب کاربری خود را برای استفاده از اعتبار حساب کاربری Admin SDK پیکربندی کنید

از آنجا که حساب سرویس Admin SDK دارای تمام نقش ها و مجوزهای لازم برای اجرای عملکرد و تعامل با Remote Config و Gemini API در Vertex AI است ، می خواهید از آن برای اجرای عملکرد خود استفاده کنید. برای انجام این کار ، شما باید بتوانید نشانه هایی را برای حساب کاربری خود ایجاد کنید.

مراحل زیر نحوه پیکربندی حساب کاربری خود و عملکردی را که با امتیازات حساب کاربری Admin SDK Service اجرا می شود ، شرح می دهد.

  1. در کنسول Google Cloud ، API اعتبار حساب IAM را فعال کنید.
  2. به حساب کاربری خود در نقش سازنده Token Account Service Service : از Console Google Cloud ، IAM & Admin > IAM را باز کنید ، حساب کاربری خود را انتخاب کنید و سپس روی ویرایش اصلی > اضافه کردن نقش دیگر کلیک کنید.

  3. Service Account Token Creator را انتخاب کنید ، سپس روی ذخیره کلیک کنید.

    برای کسب اطلاعات بیشتر در مورد جعل هویت حساب خدمات ، به جعل هویت حساب خدمات در مستندات Google Cloud مراجعه کنید.

  4. صفحه Cloud Functions Google Cloud Console Console Cloud را باز کنید و روی عملکرد GETERATEWWORTEXT در لیست توابع کلیک کنید.

  5. Trigger > ویرایش و گسترش زمان اجرا ، ساخت ، اتصالات و تنظیمات امنیتی را انتخاب کنید.

  6. از برگه Runtime ، حساب سرویس Runtime را به حساب Admin SDK تغییر دهید.

  7. روی Next کلیک کنید ، سپس روی Deploy کلیک کنید.

gcloud cli را تنظیم کنید

برای اجرای ایمن و آزمایش عملکرد خود از خط فرمان ، باید با سرویس Cloud Functions تأیید کنید و یک نشانه تأیید اعتبار معتبر را بدست آورید.

برای فعال کردن تولید Token ، Gcloud CLI را نصب و پیکربندی کنید:

  1. اگر قبلاً روی رایانه خود نصب نشده اید ، GCLOUD CLI را همانطور که در نصب GCLOUD CLI توضیح داده شده است ، نصب کنید.

  2. اعتبارنامه دسترسی را برای حساب Google Cloud خود بدست آورید: 

    gcloud auth login

  3. شناسه پروژه خود را در 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 خود تغییراتی ایجاد کنید ، آن تغییرات را منتشر کرده و گزینه های مختلفی را آزمایش کنید.

مراحل بعدی