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

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

در این آموزش، 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 AI را در کنسول Google Cloud فعال کنید .
  2. پروژه خود را راه اندازی کنید و Dependencies Node را نصب کنید .
  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. در قسمت 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 و Vertex AI Gemini API را راه‌اندازی می‌کند، پارامترهای پیش‌فرض را با استفاده از 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 مراجعه کنید.

    به صورت اختیاری، همچنین می توانید پارامتری را برای کنترل دسترسی یا عدم دسترسی به 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-preview-0514",
  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-1.5-pro-preview-0514
    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 پیکربندی شده است، باید از طریق Vertex AI Gemini API به 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 و Vertex AI Gemini API ، باید از آن برای اجرای عملکرد خود استفاده کنید. برای انجام این کار، باید بتوانید از حساب کاربری خود، توکن هایی برای حساب ایجاد کنید.

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

مراحل بعدی