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

فقط زمانی در دسترس است که از Vertex AI Gemini API به عنوان ارائه دهنده API خود استفاده کنید.

هنگام فراخوانی API مربوط به Vertex AI Gemini از برنامه خود با استفاده از Firebase AI Logic SDK، می‌توانید مدل Gemini را وادار کنید تا بر اساس ورودی‌های چندوجهی مانند تصاویر، فایل‌های PDF، ویدیو و صدا، متن تولید کند.

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

  • اگر از API مربوط به Vertex AI Gemini استفاده می‌کنید، می‌توانید 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 در درخواست چندوجهی شما به API جمینی را شرح می‌دهد.

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

پرش به مثال‌های کد

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

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

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

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

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

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

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

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

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

چه نوع فایل‌ها و آدرس‌های اینترنتی پشتیبانی می‌شوند؟

الزامات مربوط به فایل‌ها و URLها هنگام استفاده از Cloud Storage for Firebase با SDKهای Firebase AI Logic به شرح زیر است:

  • این فایل باید الزامات فایل‌های ورودی برای درخواست‌های چندوجهی را برآورده کند. این شامل الزاماتی مانند نوع MIME و اندازه فایل می‌شود.

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

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

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

  • آدرس اینترنتی فایل نمی‌تواند یک آدرس اینترنتی «مرورگر» باشد (برای مثال، آدرس اینترنتی تصویری که در اینترنت پیدا می‌کنید).

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

  • اگر قوانین عمومی دارید، هر کاربر یا کلاینتی می‌تواند به فایل دسترسی داشته باشد.

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

استفاده از Cloud Storage for Firebase با منطق هوش مصنوعی فایربیس

فقط زمانی در دسترس است که از Vertex AI Gemini API به عنوان ارائه دهنده API خود استفاده کنید.

مرحله 1 : تنظیم Cloud Storage for Firebase

می‌توانید دستورالعمل‌های دقیق برای راه‌اندازی Cloud Storage for Firebase در راهنمای شروع به کار آن بیابید: iOS+ | اندروید | وب | فلاتر | یونیتی

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

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

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

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

    توجه داشته باشید که می‌توانید از این کار صرف نظر کنید، اما در این صورت همیشه باید نوع MIME و مقادیر URL را به صراحت در درخواست‌های خود وارد کنید .

مرحله 2 : یک فایل را در یک سطل بارگذاری کنید

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

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

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

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

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

وقتی فایلی را در یک باکت ذخیره کردید، می‌توانید نوع MIME و URL آن را در یک درخواست وارد کنید. توجه داشته باشید که این مثال‌ها یک درخواست generateContent غیر استریمینگ را نشان می‌دهند، اما می‌توانید از URLهایی با استریمینگ و چت نیز استفاده کنید.

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

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

قبل از امتحان کردن این مثال، مطمئن شوید که راهنمای شروع به کار با Firebase AI Logic SDK ها را تکمیل کرده‌اید.

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

سویفت 

// Upload an image file using Cloud Storage for Firebase.
let storageRef = Storage.storage().reference(withPath: "images/image.jpg")
guard let imageURL = Bundle.main.url(forResource: "image", withExtension: "jpg") else {
  fatalError("File 'image.jpg' not found in main bundle.")
}
let metadata = try await storageRef.putFileAsync(from: imageURL)

// Get the MIME type and Cloud Storage for Firebase URL.
guard let mimeType = metadata.contentType else {
  fatalError("The MIME type of the uploaded image is nil.")
}
// Construct a URL in the required format.
let storageURL = "gs://\(storageRef.bucket)/\(storageRef.fullPath)"

let prompt = "What's in this picture?"
// Construct the imagePart with the MIME type and the URL.
let imagePart = FileDataPart(uri: storageURL, mimeType: mimeType)

// To generate text output, call generateContent with the prompt and the imagePart.
let result = try await model.generateContent(prompt, imagePart)
if let text = result.text {
  print(text)
}

Kotlin

برای کاتلین، متدهای موجود در این SDK توابع suspend هستند و باید از یک scope کوروتین فراخوانی شوند. 
// 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 = model.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();
});

Web 

// Upload an image file using Cloud Storage for Firebase.
const storageRef = ref(storage, "image.jpg");
const uploadResult = await uploadBytes(storageRef, file);

// Get the MIME type and Cloud Storage for Firebase URL.
// toString() is the simplest way to construct the Cloud Storage for Firebase URL
// in the required format.
const mimeType = uploadResult.metadata.contentType;
const storageUrl = uploadResult.ref.toString();

// Construct the imagePart with the MIME type and the URL.
const imagePart = { fileData: { mimeType, fileUri: storageUrl }};

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

Dart 

// Upload an image file using Cloud Storage for Firebase.
final storageRef = FirebaseStorage.instance.ref();
final imageRef = storageRef.child("images/image.jpg");
await imageRef.putData(data);

// Get the MIME type and Cloud Storage for Firebase file path.
final metadata = await imageRef.getMetadata();
final mimeType = metadata.contentType;
final bucket = imageRef.bucket;
final fullPath = imageRef.fullPath;

final prompt = TextPart("What's in the picture?");
// Construct a URL in the required format.
final storageUrl = 'gs://$bucket/$fullPath';
// Construct the filePart with the MIME type and the URL.
final filePart = FileData(mimeType, storageUrl);
// To generate text output, call generateContent with the text and the filePart.
final response = await model.generateContent([
  Content.multi([prompt, filePart])
]);
print(response.text);

وحدت 

var storageRef = FirebaseStorage.DefaultInstance.GetReference("images/image.jpg");
var metadata = await storageRef.PutFileAsync(filePathToJpg);

// Get the MIME type and Cloud Storage for Firebase URL.
var mimeType = metadata.ContentType;
// Construct a URL in the required format.
var storageURL = new Uri($"gs://{storageRef.Bucket}/{storageRef.Path}");

var prompt = ModelContent.Text("What's in this picture?");
// Construct a FileData that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
var fileData = ModelContent.FileData(mimeType, storageURL);

// To generate text output, call GenerateContentAsync with the prompt and fileData.
var response = await model.GenerateContentAsync(new [] { prompt, fileData });
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

گزینه ۲: نوع MIME و URL را به طور صریح وارد کنید

قبل از امتحان کردن این مثال، مطمئن شوید که راهنمای شروع به کار با Firebase AI Logic SDK ها را تکمیل کرده‌اید.

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

سویفت 

let prompt = "What's in this picture?"
// Construct an imagePart that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
let imagePart = FileDataPart(uri: "gs://bucket-name/path/image.jpg", mimeType: "image/jpeg")

// To generate text output, call generateContent with the prompt and imagePart.
let result = try await model.generateContent(prompt, imagePart)
if let text = result.text {
  print(text)
}

Kotlin

برای کاتلین، متدهای موجود در این SDK توابع suspend هستند و باید از یک scope کوروتین فراخوانی شوند. 
// 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 = model.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);

Web 

const prompt = "What's in this picture?";
// Construct an imagePart that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
const imagePart = { fileData: { mimeType: "image/jpeg", fileUri: "gs://bucket-name/path/image.jpg" }};

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

Dart 

final prompt = TextPart("What's in the picture?");
// Construct a filePart that explicitly includes the MIME type and Cloud Storage for Firebase URL values.
final filePart = FileData('image/jpeg', 'gs://bucket-name/path/image.jpg'),
// To generate text output, call generateContent with the prompt and filePart.
final response = await model.generateContent([
  Content.multi([prompt, filePart])
]);
print(response.text);

وحدت 

var prompt = ModelContent.Text("What's in this picture?");
// Construct a FileData that explicitly includes the MIME type and
// Cloud Storage for Firebase URL values.
var fileData = ModelContent.FileData(
  mimeType: "image/jpeg",
  uri: new Uri("gs://bucket-name/path/image.jpg")
);

// To generate text output, call GenerateContentAsync with the prompt and fileData.
var response = await model.GenerateContentAsync(new [] { prompt, fileData });
UnityEngine.Debug.Log(response.Text ?? "No text in response.");