יצירת סוכן תמיכת לקוחות מבוסס-AI באמצעות Firebase AI Logic

1. מבוא

בשיעור Codelab הזה נסביר איך להוסיף ווידג'ט צ'אט חכם לתמיכת לקוחות בחנות למסחר אלקטרוני של ציוד לטיולים בטבע שנקראת Rugged Terrain Guide. תשתמשו ב-Firebase AI Logic כדי ליצור את הנציג הזה, ותלמדו איך להגדיר תבנית לפרומפט בצד השרת (product-agent) שמטפלת באישיות של ה-AI, בכללי תקציב לפיצוי משתמשים ומשתמשת באופן דינמי בקטלוג המוצרים כהקשר.

מה עושים:

  • מקבלים את קוד לתחילת הדרך של אפליקציית האינטרנט של ה-Codelab הזה.
  • מגדירים פרויקט Firebase.
  • הגדרה ואתחול של שירותי Firebase (כמו Firebase AI Logic) באפליקציית אינטרנט.
  • מגדירים תבנית לפרומפט בצד השרת במסוף Firebase.
  • גישה לתבנית מתוך קריאה לשירות ה-AI הגנרטיבי מקצה קדמי של TypeScript שדומה ל-React.

מה דרוש לכם?

  • דפדפן אינטרנט כמו Chrome.
  • היכרות בסיסית עם TypeScript ו-Node.js.
  • סביבת פיתוח משולבת (IDE) או עורך טקסט לפי בחירתכם. Antigravity היא בחירה טובה.

2. קבלת קוד לתחילת הדרך

  1. במסוף, משכפלים את מאגר המתחילים:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
    
  2. עוברים לספריית הקוד ומתקינים את יחסי התלות:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
    npm install
    

3. הגדרת פרויקט Firebase

יצירת פרויקט Firebase

  1. נכנסים למסוף Firebase באמצעות חשבון Google.
  2. לוחצים על הלחצן כדי ליצור פרויקט חדש, ואז מזינים שם לפרויקט (לדוגמה, rugged-terrain-ai).
  3. לוחצים על המשך.
  4. אם מוצגת בקשה, קוראים ומאשרים את התנאים של Firebase, ואז לוחצים על המשך.
  5. (אופציונלי) מפעילים את העזרה מבוססת-AI במסוף Firebase (שנקראת 'Gemini ב-Firebase').
  6. ב-codelab הזה לא צריך להשתמש ב-Google Analytics, לכן משביתים את האפשרות Google Analytics.
  7. לוחצים על יצירת פרויקט, מחכים שהפרויקט יוקצה ולוחצים על המשך.

שדרוג תוכנית התמחור של Firebase

כדי להשתמש בשירותי Firebase ב-codelab הזה, הפרויקט ב-Firebase צריך להיות בתוכנית התמחור pay-as-you-go (Blaze), כלומר הוא צריך להיות מקושר לחשבון לחיוב ב-Cloud.

  • בחשבון לחיוב ב-Cloud צריך להגדיר אמצעי תשלום, כמו כרטיס אשראי.
  • במהלך מבצעים מיוחדים או אם אתם משתתפים ב-Codelab הזו כחלק מאירוע, יכול להיות שיהיו לכם קרדיטים ל-Google Cloud.
  • אם אתם משתמשים חדשים ב-Firebase וב-Google Cloud, כדאי לבדוק אם אתם עומדים בדרישות לקבלת קרדיט בשווי 300$וחשבון לחיוב ב-Cloud עם תקופת ניסיון בחינם.

כדי לשדרג את הפרויקט לתוכנית Blaze, פועלים לפי השלבים הבאים:

  1. במסוף Firebase, בוחרים באפשרות שדרוג התוכנית.
  2. בוחרים בתוכנית Blaze. פועלים לפי ההוראות במסך כדי לקשר חשבון לחיוב ב-Cloud לפרויקט.
    • אם אתם משתמשים בקרדיטים של Google Cloud בשביל ה-codelab הזה, סביר להניח שהחשבון לחיוב נקרא Google Cloud Platform Trial Billing Account או My Billing Account.
    • אם הייתם צריכים ליצור חשבון לחיוב ב-Cloud כחלק מהשדרוג, יכול להיות שתצטרכו לחזור לתהליך השדרוג במסוף Firebase כדי להשלים את השדרוג.

4. הגדרת שירותי Firebase וקישור האפליקציה

בשיעור Codelab הזה, תצטרכו להגדיר את Cloud Storage for Firebase ואת Firebase AI Logic בפרויקט שלכם ב-Firebase. בנוסף, צריך לקשר את קוד המקור של האפליקציה לפרויקט Firebase.

הגדרת Cloud Storage for Firebase

בשיעור Codelab הזה נשתמש ב-Cloud Storage for Firebase כדי לאחסן תיאורי מוצרים.

  1. במסוף Firebase, עוברים אל Databases & Storage (מסדי נתונים ואחסון) > Storage (אחסון).
  2. לוחצים על שנתחיל?.
  3. בוחרים מיקום לקטגוריית האחסון שמוגדרת כברירת מחדל.
    קטגוריות ב-US-WEST1, ב-US-CENTRAL1 וב-US-EAST1 יכולות ליהנות מהמסלול תמיד בחינם של Google Cloud Storage. הקטגוריות בכל המיקומים האחרים כפופות לתמחור ולשימוש ב-Google Cloud Storage.
  4. לוחצים על מצב הפקה. בשלבים הבאים תעדכנו את כללי האבטחה האלה כך שיהיו ספציפיים ל-codelab הזה.
  5. לוחצים על יצירה.
  6. עדכון כללי האבטחה:
    1. אחרי שהבאקט מוקצה, עוברים לכרטיסייה כללים.
    2. מעתיקים את הכללים הבאים ומדביקים אותם:
      rules_version = '2';
      service firebase.storage {
        match /b/{bucket}/o {
          match /products.txt {
            allow read;
          }
        }
      }
      
    3. לוחצים על פרסום.
  7. מעלים את תיאורי המוצרים מקוד ההתחלה:
    1. לוחצים על הכרטיסייה Files (קבצים) בקטגוריה של Storage.
    2. לוחצים על העלאת קובץ ומעלים את קובץ products.txt מקוד ההתחלה. הקובץ הזה נמצא במיקום: src/data/products.txt.

הגדרת Firebase AI Logic

‫Firebase AI Logic הוא שירות Firebase העיקרי שבו תשתמשו בשיעור Codelab הזה.

  1. במסוף Firebase, עוברים אל AI Services (שירותי AI) > AI Logic (לוגיקת AI).
  2. לוחצים על שנתחיל?.
  3. בכרטיס Agent Platform Gemini API, לוחצים על Get started with this API (תחילת העבודה עם ה-API הזה) ופועלים לפי ההוראות במסך. בתהליך הזה יופעלו ממשקי ה-API הנדרשים כדי שתוכלו להשתמש ב-Firebase AI Logic עם Agent Platform Gemini API.
  4. (אופציונלי) בוחרים באפשרות Enable AI monitoring (הפעלת ניטור מבוסס-AI) כדי שתוכלו לעקוב אחרי מדדים שונים ברמת האפליקציה ונתוני שימוש, ולקבל תמונה מקיפה של הבקשות שלכם באמצעות 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() });

5. יצירת תבנית לפרומפט בצד השרת

במקום להטמיע הנחיות מורכבות ל-AI באפליקציית הלקוח, תוכלו להשתמש בתחביר Dotprompt כדי לנהל את ההוראות בצורה מאובטחת בשרת.

כך משתמשי הקצה לא יכולים לראות את הכללים הסודיים של 'תקציב הפיצוי'.

  1. במסוף Firebase, עוברים אל AI Services (שירותי AI) > AI Logic (לוגיקת AI) > הכרטיסייה Prompt templates (תבניות של הנחיות).
  2. לוחצים על יצירת תבנית ובוחרים באפשרות תבנית ריקה.
  3. מגדירים את שם התבנית ל-Product Agent ואת המזהה ל-product-agent.
  4. מגדירים את המודל ל-gemini-3.1-flash-lite (או לגרסה העדכנית ביותר שזמינה).
  5. מעתיקים את התוכן של product-agent.prompt (הקובץ הזה נמצא בתיקיית השורש) מקוד לתחילת הדרך שסופק ל-Codelab הזה. לאחר מכן, מדביקים את התוכן הזה בשדה הנחיה ו (אופציונלי) הוראות מערכת של תבנית ההנחיה לשרת במסוף Firebase. התוכן הזה נותן למודל הוראות מאובטחות לגבי ההתנהגות שלו כ'מפעיל חזק' וכולל הפניה לקטלוג המוצרים.
  6. בשדה Test input מגדירים את סכימת הקלט בדיוק כמו בדוגמה הבאה:
    {
      "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.

6. הפעלת מודל ה-AI

עכשיו, אחרי שהתבנית מוגדרת בצורה מאובטחת בשרת, צריך רק לקרוא לה מהקצה הקדמי של האפליקציה.

  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();
    }
    

7. אבטחת הסוכן באמצעות Firebase App Check

מודלים של AI הם עוצמתיים, אבל אפשר גם לנצל אותם לרעה אם נקודות קצה ציבוריות לא מוגנות. תמיד צריך להשתמש ב-Firebase App Check כדי לוודא שרק אפליקציית האינטרנט האמיתית שלכם יכולה לשלוח בקשות מוצלחות ל-Gemini API, ולחסום בוטים ולקוחות לא מורשים.

  1. במסוף Google Cloud, עוברים אל Security (אבטחה) > Fraud Defense (הגנה מפני הונאה).
  2. לוחצים על יצירת מפתח וממלאים את השדות:
    • שם לתצוגה: Codelab Key
    • סוג האפליקציה: אינטרנט
    • רשימת דומיינים: מוסיפים את localhost ו-127.0.0.1 כדי שלשרת Vite המקומי תהיה אפשרות לשלוח בקשות.
  3. לוחצים על יצירת מפתח כדי לרשום את המפתח.
  4. בחלק העליון של הדף 'פרטים של מפתח Fraud Defense', מעתיקים את מזהה מפתח האתר ללוח.
  5. במסוף Firebase, עוברים אל Security (אבטחה) > App Check (בדיקת אפליקציות).
  6. לוחצים על הכרטיסייה אפליקציות, מרחיבים את אפליקציית האינטרנט (Rugged Web) ולוחצים על הספק reCAPTCHA Enterprise.
  7. בשדה מפתח אתר reCAPTCHA Enterprise, מדביקים את מזהה מפתח האתר מדף פרטי המפתח של Fraud Defense ולוחצים על שמירה.
  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, מוודאים שאסימונים לטווח קצר יחולו כדי לעזור להגביל את הניצול לרעה שהקצה העורפי עשוי לקבל.

8. הפעלת האפליקציה

אחרי שמגדירים את Firebase ומקשרים את הווידג'ט של הצ'אט לתמיכה, אפשר להריץ את האפליקציה.

  1. בטרמינל, מריצים את שרת הפיתוח של Vite:
    npm run dev
    
  2. פותחים את כתובת ה-URL המקומית שסופקה (בדרך כלל http://localhost:5173/).
  3. לוחצים על כפתור הפעולה הצף (FAB) תמיכה טקטית בפינה השמאלית התחתונה.
  4. אפשר לשאול שאלות על המוצרים, למשל:
    • "I'm looking for a weatherproof shell"
    • "הכובע שלי עם הטמפרטורה מתחת לאפס פגום, מה אפשר לעשות?"
    • כדאי להמשיך לדחות את ההמלצות כדי להפעיל את הלוגיקה של ה-AI בנוגע ל'תקציב פיוס'!

9. (אופציונלי) מחיקת משאבים מ-Codelab

כדי להימנע מחיובים אפשריים בחשבון לחיוב ב-Google Cloud, אפשר למחוק את המשאבים שנוצרו במהלך ה-codelab הזה.

  1. במסוף Firebase, עוברים אל הגדרות > הכרטיסייה כללי.
  2. מוודאים שהפרויקט שמוצג הוא הפרויקט שבו השתמשתם ב-codelab הזה. אם זה לא הפרויקט של ה-Codelab, אפשר להשתמש בכלי לבחירת פרויקטים בפינה הימנית העליונה כדי לשנות את הפרויקט.
  3. גוללים לחלק התחתון של הדף ולוחצים על מחיקת הפרויקט.
  4. פועלים לפי ההוראות במסך כדי לאשר את המחיקה.

10. כל הכבוד!

🎊 המשימה הושלמה! הצלחתם לשלב סוכן תמיכת לקוחות מבוסס-AI חזק שמבוסס על תבנית.

מה השגתם:

  • הפעלת Firebase והקצה העורפי של Agent Platform באפליקציית לקוח.
  • הגדרת תבנית מאובטחת לפרומפט בצד השרת באמצעות Handlebars וסכימות קלט מחמירות כדי להגדיר את ההתנהגות המורכבת של הסוכן.
  • קורא באופן דינמי למודל LLM ומעביר בצורה מאובטחת את היסטוריית הצ'אט ומזהי מוצרים הקשריים, בלי לחשוף ללקוח את הלוגיקה הפנימית של ההנחיות.

מה השלב הבא?

  • ‫Firebase App Check: מאבטח את נקודות הקצה של ה-AI מפני שימוש לרעה.