รวมไฟล์ขนาดใหญ่ในคำขอแบบหลายโมดัลและจัดการไฟล์โดยใช้ Cloud Storage for Firebase

ใช้ได้เฉพาะเมื่อใช้ Agent Platform Gemini API (formerly Vertex AI) เป็นผู้ให้บริการ API

เมื่อเรียกใช้ Agent Platform Gemini API (formerly Vertex AI) จากแอปโดยใช้ SDK ของ Firebase AI Logic คุณสามารถแจ้งให้โมเดล Gemini สร้างข้อความที่สร้างขึ้น ตามอินพุตหลายรูปแบบ เช่น รูปภาพ, PDF, วิดีโอ และเสียง

สำหรับส่วนที่ไม่ใช่ข้อความของอินพุต (เช่น ไฟล์สื่อ) คุณสามารถใช้ Cloud Storage for Firebase เพื่อรวมไฟล์ในคำขอได้ (ไม่บังคับ) ข้อมูลที่คุณควรทราบเกี่ยวกับฟีเจอร์นี้โดยคร่าวมีดังนี้

  • คุณใช้ Cloud Storage for Firebase กับคำขอแบบมัลติโมดอลได้ (เช่น ทั้งการสร้างข้อความและการแชท) หากใช้ Agent Platform Gemini API (formerly Vertex AI) ตัวอย่างในคำแนะนำนี้แสดงอินพุตข้อความและรูปภาพพื้นฐาน

  • คุณระบุประเภท MIME ของไฟล์และ Cloud Storage for Firebase URL (ซึ่งขึ้นต้นด้วย gs:// เสมอ) ในอินพุตคำขอ ค่าเหล่านี้คือข้อมูลเมตาที่กำหนดให้กับไฟล์ที่อัปโหลดไปยังที่เก็บข้อมูล Cloud Storage โดยอัตโนมัติ

  • คุณต้องใช้ประเภทไฟล์และ URL ที่รองรับ


คู่มือโซลูชันนี้อธิบายวิธีตั้งค่า Cloud Storage for Firebase อัปโหลดไฟล์ไปยังที่เก็บข้อมูล Cloud Storage for Firebase จากแอปของคุณ จากนั้นระบุประเภท MIME และ URL ของ Cloud Storage for Firebase ในคำขอแบบมัลติโมดอลไปยัง Gemini API

หากต้องการดูตัวอย่างโค้ด หรือคุณตั้งค่า Cloud Storage for Firebaseแล้วและพร้อมที่จะเริ่มใช้กับ คำขอแบบมัลติโมดัล

ข้ามไปยังตัวอย่างโค้ด

เหตุใดจึงควรใช้ Cloud Storage for Firebase กับแอป

Cloud Storage for Firebase ใช้โครงสร้างพื้นฐานที่รวดเร็ว ปลอดภัย และปรับขนาดได้แบบเดียวกับ Google Cloud Storage ในการจัดเก็บ Blob และไฟล์ และ SDK ของไคลเอ็นต์ได้รับการสร้างขึ้นมาโดยเฉพาะสำหรับแอปบนอุปกรณ์เคลื่อนที่และเว็บแอป

สำหรับ SDK Firebase AI Logic ขนาดคำขอสูงสุดคือ 20 MB คุณจะได้รับข้อผิดพลาด HTTP 413 หากคำขอมีขนาดใหญ่เกินไป หากขนาดของไฟล์จะทำให้ขนาดคำขอทั้งหมดเกิน 20 MB ให้ใช้ Cloud Storage for Firebase URL เพื่อรวมไฟล์ไว้ในคำขอแบบมัลติโมดัล อย่างไรก็ตาม หากไฟล์มีขนาดเล็ก คุณมักจะส่งไฟล์เป็นข้อมูลแบบอินไลน์ได้โดยตรง (โปรดทราบว่าระบบจะเข้ารหัสไฟล์ที่ระบุเป็นข้อมูลแบบอินไลน์เป็น base64 ใน ระหว่างการรับส่ง ซึ่งจะเพิ่มขนาดของคำขอ)

ประโยชน์เพิ่มเติมบางส่วนของการใช้ Cloud Storage for Firebase มีดังนี้

  • คุณให้ผู้ใช้ปลายทางอัปโหลดรูปภาพจากแอปไปยัง Cloud Storage for Firebase บัคเก็ตได้โดยตรง จากนั้นคุณก็ใส่รูปภาพเหล่านั้นใน พรอมต์มัลติโมดัลได้เพียงแค่ระบุประเภท MIME ของไฟล์และ Cloud Storage for Firebase URL (ซึ่งเป็นตัวระบุของไฟล์)

  • คุณสามารถประหยัดเวลาและแบนด์วิดท์ของผู้ใช้ปลายทางได้หากผู้ใช้ต้องระบุรูปภาพ โดยเฉพาะอย่างยิ่งหากผู้ใช้มีคุณภาพเครือข่ายไม่ดีหรือไม่เสถียร

    • หากการอัปโหลดหรือดาวน์โหลดไฟล์ถูกขัดจังหวะ Cloud Storage for Firebase SDK จะเริ่มการดำเนินการต่อโดยอัตโนมัติจากจุดที่หยุดไว้
    • คุณสามารถใช้ไฟล์ที่อัปโหลดเดียวกันได้หลายครั้งโดยไม่ต้องให้ผู้ใช้ปลายทาง อัปโหลดไฟล์เดียวกันทุกครั้งที่จำเป็นในแอป (เช่น ในคำขอแบบมัลติโมดัลใหม่)
  • คุณสามารถจำกัดสิทธิ์เข้าถึงไฟล์ที่จัดเก็บไว้ใน Cloud Storage for Firebase ของผู้ใช้ปลายทางได้โดยใช้ Firebase Security Rules ซึ่งจะอนุญาตให้เฉพาะผู้ใช้ที่ได้รับอนุญาตอัปโหลด ดาวน์โหลด หรือลบไฟล์ได้

  • คุณสามารถเข้าถึงไฟล์ในที่เก็บข้อมูลจาก Firebase หรือจาก Google Cloud ซึ่งช่วยให้คุณมีความยืดหยุ่นในการประมวลผลฝั่งเซิร์ฟเวอร์ เช่น การกรองรูปภาพหรือการแปลงรหัสวิดีโอโดยใช้ Google Cloud Storage API

ระบบรองรับไฟล์และ URL ประเภทใดบ้าง

ต่อไปนี้คือข้อกำหนดสำหรับไฟล์และ URL เมื่อคุณต้องการใช้ Cloud Storage for Firebase URL กับ SDKFirebase AI Logic

  • ไฟล์ต้องเป็นไปตามข้อกำหนดของไฟล์อินพุตสำหรับคำขอแบบมัลติโมดัล ซึ่งรวมถึงข้อกำหนดต่างๆ เช่น ประเภท MIME และขนาดไฟล์

  • ไฟล์ต้องจัดเก็บไว้ใน Bucket Cloud Storage for Firebase (ซึ่งหมายความว่าบริการ Firebase เช่น Firebase Security Rules จะเข้าถึง Bucket ได้) หากคุณดู Bucket ใน คอนโซล Firebase ได้ แสดงว่าเป็น Bucket Cloud Storage for Firebase

  • Bucket Cloud Storage for Firebase ต้องอยู่ในโปรเจ็กต์ Firebase เดียวกันกับที่ลงทะเบียนแอป

  • Cloud Storage for Firebase URL ของไฟล์ต้องขึ้นต้นด้วย gs:// ซึ่งเป็นวิธีสร้าง URL ของ Google Cloud Storage ทั้งหมด

  • URL ของไฟล์ต้องไม่ใช่ URL ของ "เบราว์เซอร์" (เช่น URL ของรูปภาพ ที่คุณพบในอินเทอร์เน็ต)

นอกจากนี้ Firebase Security Rules สำหรับที่เก็บข้อมูลของคุณต้องอนุญาต การเข้าถึงไฟล์ที่เหมาะสม เช่น

  • หากคุณมีกฎสาธารณะ ผู้ใช้หรือไคลเอ็นต์ใดก็ได้จะเข้าถึงไฟล์ได้

  • หากคุณมีกฎที่เข้มงวด (ขอแนะนำอย่างยิ่ง) Firebase จะตรวจสอบว่าผู้ใช้หรือ ไคลเอ็นต์ที่ลงชื่อเข้าใช้มีสิทธิ์เข้าถึงไฟล์เพียงพอหรือไม่ก่อนที่จะอนุญาตให้มีการเรียกผ่าน URL ที่ระบุ

ใช้ URL ของ Cloud Storage for Firebase กับ Firebase AI Logic

ใช้ได้เฉพาะเมื่อใช้ Agent Platform Gemini API (formerly Vertex AI) เป็นผู้ให้บริการ API

ขั้นตอนที่ 1: ตั้งค่า Cloud Storage for Firebase

คุณดูวิธีการตั้งค่า Cloud Storage for Firebase โดยละเอียดได้ใน คู่มือเริ่มต้นใช้งาน iOS+ | Android | เว็บ | Flutter | Unity

โดยงานระดับสูงที่คุณจะต้องทำมีดังนี้

  1. สร้างหรือนำเข้าCloud Storage for Firebaseที่เก็บข้อมูลในโปรเจ็กต์ Firebase

  2. ใช้ Firebase Security Rules กับที่เก็บข้อมูลนี้ Security Rules ช่วยรักษาความปลอดภัยของไฟล์โดยจำกัดการเข้าถึงเฉพาะผู้ใช้ที่ได้รับอนุญาต

  3. เพิ่มไลบรารีของไคลเอ็นต์สำหรับ Cloud Storage for Firebase ลงในแอป

    โปรดทราบว่าคุณข้ามงานนี้ได้ แต่ต้องระบุค่าประเภท MIME และ URL ในคำขออย่างชัดเจนเสมอ

ขั้นตอนที่ 2: อัปโหลดไฟล์ไปยังที่เก็บข้อมูล

ในCloud Storageเอกสารประกอบ คุณจะดูวิธีต่างๆ ในการอัปโหลดไฟล์ไปยัง Bucket ได้ เช่น คุณสามารถอัปโหลดไฟล์ในเครื่องจากอุปกรณ์ของผู้ใช้ปลายทาง เช่น รูปภาพและวิดีโอจากกล้อง ดูข้อมูลเพิ่มเติมได้ที่ iOS+ | Android | เว็บ | Flutter | Unity

เมื่ออัปโหลดไฟล์ไปยังที่เก็บข้อมูล Cloud Storage จะใช้ข้อมูล 2 รายการต่อไปนี้กับไฟล์โดยอัตโนมัติ คุณจะต้องระบุค่าเหล่านี้ในคำขอ (ดังที่แสดงในขั้นตอนถัดไปของคู่มือนี้)

  • ประเภท MIME: นี่คือประเภทสื่อของไฟล์ (เช่น image/png) เราจะพยายามตรวจหาประเภท MIME โดยอัตโนมัติในระหว่างการอัปโหลดและใช้ข้อมูลเมตาดังกล่าวกับออบเจ็กต์ในที่เก็บข้อมูล อย่างไรก็ตาม คุณสามารถระบุ ประเภท MIME ในระหว่างการอัปโหลดได้

  • Cloud Storage for Firebase URL: ตัวระบุที่ไม่ซ้ำกันสำหรับไฟล์ URL ต้องขึ้นต้นด้วย gs://

ขั้นตอนที่ 3: ระบุประเภท MIME และ URL ของไฟล์ในคำขอแบบมัลติโมดัล

เมื่อจัดเก็บไฟล์ไว้ในที่เก็บข้อมูลแล้ว คุณจะระบุประเภท MIME และ URL ของไฟล์ในคำขอได้ โปรดทราบว่าตัวอย่างเหล่านี้แสดงgenerateContent คำขอที่ไม่ใช่การสตรีม แต่คุณยังใช้ URL ที่มีการสตรีมและการแชทได้ด้วย

หากต้องการรวมไฟล์ในคำขอ คุณสามารถใช้ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้

ตัวเลือกที่ 1: ระบุประเภท MIME และ URL โดยใช้การอ้างอิงพื้นที่เก็บข้อมูล

ก่อนที่จะลองใช้ตัวอย่างนี้ โปรดตรวจสอบว่าคุณได้ทำตาม คู่มือเริ่มต้นใช้งานสำหรับ Firebase AI Logic SDK แล้ว

ใช้ตัวเลือกนี้หากเพิ่งอัปโหลดไฟล์ไปยังที่เก็บข้อมูล และต้องการรวมไฟล์ (ผ่านการอ้างอิง Storage) ในคำขอทันที การเรียก ต้องใช้ทั้งประเภท MIME และ 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

สำหรับ 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 = 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 เมธอดใน 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);

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

ตัวเลือกที่ 2: ระบุประเภท MIME และ URL อย่างชัดเจน

ก่อนที่จะลองใช้ตัวอย่างนี้ โปรดตรวจสอบว่าคุณได้ทำตาม คู่มือเริ่มต้นใช้งานสำหรับ Firebase AI Logic SDK แล้ว

ใช้ตัวเลือกนี้หากคุณทราบค่าสำหรับประเภท MIME และ Cloud Storage for Firebase URL และต้องการรวมค่าดังกล่าวอย่างชัดเจนใน คำขอแบบมัลติโมดัล การเรียกใช้ต้องมีทั้งประเภท MIME และ 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

สำหรับ 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 = model.generateContent(prompt)
println(response.text)

Java

สําหรับ 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);

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