Menyertakan file besar dalam permintaan multimodal dan mengelola file menggunakan Cloud Storage for Firebase

Hanya tersedia saat menggunakan Vertex AI Gemini API sebagai penyedia API Anda.

Saat memanggil Vertex AI Gemini API dari aplikasi Anda menggunakan SDK Firebase AI Logic, Anda dapat meminta model Gemini untuk membuat teks berdasarkan input multimodal, seperti gambar, PDF, video, dan audio.

Untuk bagian input non-teks (seperti file media), Anda dapat secara opsional menggunakan Cloud Storage for Firebase untuk menyertakan file dalam permintaan. Secara umum, berikut hal-hal yang perlu Anda ketahui tentang fitur ini:

  • Anda dapat menggunakan Cloud Storage for Firebase dengan permintaan multimodal apa pun (seperti pembuatan teks dan chat) jika Anda menggunakan Vertex AI Gemini API. Contoh dalam panduan ini menunjukkan input teks dan gambar dasar.

  • Anda menentukan jenis MIME file dan URL Cloud Storage for Firebase-nya (yang selalu dimulai dengan gs://) dalam input permintaan. Nilai ini adalah metadata yang otomatis ditetapkan ke file apa pun yang diupload ke bucket Cloud Storage.

  • Anda harus menggunakan jenis file dan URL yang didukung.


Panduan solusi ini menjelaskan cara menyiapkan Cloud Storage for Firebase, mengupload file ke bucket Cloud Storage for Firebase dari aplikasi Anda, lalu menyertakan jenis MIME dan URL Cloud Storage for Firebase file dalam permintaan multimodal Anda ke Gemini API.

Ingin melihat contoh kode? Atau, apakah Anda sudah menyiapkan Cloud Storage for Firebase dan siap menggunakannya dengan permintaan multimodal Anda?

Langsung ke contoh kode

Mengapa menggunakan Cloud Storage for Firebase dengan aplikasi Anda?

Cloud Storage for Firebase menggunakan infrastruktur yang sama cepat, aman, dan skalabelnya dengan Google Cloud Storage untuk menyimpan blob dan file, dan SDK kliennya dibuat khusus untuk aplikasi seluler dan web.

Untuk SDK Firebase AI Logic, ukuran permintaan maksimum adalah 20 MB. Anda akan mendapatkan error HTTP 413 jika permintaan terlalu besar. Jika ukuran file akan membuat ukuran total permintaan melebihi 20 MB, gunakan URL Cloud Storage for Firebase untuk menyertakan file dalam permintaan multimodal Anda. Namun, jika file berukuran kecil, Anda sering kali dapat meneruskannya secara langsung sebagai data inline (namun, perhatikan bahwa file yang diberikan sebagai data inline dienkode ke base64 dalam transit, yang meningkatkan ukuran permintaan).

Berikut beberapa manfaat tambahan menggunakan Cloud Storage for Firebase:

  • Anda dapat meminta pengguna akhir mengupload gambar langsung dari aplikasi Anda ke bucket Cloud Storage for Firebase, lalu Anda dapat menyertakan gambar tersebut dalam perintah multimodal hanya dengan menentukan jenis MIME file dan URL Cloud Storage for Firebase (yang merupakan ID untuk file).

  • Anda dapat menghemat waktu dan bandwidth pengguna akhir jika mereka perlu memberikan gambar, terutama jika mereka memiliki kualitas jaringan yang buruk atau tidak stabil.

    • Jika upload atau download file terganggu, SDK Cloud Storage for Firebase akan otomatis memulai ulang operasi tepat di posisi terakhirnya.
    • File yang sama yang diupload dapat digunakan beberapa kali tanpa pengguna akhir harus mengupload file yang sama setiap kali diperlukan di aplikasi Anda (seperti dalam permintaan multimodal baru).
  • Anda dapat membatasi akses pengguna akhir ke file yang disimpan di Cloud Storage for Firebase dengan menggunakan Firebase Security Rules, yang hanya mengizinkan pengguna yang diberi otorisasi untuk mengupload, mendownload, atau menghapus file.

  • Anda dapat mengakses file di bucket dari Firebase atau dari Google Cloud, sehingga Anda dapat melakukan pemrosesan sisi server seperti pemfilteran gambar atau transcoding video menggunakan Google Cloud Storage API.

Jenis file dan URL apa yang didukung?

Berikut persyaratan untuk file dan URL saat Anda ingin menggunakan URL Cloud Storage for Firebase dengan SDK Firebase AI Logic:

  • File harus memenuhi persyaratan file input untuk permintaan multimodal. Hal ini mencakup persyaratan seperti jenis MIME dan ukuran file.

  • File harus disimpan di bucket Cloud Storage for Firebase (yang berarti bucket dapat diakses oleh layanan Firebase, seperti Firebase Security Rules). Jika Anda dapat melihat bucket di Firebase console, maka bucket tersebut adalah bucket Cloud Storage for Firebase.

  • Bucket Cloud Storage for Firebase harus berada di project Firebase yang sama dengan tempat Anda mendaftarkan aplikasi.

  • URL Cloud Storage for Firebase file harus dimulai dengan gs://, yang merupakan cara semua URL Google Cloud Storage dibuat.

  • URL file tidak boleh berupa URL "browser" (misalnya, URL gambar yang Anda temukan di internet).

Selain itu, Firebase Security Rules untuk bucket Anda harus mengizinkan akses yang sesuai ke file. Contoh:

  • Jika Anda memiliki aturan publik, maka pengguna atau klien mana pun dapat mengakses file.

  • Jika Anda memiliki aturan yang kuat (sangat direkomendasikan), Firebase akan memeriksa apakah pengguna atau klien yang login memiliki akses yang memadai ke file sebelum mengizinkan panggilan dilakukan dengan URL yang diberikan.

Menggunakan URL Cloud Storage for Firebase dengan Firebase AI Logic

Hanya tersedia saat menggunakan Vertex AI Gemini API sebagai penyedia API Anda.

Langkah 1: Siapkan Cloud Storage for Firebase

Anda dapat menemukan petunjuk mendetail untuk menyiapkan Cloud Storage for Firebase di panduan memulainya: iOS+ | Android | Web | Flutter | Unity

Berikut tugas tingkat tinggi yang perlu Anda lakukan:

  1. Buat atau impor bucket Cloud Storage for Firebase di project Firebase Anda.

  2. Terapkan Firebase Security Rules ke bucket ini. Rules membantu Anda mengamankan file dengan membatasi akses ke pengguna akhir yang diberi otorisasi.

  3. Tambahkan library klien untuk Cloud Storage for Firebase ke aplikasi Anda.

    Perhatikan bahwa Anda dapat melewati tugas ini, tetapi Anda harus selalu menyertakan nilai jenis MIME dan URL secara eksplisit dalam permintaan Anda.

Langkah 2: Upload file ke bucket

Dalam dokumentasi Cloud Storage, Anda dapat mempelajari semua cara berbeda untuk mengupload file ke bucket. Misalnya, Anda dapat mengupload file lokal dari perangkat pengguna akhir, seperti foto dan video dari kamera. Pelajari lebih lanjut: iOS+ | Android | Web | Flutter | Unity

Saat Anda mengupload file ke bucket, Cloud Storage akan otomatis menerapkan dua informasi berikut ke file. Anda harus menyertakan nilai ini dalam permintaan (seperti yang ditunjukkan pada langkah berikutnya dalam panduan ini).

  • Jenis MIME: Ini adalah jenis media file (misalnya, image/png). Kami akan otomatis mencoba mendeteksi jenis MIME selama upload dan menerapkan metadata tersebut ke objek dalam bucket. Namun, Anda dapat menentukan jenis MIME secara opsional selama upload.

  • URL Cloud Storage for Firebase: Ini adalah ID unik untuk file. URL harus diawali dengan gs://.

Langkah 3: Sertakan jenis MIME dan URL file dalam permintaan multimodal

Setelah menyimpan file di bucket, Anda dapat menyertakan jenis MIME dan URL-nya dalam permintaan. Perhatikan bahwa contoh ini menunjukkan permintaan generateContent non-streaming, tetapi Anda juga dapat menggunakan URL dengan streaming dan chat.

Untuk menyertakan file dalam permintaan, Anda dapat menggunakan salah satu opsi berikut:

Opsi 1: Sertakan jenis MIME dan URL menggunakan referensi Penyimpanan

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan panduan memulai untuk SDK Firebase AI Logic.

Gunakan opsi ini jika Anda baru saja mengupload file ke bucket, dan Anda ingin segera menyertakan file (melalui referensi Storage) dalam permintaan. Panggilan memerlukan jenis MIME dan URL 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

Untuk Kotlin, metode dalam SDK ini adalah fungsi penangguhan dan perlu dipanggil dari cakupan 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

Untuk Java, metode dalam SDK ini menampilkan 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.");

Opsi 2: Sertakan jenis MIME dan URL secara eksplisit

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan panduan memulai untuk SDK Firebase AI Logic.

Gunakan opsi ini jika Anda mengetahui nilai untuk jenis MIME dan URL Cloud Storage for Firebase, dan Anda ingin menyertakannya secara eksplisit dalam permintaan multimodal. Panggilan memerlukan jenis MIME dan URL.

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

Untuk Kotlin, metode dalam SDK ini adalah fungsi penangguhan dan perlu dipanggil dari cakupan 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

Untuk Java, metode dalam SDK ini menampilkan 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.");