فایل‌های بزرگ را در درخواست‌های چندوجهی بگنجانید و فایل‌ها را بااستفاده از «فضای ذخیره‌سازی ابری ویژه Firebase» مدیریت کنید

فقط هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI) به‌عنوان ارائه‌دهنده میانای برنامه‌سازی کاربردی دردسترس است.

وقتی بااستفاده از کیت توسعه نرم‌افزار Firebase AI Logic از برنامه‌تان با Agent Platform Gemini API (formerly Vertex AI) تماس می‌گیرید، می‌توانید مدل Gemini را وادار کنید تا براساس ورودی چندوجهی، مثل تصاویر، فایل‌های PDF، ویدیو، و صدا، نوشتار تولید کند.

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

  • اگر از Agent Platform Gemini API (formerly Vertex AI) استفاده می‌کنید، می‌توانید از Cloud Storage for Firebase با هر درخواست چندوجهی (مثل تولید نوشتار و گپ) استفاده کنید. مثال‌های این راهنما ورودی پایه نوشتار و تصویر را نشان می‌دهد.

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

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


این راهنمای راه‌حل نحوه راه‌اندازی 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 برای ذخیره کردن فایل‌ها و لکه‌ها استفاده می‌کند، و کیت‌های توسعه نرم‌افزار مشتری آن به‌طور ویژه برای برنامه‌های تلفن همراه و وب ساخته شده است.

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

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

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

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

    • اگر بارگذاری یا بارگیری فایلی قطع شود، Cloud Storage for Firebase «کیت‌های توسعه نرم‌افزار» به‌طور خودکار عملیات را از همان جایی که متوقف شده است ازسر می‌گیرند.
    • از فایل بارگذاری‌شده یکسان می‌توان چندین بار استفاده کرد بدون اینکه کاربر نهایی مجبور باشد هربار که فایل در برنامه شما لازم است (مثلاً در یک درخواست چندوجهی جدید) آن را بارگذاری کند.
  • بااستفاده از Firebase Security Rules می‌توانید دسترسی کاربر نهایی به فایل‌های ذخیره‌شده در Cloud Storage for Firebase را محدود کنید. این ویژگی فقط به کاربر مجاز اجازه می‌دهد فایل‌ها را بارگذاری، بارگیری، یا حذف کند.

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

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

در اینجا الزامات مربوط به فایل‌ها و نشانی‌های وب هنگام استفاده از Cloud Storage for Firebase نشانی وب با Firebase AI Logic کیت توسعه نرم‌افزار آورده شده است:

  • فایل باید با الزامات فایل‌های ورودی برای درخواست‌های چندحالته مطابقت داشته باشد. این شامل الزامات مانند نوع MIME و اندازه فایل می‌شود.

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

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

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

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

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

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

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

استفاده از Cloud Storage for Firebase نشانی وب با Firebase AI Logic

فقط هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI) به‌عنوان ارائه‌دهنده میانای برنامه‌سازی کاربردی دردسترس است.

مرحله ۱: راه‌اندازی Cloud Storage for Firebase

می‌توانید دستورالعمل‌های دقیق را برای راه‌اندازی Cloud Storage for Firebase در راهنمای شروع به کار آن پیدا کنید: iOS+‎ | Android | Web | Flutter | Unity

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

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

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

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

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

مرحله ۲: بارگذاری فایل در یک مخزن

در اسناد Cloud Storage، می‌توانید با همه روش‌های مختلف بارگذاری فایل در یک مخزن آشنا شوید. برای مثال، می‌توانید فایل‌های محلی را از دستگاه کاربر نهایی، مانند عکس‌ها و ویدیوهای دوربین، بارگذاری کنید. بیشتر بدانید: iOS+‎ | Android | Web | Flutter | Unity

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

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

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

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

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

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

گزینه ۱: افزودن نوع MIME و نشانی وب بااستفاده از مرجع «فضای ذخیره‌سازی»

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

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

Swift

// 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

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

برای Java، روش‌های موجود در این کیت توسعه نرم‌افزار 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);

Unity

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 و نشانی وب را به‌طور صریح اضافه کنید

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

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

Swift

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

برای Kotlin، روش‌های موجود در این کیت توسعه نرم‌افزار توابع تعلیق هستند و باید از محدوده 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 = model.generateContent(prompt)
println(response.text)

Java

برای Java، روش‌های موجود در این کیت توسعه نرم‌افزار 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);

Unity

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.");