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

1. מבוא

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

מה עושים:

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

מה דרוש לכם?

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

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

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

5. יצירת תבנית הנחיה בצד השרת

במקום להטמיע הנחיות מורכבות ל-AI באפליקציית הלקוח, תוכלו להשתמש בתחביר 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 מספריית הבסיס לשדה הנחיה והוראות מערכת אופציונליות. ההוראה הזו מנחה את המודל בצורה מאובטחת איך להתנהג בתור 'מפעיל חזק' ומוסיפה את קטלוג המוצרים.
  6. במסוף Firebase, שומרים ומפרסמים את תבנית 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 כדי לוודא שרק אפליקציית האינטרנט האמיתית שלכם יכולה לקרוא למודל הגנרטיבי של Vertex AI, ולחסום בוטים ולקוחות לא מורשים.

  1. במסוף Firebase, עוברים אל Build (פיתוח) > App Check.
  2. לוחצים על הכרטיסייה אפליקציות, מרחיבים את אפליקציית האינטרנט (Rugged Web) ולוחצים על הספק reCAPTCHA Enterprise.
  3. בוחרים באפשרות יצירת מפתח חדש של reCAPTCHA Enterprise וממלאים את ההנחיה:
    • Name (שם): Codelab Key
    • Domains: מוסיפים את 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, מוודאים שטוקנים לטווח קצר יחולו כדי לעזור להגביל את הניצול לרעה שהבק-אנד עשוי לקבל.

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

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

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

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

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

  1. עוברים אל מסוף Firebase.
  2. בוחרים את הפרויקט rugged-terrain-ai.
  3. עוברים אל הגדרות הפרויקט (סמל גלגל השיניים).
  4. גוללים לחלק התחתון של הדף ולוחצים על מחיקת הפרויקט.
  5. פועלים לפי ההוראות במסך כדי לאשר את המחיקה.

10. כל הכבוד!

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

מה השגתם:

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

מה השלב הבא?

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