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

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

هنگام فراخوانی Agent Platform Gemini API (formerly Vertex AI) از برنامه‌تان بااستفاده از کیت توسعه نرم‌افزار Firebase AI Logic، می‌توانید از مدل 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 bucket بارگذاری کنند، و سپس می‌توانید آن تصاویر را فقط با مشخص کردن نوع MIME فایل و Cloud Storage for Firebase URL (که شناسه‌ای برای فایل است) در پیام‌واره‌های چندحالته خود بگنجانید.

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

    • اگر بارگذاری یا بارگیری فایل قطع شود، کیت‌های توسعه نرم‌افزار 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 bucket باید در همان پروژه 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) به‌عنوان ارائه‌دهنده API دردسترس است.

مرحله ۱: راه‌اندازی 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 | وب | Flutter | Unity

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

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

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

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

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

پشتیبانی می‌شوند.

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

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

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

اگر به‌تازگی فایل را در bucket بارگذاری کرده‌اید و می‌خواهید بلافاصله فایل را (ازطریق مرجع «فضای ذخیره‌سازی») در درخواست بگنجانید، از این گزینه استفاده کنید. فراخوانی هم به نوع MIME و هم به نشانی وب 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 = { type: "fileData", 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 = { type: "fileData", 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.");