فایل‌های بزرگ را در درخواست‌های چندوجهی قرار دهید و فایل‌ها را با استفاده از Cloud Storage برای Firebase مدیریت کنید

هنگام فراخوانی Gemini API از برنامه خود با استفاده از Vertex AI in Firebase SDK، می‌توانید از مدل Gemini بخواهید متنی را بر اساس یک ورودی چندوجهی تولید کند. اعلان‌های چندوجهی می‌توانند شامل چندین حالت (یا انواع ورودی)، مانند متن همراه با تصاویر، فایل‌های PDF، ویدئو و صدا باشند.

برای بخش‌های غیر متنی ورودی (مانند فایل‌های رسانه)، می‌توانید به صورت اختیاری از Cloud Storage for Firebase استفاده کنید تا فایل‌ها را در درخواست اضافه کنید. در سطح بالا، آنچه باید در مورد این ویژگی بدانید به شرح زیر است:

  • می‌توانید با هر درخواست چندوجهی (مانند تولید متن و چت) از Cloud Storage for Firebase استفاده کنید. مثال‌های این راهنما یک ورودی متن و تصویر اساسی را نشان می‌دهند.

  • شما نوع MIME فایل و Cloud Storage for Firebase (که همیشه با gs:// شروع می شود) در ورودی درخواست مشخص می کنید. این مقادیر به صورت خودکار به هر فایلی که در یک سطل Cloud Storage آپلود می‌شود، ابرداده اختصاص می‌یابد.

  • باید از نوع فایل و URL پشتیبانی شده استفاده کنید.


این راهنمای راه‌حل نحوه راه‌اندازی Cloud Storage for Firebase ، آپلود یک فایل در سطل Cloud Storage for Firebase از برنامه‌تان، و سپس گنجاندن نوع MIME فایل و Cloud Storage for Firebase در درخواست چندوجهی‌تان به Gemini API توضیح می‌دهد.

آیا می خواهید نمونه کدها را ببینید؟ یا قبلاً Cloud Storage for Firebase راه‌اندازی کرده‌اید و آماده شروع استفاده از آن با درخواست‌های چندوجهی خود هستید؟

به نمونه کدها بروید

چرا از Cloud Storage for Firebase با برنامه خود استفاده کنید؟

Cloud Storage for Firebase از همان زیرساخت سریع، ایمن و مقیاس‌پذیر Google Cloud Storage برای ذخیره حباب‌ها و فایل‌ها استفاده می‌کند و SDK‌های مشتری آن به‌طور خاص برای برنامه‌های موبایل و وب ساخته شده‌اند.

برای Vertex AI in Firebase SDK، حداکثر اندازه درخواست 20 مگابایت است. اگر درخواست خیلی بزرگ باشد، خطای HTTP 413 دریافت می کنید. اگر اندازه فایل باعث می‌شود که حجم کل درخواست از 20 مگابایت بیشتر شود، از یک Cloud Storage for Firebase استفاده کنید تا فایل را در درخواست چندوجهی خود قرار دهید. با این حال، اگر یک فایل کوچک است، اغلب می‌توانید آن را مستقیماً به‌عنوان داده‌های درون خطی ارسال کنید (البته توجه داشته باشید که فایلی که به‌عنوان داده‌های درون‌خط ارائه می‌شود در حین انتقال به base64 کدگذاری می‌شود، که اندازه درخواست را افزایش می‌دهد).

در اینجا برخی از مزایای اضافی استفاده از Cloud Storage for Firebase آورده شده است:

  • می‌توانید از کاربران نهایی بخواهید تصاویر را مستقیماً از برنامه شما در سطل Cloud Storage for Firebase آپلود کنند، و سپس می‌توانید آن تصاویر را فقط با تعیین نوع MIME فایل و Cloud Storage for Firebase (که یک شناسه برای فایربیس است) در پیام‌های چندوجهی خود قرار دهید. فایل).

  • در صورت نیاز به ارائه تصاویر، به خصوص اگر کیفیت شبکه ضعیف یا ضعیفی داشته باشند، می توانید در زمان و پهنای باند کاربران نهایی خود صرفه جویی کنید.

    • اگر آپلود یا دانلود فایل قطع شود، Cloud Storage for Firebase SDK به طور خودکار عملیات را درست از همان جایی که متوقف شد، مجدداً راه اندازی می کند.
    • همان فایل آپلود شده را می توان چندین بار استفاده کرد بدون اینکه کاربر نهایی مجبور باشد هر بار که نیاز است همان فایل را در برنامه شما آپلود کند (مانند یک درخواست چندوجهی جدید).

  • می‌توانید دسترسی کاربر نهایی را به فایل‌های ذخیره‌شده در Cloud Storage for Firebase با استفاده از Firebase Security Rules محدود کنید، که فقط به یک کاربر مجاز اجازه آپلود، دانلود یا حذف فایل‌ها را می‌دهد.

  • می‌توانید از Firebase یا Google Cloud به فایل‌های موجود در سطل خود دسترسی داشته باشید، که به شما این امکان را می‌دهد تا پردازش سمت سرور مانند فیلتر کردن تصویر یا رمزگذاری ویدیو را با استفاده از APIهای Google Cloud Storage انجام دهید.

چه نوع فایل ها و URL هایی پشتیبانی می شوند؟

هنگامی که می‌خواهید از Cloud Storage for Firebase با Vertex AI in Firebase SDK استفاده کنید، شرایط لازم برای فایل‌ها و URLها در اینجا آمده است:

  • هنگام استفاده از Vertex AI in Firebase SDK، فایل باید الزامات فایل های ورودی برای درخواست های چندوجهی را برآورده کند. این شامل الزاماتی مانند نوع MIME و اندازه فایل است.

  • فایل باید در یک سطل Cloud Storage for Firebase ذخیره شود (به این معنی که سطل برای سرویس‌های Firebase قابل دسترسی است، مانند Firebase Security Rules ). اگر می‌توانید سطل خود را در کنسول Firebase مشاهده کنید، پس این یک سطل Cloud Storage for Firebase است.

  • سطل Cloud Storage for Firebase باید در همان پروژه Firebase باشد که برنامه خود را در آن ثبت کرده اید.

  • Cloud Storage for Firebase باید با gs:// شروع شود، این روشی است که همه URL‌های Google Cloud Storage ساخته می‌شوند.

  • URL فایل نمی تواند یک URL "مرورگر" باشد (به عنوان مثال، URL تصویری که در اینترنت پیدا می کنید).

همچنین، Firebase Security Rules برای سطل شما باید اجازه دسترسی مناسب به فایل را بدهد. به عنوان مثال:

  • اگر قوانین عمومی دارید، هر کاربر یا مشتری می‌تواند به فایل دسترسی داشته باشد و URL آن را در یک تماس با استفاده از Vertex AI in Firebase SDK ارائه کند. این نوع قوانین فقط باید برای شروع و در طول نمونه سازی اولیه مورد استفاده قرار گیرند (مگر اینکه فایل ها واقعاً فایل های کاملاً در دسترس عموم باشند).

  • اگر قوانین محکمی دارید (اکیداً توصیه می‌شود) ، Firebase قبل از اجازه دادن به تماس با URL ارائه‌شده، بررسی می‌کند که کاربر یا مشتری واردشده به فایل دسترسی کافی به فایل داشته باشد.

از Cloud Storage for Firebase با Vertex AI in Firebase استفاده کنید

مرحله ۱ : Cloud Storage for Firebase تنظیم کنید

می‌توانید دستورالعمل‌های دقیق برای راه‌اندازی و استفاده از Cloud Storage for Firebase در راهنمای شروع آن بیابید.

به راهنمای شروع به کار به Cloud Storage for Firebase بروید

در اینجا وظایف سطح بالایی که باید انجام دهید آورده شده است:

  1. در پروژه Firebase خود یک Cloud Storage for Firebase ایجاد کنید.

    اگر قبلاً یک سطل Cloud Storage در پروژه Google Cloud خود دارید که می‌خواهید با Vertex AI in Firebase استفاده کنید، می‌توانید با «وارد کردن» سطل به Firebase ، آن را برای سرویس‌های Firebase (از جمله Vertex AI in Firebase ) در دسترس قرار دهید.

  2. Firebase Security Rules در این سطل اعمال کنید. Firebase Security Rules به شما کمک می کند تا با محدود کردن دسترسی به کاربران نهایی مجاز، فایل های خود را ایمن کنید.

  3. کتابخانه سرویس گیرنده Cloud Storage for Firebase را به برنامه خود اضافه کنید.

    توجه داشته باشید که می‌توانید از این کار صرف‌نظر کنید، اما باید همیشه مقدار MIME و Cloud Storage for Firebase URL را به صراحت در درخواست‌های چندوجهی خود بگنجانید .

مرحله 2 : یک فایل را در یک سطل آپلود کنید

در مستندات Cloud Storage for Firebase ، می‌توانید تمام روش‌های مختلف آپلود فایل‌ها را در سطل Cloud Storage for Firebase بیاموزید. برای مثال، می‌توانید فایل‌های محلی را از دستگاه کاربر نهایی آپلود کنید، مانند عکس‌ها و ویدیوها از دوربین.

هنگامی که یک فایل را در یک سطل آپلود می کنید، Cloud Storage به طور خودکار دو قسمت از اطلاعات زیر را روی فایل اعمال می کند. شما باید این مقادیر را در درخواست چندوجهی بگنجانید (همانطور که در مرحله بعدی این راهنما نشان داده شده است).

  • نوع MIME : این نوع رسانه فایل است (به عنوان مثال، image/png ). Cloud Storage for Firebase به طور خودکار سعی می‌کند نوع MIME را در حین آپلود شناسایی کند و آن ابرداده را در شیء موجود در سطل اعمال کند. با این حال، می توانید به صورت اختیاری نوع MIME را در حین آپلود مشخص کنید.

  • Cloud Storage for Firebase URL : این یک شناسه منحصر به فرد برای فایل است. URL باید با gs:// شروع شود.

مرحله 3 : نوع MIME و URL فایل را در یک درخواست چندوجهی وارد کنید

هنگامی که فایلی را در یک سطل Cloud Storage for Firebase ذخیره کردید، می توانید نوع MIME و Cloud Storage for Firebase را در یک درخواست چندوجهی قرار دهید. توجه داشته باشید که این مثال‌ها یک درخواست generateContent غیر جریانی را نشان می‌دهند، اما می‌توانید Cloud Storage for Firebase با پخش جریانی و چت نیز استفاده کنید.

برای قرار دادن فایل در درخواست، می توانید از یکی از گزینه های زیر استفاده کنید:

گزینه 1: نوع MIME و URL را با استفاده از مرجع ذخیره سازی وارد کنید

اگر به تازگی فایل را در سطل آپلود کرده اید، و می خواهید بلافاصله فایل را (از طریق مرجع ذخیره سازی) در درخواست چندوجهی قرار دهید، از این گزینه استفاده کنید. تماس به نوع MIME و Cloud Storage for Firebase نیاز دارد.

Kotlin+KTX

برای Kotlin، روش‌های موجود در این SDK توابع تعلیق هستند و باید از یک محدوده 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

برای جاوا، روش‌های موجود در این 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 و Cloud Storage for Firebase را می‌دانید و می‌خواهید آنها را به صراحت در درخواست چندوجهی لحاظ کنید، از این گزینه استفاده کنید. تماس به نوع MIME و URL نیاز دارد.

Kotlin+KTX

برای Kotlin، روش‌های موجود در این SDK توابع تعلیق هستند و باید از یک محدوده 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

برای جاوا، روش‌های موجود در این 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);