با استفاده از Firebase AI Logic یک عامل پشتیبانی مشتری مبتنی بر هوش مصنوعی بسازید

۱. مقدمه

در این آزمایشگاه کد، یک ویجت چت پشتیبانی مشتری هوشمند به یک فروشگاه تجارت الکترونیک تجهیزات فضای باز به نام Rugged Terrain Guide اضافه خواهید کرد. از Firebase AI Logic برای ساخت این عامل استفاده خواهید کرد و یاد خواهید گرفت که چگونه یک الگوی اعلان سمت سرور ( product-agent ) را پیکربندی کنید که شخصیت هوش مصنوعی، قوانین سختگیرانه بودجه را مدیریت کند و به صورت پویا از کاتالوگ محصول به عنوان زمینه استفاده کند.

کاری که انجام خواهید داد:

  • کد آغازین برنامه وب این codelab را دریافت کنید.
  • یک پروژه Firebase راه‌اندازی کنید.
  • سرویس‌های Firebase (مانند Firebase AI Logic) را در یک برنامه وب راه‌اندازی و مقداردهی اولیه کنید.
  • یک الگوی اعلان سمت سرور را در کنسول Firebase پیکربندی کنید.
  • از طریق فراخوانی سرویس هوش مصنوعی مولد از طریق یک رابط TypeScript شبیه React، به قالب دسترسی پیدا کنید.

آنچه نیاز دارید:

  • یک مرورگر وب مانند کروم .
  • آشنایی اولیه با TypeScript و Node.js.
  • یک IDE یا ویرایشگر متن به دلخواه شما. Antigravity انتخاب خوبی است.

۲. کد شروع را دریافت کنید

  1. در ترمینال خود، مخزن اولیه را کلون کنید: 
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. به دایرکتوری کد بروید و وابستگی‌ها را نصب کنید: 
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

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

ایجاد یک پروژه فایربیس

  1. با استفاده از حساب گوگل خود وارد کنسول فایربیس شوید.
  2. برای ایجاد یک پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال، rugged-terrain-ai ).
  3. روی ادامه کلیک کنید.
  4. در صورت درخواست، شرایط Firebase را مرور و قبول کنید و سپس روی ادامه کلیک کنید.
  5. (اختیاری) دستیار هوش مصنوعی را در کنسول Firebase (با نام "Gemini در Firebase") فعال کنید.
  6. برای این codelab، به گوگل آنالیتیکس نیاز ندارید ، بنابراین گزینه گوگل آنالیتیکس را غیرفعال کنید .
  7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه شما آماده شود و سپس روی ادامه کلیک کنید.

طرح قیمت‌گذاری فایربیس خود را ارتقا دهید

برای استفاده از سرویس‌های فایربیس در این آزمایشگاه کد، پروژه فایربیس شما باید در طرح قیمت‌گذاری پرداخت در محل (Blaze) باشد، به این معنی که به یک حساب پرداخت ابری (Cloud Billing ) متصل باشد.

  • یک حساب Cloud Billing به یک روش پرداخت، مانند کارت اعتباری، نیاز دارد.
  • اگر در استفاده از فایربیس و گوگل کلود تازه‌کار هستید، بررسی کنید که آیا واجد شرایط دریافت اعتبار ۳۰۰ دلاری و یک حساب کاربری رایگان ابری هستید یا خیر.
  • اگر این codelab را به عنوان بخشی از یک رویداد انجام می‌دهید، از برگزارکننده خود بپرسید که آیا امکان استفاده از فضای ابری (Cloud credits) وجود دارد یا خیر.

برای ارتقاء پروژه خود به طرح Blaze، مراحل زیر را دنبال کنید:

  1. در کنسول Firebase، گزینه ارتقاء پلن خود را انتخاب کنید.
  2. طرح Blaze را انتخاب کنید. دستورالعمل‌های روی صفحه را دنبال کنید تا یک حساب Cloud Billing به پروژه شما متصل شود.
    اگر به عنوان بخشی از این ارتقا نیاز به ایجاد یک حساب Cloud Billing داشتید، ممکن است لازم باشد برای تکمیل ارتقا، به روند ارتقا در کنسول Firebase برگردید.

۴. سرویس‌های فایربیس را راه‌اندازی کنید و برنامه خود را متصل کنید

برای این آزمایشگاه کد، باید فضای ذخیره‌سازی ابری برای فایربیس و منطق هوش مصنوعی فایربیس را در پروژه فایربیس خود راه‌اندازی کنید. همچنین باید کد منبع برنامه خود را به پروژه فایربیس خود متصل کنید.

راه‌اندازی فضای ذخیره‌سازی ابری برای فایربیس

این آزمایشگاه کد از فضای ذخیره‌سازی ابری برای فایربیس برای ذخیره توضیحات محصول استفاده می‌کند.

  1. در کنسول فایربیس، به مسیر Databases & Storage > Storage بروید.
  2. روی شروع به کار کلیک کنید.
  3. مکانی را برای سطل ذخیره‌سازی پیش‌فرض خود انتخاب کنید.
    کاربران در US-WEST1 ، US-CENTRAL1 و US-EAST1 می‌توانند از ردیف «همیشه رایگان» برای Google Cloud Storage بهره‌مند شوند. کاربران در سایر مناطق ، از قیمت‌ها و میزان استفاده از Google Cloud Storage پیروی می‌کنند.
  4. روی حالت تولید (Production mode) کلیک کنید. در مراحل زیر، این قوانین امنیتی را به‌روزرسانی خواهید کرد تا مختص این آزمایشگاه کد باشند.
  5. روی ایجاد کلیک کنید.
  6. قوانین امنیتی خود را به‌روزرسانی کنید:
    1. پس از آماده‌سازی سطل، به برگه قوانین بروید.
    2. قوانین زیر را کپی و سپس در آن جایگذاری کنید: 
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. روی انتشار کلیک کنید.
  7. توضیحات محصول را از کد آغازین آپلود کنید:
    1. روی تب Files مربوط به Storage Bucket خود کلیک کنید.
    2. روی آپلود فایل کلیک کنید و سپس فایل products.txt را از کد آغازین آپلود کنید. این فایل را می‌توانید در آدرس src/data/products.txt پیدا کنید.

پیکربندی منطق هوش مصنوعی فایربیس

منطق هوش مصنوعی فایربیس (Firebase AI Logic) سرویس اصلی فایربیس است که در این آزمایشگاه کد از آن استفاده خواهید کرد.

  1. در کنسول فایربیس، به بخش سرویس‌های هوش مصنوعی > منطق هوش مصنوعی بروید.
  2. روی شروع به کار کلیک کنید.
  3. در کارت API مربوط به Vertex AI Gemini ، روی گزینه‌ی «شروع با این API» کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید. این روند، APIهای مورد نیاز برای استفاده از Firebase AI Logic با API مربوط به Vertex AI Gemini را برای شما فعال می‌کند.
  4. (اختیاری) گزینه فعال کردن نظارت بر هوش مصنوعی را انتخاب کنید تا بتوانید معیارها و میزان استفاده در سطح برنامه را مشاهده کنید تا از طریق Firebase AI Logic، دید جامعی نسبت به درخواست‌های خود داشته باشید.

کد خود را به پروژه Firebase خود وصل کنید

به عنوان بخشی از راه‌اندازی Firebase AI Logic، از شما خواسته می‌شود که یک برنامه وب Firebase ایجاد کنید و پیکربندی خود را به کد منبع خود اضافه کنید.

  1. وقتی در جریان تنظیم Firebase AI Logic از شما خواسته شد، روی وب ( ) آیکون برای ثبت یک برنامه وب جدید.
  2. نام برنامه را بنویسید (مثلاً Rugged Web ).
  3. شیء firebaseConfig را از دستورالعمل‌های راه‌اندازی کپی کنید.

در مرحله بعد، کد شروع را به‌روزرسانی کنید:

  1. در ویرایشگر کد خود، src/firebase.ts را باز کنید.
  2. firebaseConfig موجود را با موردی که از کنسول Firebase کپی کرده‌اید، جایگزین کنید.

فایل شما باید به این شکل باشد:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new VertexAIBackend() });

۵. الگوی اعلان سمت سرور را ایجاد کنید

به جای کدنویسی دستورات پیچیده هوش مصنوعی در برنامه کلاینت، از سینتکس Dotprompt برای مدیریت ایمن دستورالعمل‌ها روی سرور استفاده خواهید کرد.

این امر مانع از آن می‌شود که کاربران نهایی قوانین مخفی «بودجه مماشات» را ببینند.

  1. در کنسول Firebase، به بخش Vertex AI یا Prompt Management بروید.
  2. یک الگوی اعلان جدید ایجاد کنید و نام آن را product-agent بگذارید.
  3. مدل را روی gemini-2.5-flash تنظیم کنید.
  4. طرح ورودی را دقیقاً به صورت زیر تعریف کنید: 
    input:
  schema:
    query:
      type: string
      description: the customers ask of the robot
    productId?:
      type: string
      description: the product the customer is looking at right now
    history?:
      type: array
      description: list of previous history between the user and system
      items:
        type: object
        required: [role, contents]
        properties:
          role:
            type: string
          contents:
            type: string
  5. محتویات agent-product.prompt را از دایرکتوری ریشه به فیلد Prompt و اختیاری system instructions کپی کنید. این کار به طور ایمن به مدل دستور می‌دهد که چگونه به عنوان "Rugged Operator" رفتار کند و کاتالوگ محصول را تزریق کند.
  6. در کنسول Firebase، الگوی product-agent را ذخیره و منتشر کنید.

۶. مدل هوش مصنوعی را فراخوانی کنید

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

  1. در ویرایشگر کد خود، به src/firebase.ts برگردید.
  2. در زیر مقداردهی اولیه، از getTemplateGenerativeModel برای اتصال به قالب استفاده کنید: 
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

۷. با استفاده از Firebase App Check، عامل را ایمن کنید

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

  1. در کنسول Firebase، به Build > App Check بروید.
  2. روی برگه برنامه‌ها کلیک کنید، برنامه وب خود ( Rugged Web ) را باز کنید و روی ارائه‌دهنده reCAPTCHA Enterprise کلیک کنید.
  3. گزینه «ایجاد کلید جدید reCAPTCHA Enterprise» را انتخاب کنید و فرم را پر کنید:
    • نام : Codelab Key
    • دامنه‌ها : localhost و 127.0.0.1 را اضافه کنید تا سرور محلی Vite شما مجاز به ارسال درخواست باشد.
  4. برای ثبت برنامه، روی ذخیره کلیک کنید.
  5. پس از ثبت نام، کنسول Firebase کلید سایت شما را نمایش می‌دهد. این رشته را کپی کنید.
  6. در ویرایشگر کد خود، دوباره src/firebase.ts را باز کنید.
  7. ایمپورت‌های زیر را در بالا اضافه کنید: 
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. مقداردهی اولیه App Check را درست پس از فراخوانی initializeApp(firebaseConfig) اضافه کنید و کلید سایتی که کپی کرده‌اید را جایگذاری کنید: 
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. برای استفاده از این توکن‌ها، فراخوانی تابع getAI() خود را به‌روزرسانی کنید. تغییر زیر را اعمال کنید:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    با تنظیم مقدار useLimitedUseAppCheckTokens به true، شما مطمئن می‌شوید که توکن‌های کوتاه‌مدت برای کمک به محدود کردن سوءاستفاده‌ای که ممکن است backend شما دریافت کند، اعمال می‌شوند.

۸. برنامه را اجرا کنید

با پیکربندی Firebase و اتصال ویجت چت پشتیبانی، زمان اجرای برنامه فرا رسیده است.

  1. در ترمینال خود، سرور توسعه Vite را اجرا کنید: 
    npm run dev
  2. آدرس اینترنتی محلی ارائه شده (معمولاً http://localhost:5173/ ) را باز کنید.
  3. روی دکمه‌ی شناور پشتیبانی تاکتیکی (FAB) در گوشه‌ی پایین سمت راست کلیک کنید.
  4. سعی کنید در مورد محصولات سوال بپرسید، برای مثال:
    • «من دنبال یک پوسته مقاوم در برابر آب و هوا هستم»
    • کلاه بافتنی زیر صفر من خراب است، چه کاری از دستم برمی‌آید؟
    • به عقب راندن ادامه بده تا منطق «بودجه‌ی مماشات» هوش مصنوعی رو فعال کنی!

۹. (اختیاری) پاک‌سازی منابع از codelab

برای جلوگیری از هزینه‌های احتمالی برای حساب Google Cloud Billing خود، می‌توانید منابع ایجاد شده در طول این codelab را حذف کنید.

  1. به کنسول فایربیس بروید.
  2. پروژه rugged-terrain-ai را انتخاب کنید.
  3. به تنظیمات پروژه (آیکون چرخ دنده) بروید.
  4. به پایین بروید و روی «حذف پروژه» کلیک کنید.
  5. برای تأیید حذف، دستورالعمل‌های روی صفحه را دنبال کنید.

۱۰. تبریک می‌گویم!

🎊 ماموریت تکمیل شد! شما با موفقیت یک عامل پشتیبانی مشتری هوش مصنوعی قوی و مبتنی بر الگو را ادغام کرده‌اید.

کاری که شما انجام دادید:

  • مقداردهی اولیه Firebase و Vertex AI backend در یک برنامه کلاینت.
  • یک الگوی اعلان امن سمت سرور با استفاده از Handlebars و طرح‌های ورودی دقیق پیکربندی شد تا رفتار پیچیده عامل را تعریف کند.
  • به صورت پویا یک LLM فراخوانی می‌شود که تاریخچه چت و شناسه‌های متنی محصول را بدون افشای منطق داخلی اعلان به کلاینت، به صورت ایمن منتقل می‌کند.

بعدش چی؟