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

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

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

שימו לב: הסקת מסקנות במכשיר באמצעות Firebase AI Logic נתמכת באפליקציות אינטרנט שמשתמשות ב-Firebase AI Logic SDK בגרסה 12.5.0 ואילך ופועלות ב-Chrome במחשב (גרסה 139 ואילך).

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

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

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

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

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

    • לספק חוויית שימוש דומה באפליקציה, בלי קשר למכשיר של משתמש הקצה
    • לשפר את הזמינות של תכונות מבוססות-AI גנרטיבי, בלי קשר לחיבור לאינטרנט, למגבלות המכסות או ליכולות המכשיר

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

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

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

ממשקי API ופלטפורמות נתמכים

בקטעים הבאים מתוארים ממשקי ה-API הנתמכים, וגם הפלטפורמות והדפדפנים הנתמכים.

ממשקי API נתמכים להסקת מסקנות בענן לעומת במכשיר

  • הסקה בענן משתמשת בספק Gemini API שבחרתם (Gemini Developer API או Agent Platform Gemini API (formerly Vertex AI)).

  • ההסקה במכשיר מתבצעת באמצעות Prompt API מ-Chrome.

פלטפורמות ודפדפנים נתמכים

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

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

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

במסמכי התיעוד של Chrome אפשר לקרוא מידע נוסף על שימוש בממשקי API ב-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, אבל המודל במכשיר לא זמין כברירת מחדל. אם עדיין לא הורדתם את המודל לפני הבקשה הראשונה להסקת מסקנות במכשיר, הבקשה תתחיל באופן אוטומטי את הורדת המודל ברקע.

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

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

  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. מוצאים את האפליקציה, לוחצים על סמל האפשרויות הנוספות () ובוחרים באפשרות ניהול אסימוני ניפוי באגים.

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

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

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

כדי לראות תוכן וקוד שספציפיים לספק, לוחצים על הספק Gemini API בדף הזה.

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

  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: שליחת בקשת הנחיה למודל

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

אם אתם רוצים ליצור פלט מובנה (כמו 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).

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

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

תכונות שעדיין לא נתמכות

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

תכונות שעדיין לא נתמכות בהטמעות היברידיות

אי אפשר להשתמש בתכונות הבאות בהטמעות היברידיות (לא במכשיר ולא באמצעות גיבוי בענן):

  • ‫Gemini Live API: אין תמיכה בסטרימינג דו-כיווני בזמן אמת.

  • תבניות לפרומפטים בשרת: אין תמיכה בתבניות מנוהלות לפרומפטים בשרת.

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

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

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

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

    • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.
  • יצירת טקסט מסוגי קבצים של קלט תמונה שאינם JPEG ו-PNG

    • אפשר לחזור למודל שמתארח בענן, אבל במצב ONLY_ON_DEVICE תופיע שגיאה.
  • יצירת טקסט דינמי מבוסס-AI מקלט מולטי-מודאלי של אודיו, וידאו ומסמכים (קובצי PDF)

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

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

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

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

מגבלות נוספות

בנוסף לאמור למעלה, להסקת מסקנות במכשיר יש את המגבלות הבאות:

  • משתמשי הקצה של האפליקציה צריכים להפעיל את Chrome במחשב (גרסה 139 ואילך) כשהדגלים הנדרשים מופעלים.

  • כדי להוריד את המודל בפעם הראשונה, צריך שיהיה מספיק מקום פנוי במכשיר של המשתמש.


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