Membangun pengalaman hybrid di aplikasi Android dengan model yang dihosting di perangkat dan cloud


Anda dapat membuat aplikasi dan fitur Android yang didukung AI dengan inferensi hibrida menggunakan Firebase AI Logic. Inferensi hybrid memungkinkan menjalankan inferensi menggunakan model di perangkat jika tersedia dan melakukan penggantian ke model yang dihosting di cloud jika tidak tersedia (dan sebaliknya).

Halaman ini menjelaskan cara memulai penggunaan SDK klien, serta menunjukkan opsi dan kemampuan konfigurasi tambahan, seperti suhu.

Perhatikan bahwa inferensi di perangkat melalui Firebase AI Logic didukung untuk aplikasi Android yang berjalan di perangkat tertentu dan diatur oleh persyaratan ML Kit, serta persyaratan khusus untuk aspek AI Generatif ML Kit.

Kasus penggunaan yang direkomendasikan dan kemampuan yang didukung

Kasus penggunaan yang direkomendasikan

  • Penggunaan model di perangkat untuk inferensi menawarkan:

    • Privasi yang ditingkatkan
    • Konteks lokal
    • Inferensi tanpa biaya
    • Fungsi offline

  • Menggunakan penawaran fungsi hybrid:

    • Jangkau lebih banyak audiens dengan mengakomodasi ketersediaan model di perangkat dan konektivitas internet

Kemampuan dan fitur yang didukung untuk inferensi di perangkat

Inferensi di perangkat hanya mendukung pembuatan teks sekali putaran (bukan chat), dengan output streaming atau non-streaming. Model ini mendukung kemampuan pembuatan teks berikut:

Pastikan untuk meninjau daftar fitur yang belum tersedia untuk inferensi di perangkat di bagian bawah halaman ini.

Sebelum memulai

Perhatikan hal berikut ini:

Perangkat Android yang didukung dan model di perangkatnya

Untuk inferensi di perangkat (yang menggunakan Prompt API ML Kit), Anda dapat menemukan daftar perangkat yang didukung dan model di perangkatnya dalam dokumentasi ML Kit.

Mulai

Langkah-langkah memulai ini menjelaskan penyiapan umum yang diperlukan untuk setiap permintaan perintah yang didukung yang ingin Anda kirim.

Langkah 1: Siapkan project Firebase dan hubungkan aplikasi Anda ke Firebase

  1. Login ke konsol Firebase, lalu pilih project Firebase Anda.

  2. Di konsol Firebase, buka halaman Firebase AI Logic.

  3. Klik Mulai untuk meluncurkan alur kerja terpandu yang membantu Anda menyiapkan API dan resource yang diperlukan untuk project Anda.

  4. Siapkan project Anda untuk menggunakan penyedia "Gemini API".

    Sebaiknya mulai menggunakan Gemini Developer API. Kapan saja, Anda dapat menyiapkan Vertex AI Gemini API (dan persyaratan penagihannya).

    Untuk Gemini Developer API, konsol akan mengaktifkan API yang diperlukan dan membuat kunci API Gemini di project Anda.
    Jangan menambahkan kunci API Gemini ini ke codebase aplikasi Anda. Pelajari lebih lanjut.

  5. Jika diminta dalam alur kerja konsol, ikuti petunjuk di layar untuk mendaftarkan aplikasi dan menghubungkannya ke Firebase.

  6. Lanjutkan ke langkah berikutnya dalam panduan ini untuk menambahkan SDK ke aplikasi Anda.

Langkah 2: Tambahkan SDK yang diperlukan

Firebase AI Logic SDK for Android (firebase-ai) bersama dengan Firebase AI Logic On-Device SDK (firebase-ai-ondevice) memberikan akses ke API untuk berinteraksi dengan model generatif.

Dalam file Gradle modul (level aplikasi) (seperti <project>/<app-module>/build.gradle.kts), tambahkan dependensi untuk library Firebase AI Logic untuk Android:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.10.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")
}

Java

Untuk Java, Anda perlu menambahkan dua library tambahan.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:17.10.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta01")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

Langkah 3: Periksa apakah model di perangkat tersedia

Dengan menggunakan FirebaseAIOnDevice, periksa apakah model di perangkat tersedia, dan download model jika tidak tersedia.

Setelah didownload, AICore akan otomatis memperbarui model. Lihat catatan setelah cuplikan untuk mengetahui detail selengkapnya tentang AICore dan mengelola download model di perangkat.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for and downloading the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

Perhatikan hal-hal berikut tentang mendownload model di perangkat:

  • Waktu yang diperlukan untuk mendownload model di perangkat bergantung pada banyak faktor, termasuk jaringan Anda.

  • Jika kode Anda menggunakan model di perangkat untuk inferensi utama atau penggantiannya, pastikan model didownload lebih awal dalam siklus proses aplikasi Anda sehingga model di perangkat tersedia sebelum pengguna akhir Anda menemukan kode di aplikasi Anda.

  • Jika model di perangkat tidak tersedia saat permintaan inferensi di perangkat dibuat, SDK tidak akan otomatis memicu download model di perangkat. SDK akan melakukan penggantian ke model yang dihosting di cloud atau mengecualikan (lihat detail tentang perilaku mode inferensi).

  • AICore (layanan sistem Android) mengelola model dan versi yang didownload, memperbarui model, dll. Perhatikan bahwa perangkat hanya akan mendownload satu model, jadi jika aplikasi lain di perangkat sebelumnya berhasil mendownload model di perangkat, pemeriksaan ini akan menampilkan bahwa model tersedia.

Pengoptimalan latensi

Untuk mengoptimalkan panggilan inferensi pertama, Anda dapat membuat aplikasi Anda memanggil warmup(). Tindakan ini memuat model di perangkat ke dalam memori dan menginisialisasi komponen runtime.

Langkah 4: Inisialisasi layanan dan buat instance model

Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini.

Siapkan hal berikut sebelum Anda mengirim permintaan perintah ke model.

  1. Lakukan inisialisasi layanan untuk penyedia API yang Anda pilih.

  2. Buat instance GenerativeModel, dan tetapkan mode ke salah satu berikut. Deskripsi di sini sangat umum, tetapi Anda dapat mempelajari detail tentang perilaku mode ini di Menetapkan mode inferensi.

    • PREFER_ON_DEVICE: Berupaya menggunakan model di perangkat; jika tidak, kembali ke model yang dihosting di cloud.

    • ONLY_ON_DEVICE: Berupaya menggunakan model di perangkat; jika tidak, lempar pengecualian.

    • PREFER_IN_CLOUD: Berupaya menggunakan model yang dihosting di cloud; jika tidak, kembali ke model di perangkat.

    • ONLY_IN_CLOUD: Berupaya menggunakan model yang dihosting di cloud; jika tidak, tampilkan pengecualian.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Langkah 5: Kirim permintaan perintah ke model

Bagian ini menunjukkan cara mengirim berbagai jenis input untuk menghasilkan berbagai jenis output, termasuk:

Membuat teks dari input khusus teks

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan bagian Mulai dalam panduan ini.

Anda dapat menggunakan generateContent() untuk membuat teks dari perintah yang berisi teks:

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Perhatikan bahwa Firebase AI Logic juga mendukung streaming respons teks menggunakan generateContentStream (bukan generateContent).

Membuat teks dari input teks dan gambar (multimodal)

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan bagian Mulai dalam panduan ini.

Anda dapat menggunakan generateContent() untuk membuat teks dari perintah yang berisi teks dan hingga satu file gambar (Bitmap saja) — dengan memberikan mimeType setiap file input dan file itu sendiri.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Perhatikan bahwa Firebase AI Logic juga mendukung streaming respons teks menggunakan generateContentStream (bukan generateContent).

Kamu bisa apa lagi?

Anda dapat menggunakan berbagai opsi dan kemampuan konfigurasi tambahan untuk pengalaman hibrida:

Fitur yang belum tersedia untuk inferensi di perangkat

Sebagai rilis eksperimental, tidak semua kemampuan model cloud tersedia untuk inferensi di perangkat.

Fitur yang tercantum di bagian ini belum tersedia untuk inferensi di perangkat. Jika Anda ingin menggunakan salah satu fitur ini, sebaiknya gunakan mode inferensi ONLY_IN_CLOUD untuk pengalaman yang lebih konsisten.

  • Membuat output terstruktur (seperti JSON atau enum)

  • Membuat teks dari jenis input file gambar selain Bitmap (gambar dimuat ke dalam memori)

  • Membuat teks dari lebih dari satu file gambar

  • Membuat teks dari input audio, video, dan dokumen (seperti PDF)

  • Membuat gambar menggunakan model Gemini atau Imagen

  • Menyediakan file menggunakan URL dalam permintaan multimodal. Anda harus menyediakan file sebagai data inline untuk model di perangkat

  • Mengirim permintaan yang melebihi 4.000 token (atau sekitar 3.000 kata dalam bahasa Inggris).

  • Multi-turn chat

  • Memberikan alat kepada model untuk membantunya membuat respons (seperti pemanggilan fungsi, eksekusi kode, konteks URL, dan perujukan dengan Google Penelusuran)

Pemantauan AI di konsol Firebase tidak menampilkan data apa pun untuk inferensi di perangkat (termasuk log di perangkat). Namun, inferensi apa pun yang menggunakan model yang dihosting di cloud dapat dipantau seperti inferensi lainnya melalui Firebase AI Logic.

Batasan tambahan

Selain hal di atas, inferensi di perangkat memiliki batasan berikut (pelajari lebih lanjut di dokumentasi ML Kit):

  • Pengguna akhir aplikasi Anda harus menggunakan perangkat yang didukung untuk inferensi di perangkat.

  • Aplikasi Anda hanya dapat menjalankan inferensi di perangkat saat berada di latar depan.

  • Hanya bahasa Inggris dan Korea yang telah divalidasi untuk inferensi di perangkat.

  • Batas token maksimum untuk seluruh permintaan inferensi di perangkat adalah 4.000 token. Jika permintaan Anda mungkin melebihi batas ini, pastikan untuk mengonfigurasi mode inferensi yang dapat menggunakan model yang dihosting di cloud.

  • Sebaiknya hindari kasus penggunaan inferensi di perangkat yang memerlukan output panjang (lebih dari 256 token).

  • AICore (layanan sistem Android yang mengelola model di perangkat) menerapkan kuota inferensi per aplikasi. Membuat terlalu banyak permintaan API dalam waktu singkat akan menghasilkan respons ErrorCode.BUSY. Jika Anda menerima error ini, pertimbangkan untuk menggunakan backoff eksponensial untuk mencoba lagi permintaan. Selain itu, ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED dapat ditampilkan jika aplikasi melebihi kuota durasi panjang (misalnya, kuota harian).


Memberikan masukan tentang pengalaman Anda menggunakan Firebase AI Logic