הוספת קבצים גדולים לבקשות עם מודלים מרובים לזיהוי (multimodal) וניהול קבצים באמצעות Cloud Storage for Firebase

כשאתם קוראים ל-Gemini API מהאפליקציה באמצעות SDK של Vertex AI in Firebase, אתם יכולים להנחות את מודל Gemini ליצור טקסט על סמך קלט רב-מודלי. הנחיות מרובה-מצבים יכולות לכלול כמה מודלים (או סוגי קלט), כמו טקסט עם תמונות, קובצי PDF, סרטונים ואודיו.

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

  • אפשר להשתמש ב-Cloud Storage for Firebase עם כל בקשה רב-מודאלית (כמו יצירת טקסט וצ'אט). בדוגמאות במדריך הזה מוצגת קלט בסיסי של טקסט ותמונה.

  • צריך לציין את סוג ה-MIME של הקובץ ואת כתובת ה-URL‏ Cloud Storage for Firebase שלו (שתמיד מתחילה ב-gs://) בקלט הבקשה. הערכים האלה הם מטא-נתונים שמוקציים באופן אוטומטי לכל קובץ שמעלים לקטגוריה Cloud Storage.

  • צריך להשתמש בסוג קובץ וכתובת URL נתמכים.


במדריך הפתרון הזה נסביר איך להגדיר את Cloud Storage for Firebase, להעלות קובץ לקטגוריה (bucket) Cloud Storage for Firebase מהאפליקציה ואז לכלול את סוג ה-MIME של הקובץ וכתובת ה-URL של Cloud Storage for Firebase בבקשה הרב-מודאלית ל-Gemini API.

רוצה לראות את דוגמאות הקוד? או שאולי כבר הגדרתם את Cloud Storage for Firebase ואתם מוכנים להתחיל להשתמש בו בבקשות שלכם עם מספר שיטות להפעלה?

מעבר לדוגמאות הקוד

למה כדאי להשתמש ב-Cloud Storage for Firebase באפליקציה?

Cloud Storage for Firebase משתמש באותה תשתית מהירה, מאובטחת וניתנת להתאמה כמו Google Cloud Storage כדי לאחסן blobs וקובצי נתונים, וערכות ה-SDK של הלקוח שלו מיועדות במיוחד לאפליקציות לנייד ולאינטרנט.

ב-SDK של Vertex AI in Firebase, גודל הבקשה המקסימלי הוא 20MB. אם הבקשה גדולה מדי, תופיע שגיאת HTTP 413. אם גודל הקובץ יגרום לגודל הבקשה הכולל לחרוג מ-20MB, צריך להשתמש בכתובת URL מסוג Cloud Storage for Firebase כדי לכלול את הקובץ בבקשה הרב-מודאלית. עם זאת, אם הקובץ קטן, בדרך כלל אפשר להעביר אותו ישירות כנתונים בקוד (עם זאת, חשוב לזכור שקובץ שסופק כנתונים בקוד מקודד ל-base64 במעבר, וכך גדל גודל הבקשה).

אלה כמה יתרונות נוספים של השימוש ב-Cloud Storage for Firebase:

  • אתם יכולים לאפשר למשתמשי הקצה להעלות תמונות ישירות מהאפליקציה שלכם לקטגוריה Cloud Storage for Firebase, ואז לכלול את התמונות האלה בהנחיות הרב-מודאליות שלכם פשוט על ידי ציון סוג ה-MIME של הקובץ וכתובת ה-URL של Cloud Storage for Firebase (המזהה של הקובץ).

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

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

  • אפשר להגביל את הגישה של משתמשי הקצה לקבצים שמאוחסנים ב-Cloud Storage for Firebase באמצעות Firebase Security Rules, שמאפשרת רק למשתמש מורשה להעלות, להוריד או למחוק קבצים.

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

אילו סוגי קבצים וכתובות URL נתמכים?

אלה הדרישות לגבי קבצים וכתובות URL כשרוצים להשתמש בכתובות URL מסוג Cloud Storage for Firebase עם ערכות ה-SDK של Vertex AI in Firebase:

  • כשמשתמשים ב-SDKs של Vertex AI in Firebase, הקובץ צריך לעמוד בדרישות של קובצי קלט לבקשות עם כמה מודלים. הדרישות האלה כוללות, למשל, סוג MIME וגודל הקובץ.

  • הקובץ צריך להיות מאוחסן בקטגוריה (bucket) מסוג Cloud Storage for Firebase (כלומר, הקטגוריה צריכה להיות נגישה לשירותי Firebase, כמו Firebase Security Rules). אם אתם יכולים לראות את הקטגוריה במסוף Firebase, סימן שמדובר בקטגוריה מסוג Cloud Storage for Firebase.

  • הקטגוריה Cloud Storage for Firebase צריכה להיות באותו פרויקט Firebase שבו רשמתם את האפליקציה.

  • כתובת ה-URL Cloud Storage for Firebase של הקובץ חייבת להתחיל ב-gs://, כי כך נוצרות כל כתובות ה-URL מסוג Google Cloud Storage.

  • כתובת ה-URL של הקובץ לא יכולה להיות כתובת URL של 'דפדפן' (לדוגמה, כתובת ה-URL של תמונה שנמצאת באינטרנט).

בנוסף, ה-Firebase Security Rules של הקטגוריה צריך לאפשר גישה מתאימה לקובץ. לדוגמה:

  • אם יש לכם כללים ציבוריים, כל משתמש או לקוח יכול לגשת לקובץ ולספק את כתובת ה-URL שלו בקריאה באמצעות Vertex AI in Firebase SDK. יש להשתמש בסוגים האלה של כללים רק כדי להתחיל לעבוד ובשלבי האב-טיפוס המוקדמים (אלא אם הקבצים מיועדים להיות קבצים שיהיו נגישים לכולם).

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

שימוש בכתובות URL מסוג Cloud Storage for Firebase עם Vertex AI in Firebase

שלב 1: מגדירים את Cloud Storage for Firebase

הוראות מפורטות להגדרה של Cloud Storage for Firebase ולהשתמש בו מפורטות במדריך למתחילים.

למדריך לתחילת העבודה ב-Cloud Storage for Firebase

אלה המשימות ברמה גבוהה שצריך לבצע:

  1. יוצרים קטגוריה Cloud Storage for Firebase בפרויקט Firebase.

    אם כבר יש לכם קטגוריה Cloud Storage בפרויקט Google Cloud שבה אתם רוצים להשתמש עם Vertex AI in Firebase, תוכלו להפוך אותה לנגישה לשירותי Firebase (כולל Vertex AI in Firebase) על ידי "ייבוא" של הקטגוריה ל-Firebase.

  2. מחילים את Firebase Security Rules על הקטגוריה הזו. Firebase Security Rules עוזרים לכם לאבטח את הקבצים על ידי הגבלת הגישה של משתמשי קצה מורשים.

  3. מוסיפים לאפליקציה את ספריית הלקוח של Cloud Storage for Firebase.

    שימו לב שאפשר לדלג על המשימה הזו, אבל אם תעשו זאת, תצטרכו תמיד לכלול במפורש את סוג ה-MIME ואת ערכי כתובת ה-URL של Cloud Storage for Firebase בבקשות שלכם למודלים מרובים.

שלב 2: מעלים קובץ לקטגוריה

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

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

  • סוג MIME: זהו סוג המדיה של הקובץ (לדוגמה, image/png). Cloud Storage for Firebase ינסה לזהות את סוג ה-MIME באופן אוטומטי במהלך ההעלאה ולהחיל את המטא-נתונים האלה על האובייקט בקטגוריה. עם זאת, אפשר לציין את סוג ה-MIME במהלך ההעלאה.

  • כתובת ה-URL של Cloud Storage for Firebase: זהו מזהה ייחודי של הקובץ. כתובת ה-URL חייבת להתחיל ב-gs://.

שלב 3: כוללים את סוג ה-MIME ואת כתובת ה-URL של הקובץ בבקשה רב-מודאלית

אחרי שמאחסנים קובץ בקטגוריה Cloud Storage for Firebase, אפשר לכלול את סוג ה-MIME ואת כתובת ה-URL של Cloud Storage for Firebase בבקשה עם כמה מודלים. חשוב לזכור שבדוגמאות האלה מוצגת בקשת generateContent ללא סטרימינג, אבל אפשר להשתמש גם בכתובות URL מסוג Cloud Storage for Firebase עם סטרימינג וצ'אט.

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

אפשרות 1: הוספת סוג ה-MIME וכתובת ה-URL באמצעות הפניה ל-Storage

השתמשו באפשרות הזו אם העליתם את הקובץ לקטגוריה (bucket) ועכשיו אתם רוצים לכלול אותו (דרך הפניה ל-Storage) בבקשה הרב-מודאלית. בקריאה נדרשים גם סוג ה-MIME וגם כתובת ה-URL של Cloud Storage for Firebase.

Kotlin+KTX

ב-Kotlin, השיטות ב-SDK הזה הן פונקציות השהיה (suspend), וצריך לקרוא להן מהיקף של פונקציית אירוע (coroutine). 
// Upload an image file using Cloud Storage for Firebase.
val storageRef = Firebase.storage.reference.child("images/image.jpg")
val fileUri = Uri.fromFile(File("image.jpg"))
try {
    val taskSnapshot = storageRef.putFile(fileUri).await()
    // Get the MIME type and Cloud Storage for Firebase file path.
    val mimeType = taskSnapshot.metadata?.contentType
    val bucket = taskSnapshot.metadata?.bucket
    val filePath = taskSnapshot.metadata?.path

    if (mimeType != null && bucket != null) {
        // Construct a URL in the required format.
        val storageUrl = "gs://$bucket/$filePath"
        // Construct a prompt that includes text, the MIME type, and the URL.
        val prompt = content {
            fileData(mimeType = mimeType, uri = storageUrl)
            text("What's in this picture?")
        }
        // To generate text output, call generateContent with the prompt.
        val response = generativeModel.generateContent(prompt)
        println(response.text)
    }
} catch (e: StorageException) {
    // An error occurred while uploading the file.
} catch (e: GoogleGenerativeAIException) {
    // An error occurred while generating text.
}

Java

ב-Java, השיטות ב-SDK הזה מחזירות ListenableFuture. 
// Upload an image file using Cloud Storage for Firebase.
StorageReference storage = FirebaseStorage.getInstance().getReference("images/image.jpg");
Uri fileUri = Uri.fromFile(new File("images/image.jpg"));

storage.putFile(fileUri).addOnSuccessListener(taskSnapshot -> {
    // Get the MIME type and Cloud Storage for Firebase file path.
    String mimeType = taskSnapshot.getMetadata().getContentType();
    String bucket = taskSnapshot.getMetadata().getBucket();
    String filePath = taskSnapshot.getMetadata().getPath();

    if (mimeType != null && bucket != null) {
        // Construct a URL in the required format.
        String storageUrl = "gs://" + bucket + "/" + filePath;
        // Create a prompt that includes text, the MIME type, and the URL.
        Content prompt = new Content.Builder()
                .addFileData(storageUrl, mimeType)
                .addText("What's in this picture?")
                .build();

        // To generate text output, call generateContent with the prompt.
        GenerativeModelFutures modelFutures = GenerativeModelFutures.from(model);
        ListenableFuture<GenerateContentResponse> response = modelFutures.generateContent(prompt);
        Futures.addCallback(response, new FutureCallback<>() {
            @Override
            public void onSuccess(GenerateContentResponse result) {
                String resultText = result.getText();
                System.out.println(resultText);
            }

            @Override
            public void onFailure(@NonNull Throwable t) {
                t.printStackTrace();
            }
        }, executor);
    }
}).addOnFailureListener(e -> {
    // An error occurred while uploading the file.
    e.printStackTrace();
});

אפשרות 2: כוללים את סוג ה-MIME ואת כתובת ה-URL באופן מפורש

משתמשים באפשרות הזו אם אתם יודעים את הערכים של סוג ה-MIME וכתובת ה-URL‏ Cloud Storage for Firebase, ואתם רוצים לכלול אותם במפורש בבקשה הרב-מודאלית. בקריאה נדרשים גם סוג ה-MIME וגם כתובת ה-URL.

Kotlin+KTX

ב-Kotlin, השיטות ב-SDK הזה הן פונקציות השהיה (suspend), וצריך לקרוא להן מהיקף של פונקציית אירוע (coroutine). 
// Construct a prompt that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
val prompt = content {
    fileData(mimeType = "image/jpeg", uri = "gs://bucket-name/path/image.jpg")
    text("What's in this picture?")
}
// To generate text output, call generateContent with the prompt.
val response = generativeModel.generateContent(prompt)
println(response.text)

Java

ב-Java, השיטות ב-SDK הזה מחזירות ListenableFuture. 
// Construct a prompt that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
Content prompt = new Content.Builder()
        .addFilePart("gs://bucket-name/path/image.jpg", "image/jpeg")
        .addText("What's in this picture?")
        .build();

// To generate text output, call generateContent with the prompt
GenerativeModelFutures modelFutures = GenerativeModelFutures.from(model);
ListenableFuture<GenerateContentResponse> response = modelFutures.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(@NonNull Throwable t) {
        t.printStackTrace();
    }
}, executor);