פיתוח חוויות היברידיות באפליקציות אינטרנט באמצעות מודלים שמתארחים בענן ובמכשיר

פיתוח תכונות ואפליקציות אינטרנט מבוססות-AI עם הסקת מסקנות היברידית באמצעות Firebase AI Logic. הסקה היברידית מאפשרת להריץ הסקה באמצעות מודלים במכשיר כשהם זמינים, ולחזור בצורה חלקה למודלים שמתארחים בענן במקרים אחרים (ולהפך).

בדף הזה מוסבר איך להתחיל להשתמש ב-SDK של הלקוח. אחרי שתסיימו את ההגדרה הרגילה, כדאי לעיין באפשרויות וביכולות הנוספות להגדרה (כמו פלט מובנה).

שימו לב שהסקה במכשיר נתמכת באפליקציות אינטרנט שפועלות ב-Chrome במחשב.

דילוג לדוגמאות הקוד

תרחישי שימוש מומלצים ויכולות נתמכות

תרחישים מומלצים לשימוש:

• שימוש במודל במכשיר להסקת מסקנות מציע:

  • פרטיות משופרת
  • הקשר מקומי
  • הסקה ללא עלות
  • פונקציונליות אופליין

• שימוש בפונקציונליות משולבת:

  • להגיע ל-100% מהקהל, בלי קשר לזמינות של המודל במכשיר או לחיבור לאינטרנט

יכולות ותכונות נתמכות להסקת מסקנות במכשיר:

הסקה במכשיר תומכת רק ביצירת טקסט בסבב יחיד (לא צ'אט), עם פלט בסטרימינג או לא בסטרימינג. הוא תומך ביכולות הבאות ליצירת טקסט:

• יצירת טקסט מקלט טקסט בלבד

• יצירת טקסט מקלט של טקסט ותמונה, במיוחד סוגי תמונות קלט של JPEG ו-PNG

אפשר גם ליצור פלט מובנה, כולל JSON וטיפוסי enum.

לפני שמתחילים

חשוב לזכור:

• הסקה באמצעות מודל במכשיר משתמשת ב-Prompt API מ-Chrome, ואילו הסקה באמצעות מודל שמתארח בענן משתמשת בספק Gemini API שבחרתם (Gemini Developer API או Agent Platform Gemini API (formerly Vertex AI)).

• בדף הזה מוסבר איך להתחיל לפתח באמצעות localhost (מידע נוסף על שימוש בממשקי API ב-localhost זמין במסמכי התיעוד של Chrome).

  אחרי שתסיימו את ההגדרה הרגילה, כדאי לעיין באפשרויות וביכולות הנוספות להגדרה (כמו פלט מובנה).

תחילת העבודה ב-localhost

השלבים הבאים מתארים את ההגדרה הכללית הנדרשת לכל בקשת הנחיה נתמכת שרוצים לשלוח.

שלב 1: מגדירים את Chrome ואת Prompt API להסקה במכשיר

1. חשוב לוודא שאתם משתמשים בגרסה עדכנית של Chrome. מעדכנים בכתובת chrome://settings/help.
   הסקה במכשיר זמינה ב-Chrome מגרסה 139 ואילך.

2. כדי להפעיל את המודל המולטי-מודאלי במכשיר, מגדירים את הדגל הבא לערך Enabled:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. מפעילים מחדש את Chrome.

4. (אופציונלי) מורידים את המודל במכשיר לפני הבקשה הראשונה.

   ‫Prompt API מובנה ב-Chrome, אבל המודל במכשיר לא זמין כברירת מחדל. אם עדיין לא הורדתם את המודל לפני הבקשה הראשונה להסקת מסקנות במכשיר, הבקשה תתחיל באופן אוטומטי את הורדת המודל ברקע.

   הוראות להורדת המודל במכשיר

   1. פותחים את כלים למפתחים > מסוף.

   2. מריצים את הפקודה הבאה:

      await LanguageModel.availability();
      

   3. מוודאים שהפלט הוא available,‏ downloading או downloadable.

   4. אם הפלט הוא downloadable, מפעילים את הורדת המודל באמצעות הפקודה:

      await LanguageModel.create();
      

   5. אתם יכולים להשתמש בקריאה החוזרת (callback) הבאה של monitor כדי להאזין להתקדמות ההורדה ולוודא שהמודל available לפני שאתם שולחים בקשות:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

שלב 2: מגדירים פרויקט ב-Firebase ומקשרים את האפליקציה ל-Firebase

1. נכנסים למסוף Firebase ובוחרים את הפרויקט ב-Firebase.

   אין לכם עדיין פרויקט ב-Firebase?

   אם עדיין אין לכם פרויקט ב-Firebase, לחצו על הלחצן כדי ליצור פרויקט חדש ב-Firebase, ואז השתמשו באחת מהאפשרויות הבאות:

   • אפשרות 1: יוצרים פרויקט חדש לגמרי ב-Firebase (ופרויקט Google Cloud שמשויך אליו באופן אוטומטי) על ידי הזנת שם פרויקט חדש בשלב הראשון של תהליך העבודה.

   • אפשרות 2: "הוספת Firebase" לפרויקט קיים ב-Google Cloud. כדי לעשות את זה, לוחצים על הוספת Firebase לפרויקט בענן של Google (בתחתית הדף). בשלב הראשון של תהליך העבודה, מתחילים להזין את שם הפרויקט הקיים ובוחרים את הפרויקט מהרשימה שמוצגת.

   מבצעים את שאר השלבים בתהליך העבודה שמוצג במסך כדי ליצור פרויקט ב-Firebase. שימו לב: כשמוצגת בקשה, לא צריך להגדיר את Google Analytics כדי להשתמש בערכות ה-SDK של Firebase AI Logic.

2. במסוף Firebase, נכנסים לדף AI Services ‏ > AI Logic.

3. לוחצים על Get started כדי להפעיל תהליך עבודה מודרך שיעזור לכם להגדיר את ממשקי ה-API הנדרשים ואת המשאבים לפרויקט.

4. אם מוצגת בקשה, פועלים לפי ההוראות במסך כדי לרשום את האפליקציה ולהוסיף לה את הגדרות Firebase.

5. כשמתבקשים לבחור "ספק Gemini API", מומלץ לבחור באפשרות Gemini Developer API, שמאפשרת להתחיל במהירות וללא עלות.

   בכל שלב בהמשך, תמיד תוכלו להגדיר את Agent Platform Gemini API (formerly Vertex AI) (והדרישה שלו לחיוב).

6. ממשיכים בתהליך העבודה כדי להגדיר את ממשקי ה-API הנדרשים ואת השירותים שמשויכים ל-Firebase AI Logic.

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

7. כדי להוסיף את ערכות ה-SDK הנדרשות לאפליקציה, המשיכו לשלב הבא במדריך הזה.

שלב 3: הוספת ה-SDK

ספריית Firebase מספקת גישה לממשקי ה-API כדי ליצור אינטראקציה עם מודלים גנרטיביים. הספרייה כלולה כחלק מ-Firebase JavaScript SDK for Web.

1. מתקינים את Firebase JS SDK לאינטרנט באמצעות npm:

   npm install firebase
   

2. מפעילים את Firebase באפליקציה:

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

שלב 4: הגדרת ספק האימות לצורכי ניפוי באגים של App Check לפיתוח מקומי

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

כך משתמשים בספק האימות לצורכי ניפוי באגים כשמפעילים את האפליקציה מ-localhost באופן אינטראקטיבי (לדוגמה, במהלך פיתוח מקומי):

1. בגרסת ה-build לניפוי באגים, מפעילים את מצב ניפוי הבאגים על ידי הגדרת self.FIREBASE_APPCHECK_DEBUG_TOKEN ל-true לפני שמפעילים את App Check. לדוגמה:

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. נכנסים לאפליקציית האינטרנט באופן מקומי ופותחים את הכלים למפתחים בדפדפן. במסוף ניפוי הבאגים יופיע אסימון ניפוי באגים:

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. רושמים את אסימון ניפוי הבאגים ב-App Check:

   1. במסוף Firebase, נכנסים לכרטיסייה Security ‏ > App Check ‏ > Apps.

   2. מוצאים את האפליקציה, לוחצים על סמל האפשרויות הנוספות (more_vert) ובוחרים באפשרות ניהול אסימוני ניפוי באגים.

   3. פועלים לפי ההוראות במסך כדי לרשום את אסימון ניפוי הבאגים.

פרטים נוספים על ספק האימות לצורכי ניפוי באגים (כולל איך לקבל אסימון חדש לניפוי באגים) זמינים במסמכי התיעוד הרשמיים של App Check.

שלב 5: הפעלת השירות ויצירת מופע של המודל

לפני ששולחים בקשת הנחיה למודל, צריך להגדיר את הדברים הבאים:

1. מפעילים את השירות של ספק ה-API שבחרתם.

2. יוצרים מכונה של GenerativeModel. חשוב להגדיר את mode לאחת מהאפשרויות הבאות:

   • ‫PREFER_ON_DEVICE: שימוש במודל במכשיר אם הוא זמין, ואם לא, חזרה למודל שמתארח בענן.

   • ‫ONLY_ON_DEVICE: שימוש במודל במכשיר אם הוא זמין, אחרת הפעלת חריגה.

   • ‫PREFER_IN_CLOUD: שימוש במודל שמתארח בענן אם הוא זמין, ואם לא, חזרה למודל במכשיר.

   • ‫ONLY_IN_CLOUD: שימוש במודל שמתארח בענן אם הוא זמין, אחרת הצגת חריגה.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

שלב 6: הפעלת המודל במכשיר

צריך להפעיל את initializeDeviceModel() אחרי או במהלך אינטראקציה של משתמש הקצה עם הדף (כמו לחיצה על כפתור) ולפני ששולחים בקשת הנחיה למודל. מידע נוסף על הדרישה להפעלת משתמש זמין במסמכי התיעוד של Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

שלב 7: שליחת בקשת הנחיה למודל

בקטע הזה מוסבר איך לשלוח סוגים שונים של קלט כדי ליצור סוגים שונים של פלט, כולל:

• יצירת טקסט דינמי מבוסס-AI מקלט של טקסט בלבד
• יצירת טקסט דינמי מבוסס-AI מקלט של טקסט ותמונה (מולטי-מודאלי)

אם אתם רוצים ליצור פלט מובנה (כמו JSON או טיפוסים בני מנייה (enum)), אתם יכולים להשתמש באחת מהדוגמאות הבאות של "טקסט דינמי מבוסס-AI" וגם להגדיר את המודל כך שיגיב לפי סכימה.

יצירת טקסט דינמי מבוסס-AI מקלט טקסט בלבד

אתם יכולים להשתמש ב-generateContent() כדי ליצור טקסט דינמי מבוסס-AI מפרומפט שמכיל טקסט:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

שימו לב ש-Firebase AI Logic תומך גם בסטרימינג של תשובות טקסט באמצעות generateContentStream (במקום generateContent).

יצירת טקסט מקלט של טקסט ותמונה (מולטי-מודאלי)

אתם יכולים להשתמש ב-generateContent() כדי ליצור טקסט דינמי מבוסס-AI מפרומפט שמכילה קובצי טקסט וקובצי תמונה, על ידי ציון ה-mimeType של כל קובץ קלט והקובץ עצמו.

סוגי התמונות הנתמכים להסקת מסקנות במכשיר הם PNG ו-JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    type: "inlineData",
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

שימו לב ש-Firebase AI Logic תומך גם בסטרימינג של תשובות טקסט באמצעות generateContentStream (במקום generateContent).

מה עוד אפשר לעשות?

אתם יכולים להשתמש באפשרויות הגדרה וביכולות נוספות בשביל חוויות היברידיות:

• הגדרת מצב היסק

• שינוי מודל ברירת המחדל החלופי שמתארח בענן

• שימוש בהגדרות המודל כדי לשלוט בתשובות

• יצירת פלט מובנה (כמו JSON)

תכונות שעדיין לא זמינות להסקת מסקנות במכשיר

לא כל היכולות של Web SDK זמינות להסקה במכשיר. התכונות הבאות עדיין לא נתמכות בהסקת מסקנות במכשיר (אבל בדרך כלל הן זמינות להסקת מסקנות בענן).

• יצירת טקסט מסוגי קבצים של קלט תמונה שאינם JPEG ו-PNG

  • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.

• יצירת טקסט מקלט של אודיו, וידאו ומסמכים (כמו קובצי PDF)

  • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.

• יצירת תמונות באמצעות מודלים של Gemini Nano Banana

  • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.

• לספק קבצים באמצעות כתובות URL בבקשות מולטי-מודאליות. אתם צריכים לספק קבצים כנתונים מוטבעים למודלים במכשיר.

• שיחה עם זיכרון

  • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.

• סטרימינג דו-כיווני עם Gemini Live API

• לספק למודל כלים שיעזרו לו ליצור את התשובה (כמו קריאה להפעלת פונקציות, הרצת קוד, URL Context, ביסוס בעזרת Google Search וביסוס בעזרת Google Maps)

• ספירת טוקנים

  • תמיד מחזירה שגיאה. הספירה תהיה שונה בין מודלים שמתארחים בענן לבין מודלים במכשיר, ולכן אין חלופה אינטואיטיבית.

• מעקב אחרי שימוש בתכונות AI במסוף Firebase להסקת מסקנות במכשיר.

  • שימו לב: אפשר לעקוב אחרי כל הסקה שמשתמשת במודלים שמתארחים בענן, בדיוק כמו הסקות אחרות שמשתמשות ב-SDK של הלקוח של Firebase AI Logic לאינטרנט.

שליחת משוב על חוויית השימוש ב-Firebase AI Logic