יצירת סוכן תמיכת לקוחות מבוסס-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 (קבצים) של קטגוריית האחסון.
    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. (אופציונלי) בוחרים באפשרות מעקב אחרי שימוש בתכונות 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. מהקוד לתחילת הדרך שסופק ל-Codelab הזה, מעתיקים את התוכן של product-agent.prompt (הקובץ הזה נמצא בתיקיית השורש). לאחר מכן, הדביקו את התוכן הזה בשדה הנחיה ו (אופציונלי) הוראות מערכת בתבנית לפרומפט של השרת במסוף 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. לוחצים על Create key כדי לרשום את המפתח.
  4. בחלק העליון של הדף 'פרטים של מפתח Fraud Defense', מעתיקים את מזהה מפתח האתר ללוח.
  5. במסוף Firebase, עוברים אל 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, מוודאים שאסימונים לטווח קצר יחולו כדי לעזור להגביל את הניצול לרעה שהקצה העורפי עשוי לקבל.

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

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

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

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

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

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

10. כל הכבוד!

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

מה השגתם:

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

מה השלב הבא?

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