با استفاده از 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 را به عنوان بخشی از یک رویداد انجام می‌دهید، ممکن است اعتبار Google Cloud در دسترس باشد.
  • اگر در استفاده از فایربیس و گوگل کلود تازه‌کار هستید، بررسی کنید که آیا واجد شرایط دریافت اعتبار ۳۰۰ دلاری و یک حساب کاربری رایگان ابری هستید یا خیر.

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

  1. در کنسول Firebase، گزینه ارتقاء پلن خود را انتخاب کنید.
  2. طرح Blaze را انتخاب کنید. دستورالعمل‌های روی صفحه را دنبال کنید تا یک حساب Cloud Billing به پروژه شما متصل شود.
    • اگر از اعتبارهای Google Cloud برای این codelab استفاده می‌کنید، حساب صورتحساب احتمالاً Google Cloud Platform Trial Billing Account یا My Billing Account نامیده می‌شود.
    • اگر به عنوان بخشی از این ارتقا نیاز به ایجاد یک حساب 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 پلتفرم Agent Gemini ، روی گزینه‌ی «شروع با این API» کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید. این روند، APIهای مورد نیاز را برای شما فعال می‌کند تا از Firebase AI Logic با API پلتفرم Agent 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, AgentPlatformBackend } 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 AgentPlatformBackend() });

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

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

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

  1. در کنسول فایربیس، به تب AI Services > AI Logic > Prompt templates بروید.
  2. روی ایجاد الگو کلیک کنید و الگوی خالی را انتخاب کنید.
  3. نام قالب را روی Product Agent و شناسه (ID) را روی product-agent تنظیم کنید.
  4. مدل را روی gemini-3.1-flash-lite (یا آخرین نسخه موجود) تنظیم کنید.
  5. از کد آغازین ارائه شده برای این codelab، محتویات product-agent.prompt را کپی کنید (این فایل را در دایرکتوری ریشه پیدا کنید). سپس، این محتوا را در فیلد Prompt و (اختیاری) system instructions از الگوی server prompt در کنسول Firebase قرار دهید. این محتوا به طور ایمن به مدل دستور می‌دهد که چگونه به عنوان "Rugged Operator" رفتار کند و به کاتالوگ محصول ارجاع دهد.
  6. در فیلد ورودی Test، طرح ورودی را دقیقاً به صورت زیر تعریف کنید: 
    {
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "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"
          }
        }
      }
    }
  }
}
  7. برای ذخیره و انتشار الگوی 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 استفاده کنید تا مطمئن شوید که فقط برنامه وب واقعی شما می‌تواند درخواست‌های موفقی را به API Gemini ارسال کند و ربات‌ها و کلاینت‌های غیرمجاز را مسدود کند.

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

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

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

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

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

بعدش چی؟