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

Anda dapat membangun aplikasi dan fitur Android yang didukung AI dengan inferensi hibrid menggunakan Firebase AI Logic. Inferensi hybrid memungkinkan menjalankan inferensi menggunakan model di perangkat jika tersedia dan beralih dengan lancar ke model yang dihosting di cloud jika tidak tersedia (dan sebaliknya).

Halaman ini menjelaskan cara mulai menggunakan SDK klien, serta menunjukkan opsi dan kemampuan konfigurasi tambahan.

Perhatikan bahwa inferensi di perangkat melalui Firebase AI Logic didukung untuk aplikasi Android yang menggunakan Firebase AI Logic SDK v17.10.0+ (BoM v34.10.0+) dan berjalan di perangkat tertentu. API ini 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 satu giliran (bukan chat), dengan output streaming atau non-streaming. Model ini mendukung kemampuan pembuatan teks berikut:

• Membuat teks dari input khusus teks

• Membuat teks dari input teks dan gambar, khususnya satu gambar Bitmap sebagai input

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

Sebelum memulai

Perhatikan hal berikut ini:

• API yang didukung:

  • Inferensi dalam cloud menggunakan penyedia Gemini API pilihan Anda (Gemini Developer API atau Agent Platform Gemini API (formerly Vertex AI)).

  • Inferensi di perangkat menggunakan Prompt API dari ML Kit, yang masih dalam versi beta dan hanya tersedia di perangkat tertentu.

• Halaman ini menjelaskan cara memulai.

  Setelah menyelesaikan penyiapan standar ini, lihat opsi dan kemampuan konfigurasi tambahan.

Perangkat Android yang didukung dan model di perangkatnya

Untuk inferensi di perangkat (yang menggunakan Prompt API dari 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 Firebase console, lalu pilih project Firebase Anda.

   Belum memiliki project Firebase?

   Jika Anda belum memiliki project Firebase, klik tombol untuk membuat project Firebase baru, lalu gunakan salah satu opsi berikut:

   • Opsi 1: Buat project Firebase yang benar-benar baru (dan project Google Cloud yang mendasarinya secara otomatis) dengan memasukkan nama project baru di langkah pertama alur kerja.

   • Opsi 2: "Tambahkan Firebase" ke project Google Cloud yang ada dengan mengklik Add Firebase to Google Cloud project (di bagian bawah halaman). Pada langkah pertama alur kerja, masukkan nama project dari project yang ada, lalu pilih project dari daftar yang ditampilkan.

   Selesaikan langkah-langkah alur kerja di layar yang tersisa untuk membuat project Firebase. Perhatikan bahwa saat diminta, Anda tidak perlu menyiapkan Google Analytics untuk menggunakan SDK Firebase AI Logic.

2. Di Firebase console, buka AI Services > AI Logic.

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

4. Jika diminta, ikuti petunjuk di layar untuk mendaftarkan aplikasi dan menambahkan konfigurasi Firebase ke aplikasi Anda.

5. Saat diminta untuk memilih "Gemini API provider", sebaiknya pilih Gemini Developer API, yang memungkinkan Anda memulai dengan cepat tanpa biaya.

   Kapan pun setelahnya, Anda selalu dapat menyiapkan Agent Platform Gemini API (formerly Vertex AI) (dan persyaratan penagihannya).

6. Lanjutkan alur kerja untuk menyiapkan API yang diperlukan dan layanan terkait untuk Firebase AI Logic.

   Mulai awal Juli 2026, tahap alur kerja ini akan otomatis menerapkan Firebase App Check untuk AI Logic, yang merupakan layanan penting untuk membantu melindungi Gemini API saat diakses langsung dari aplikasi Anda. Sebagai bagian dari memulai (lihat langkah-langkah selanjutnya dalam panduan ini), Anda harus mengonfigurasi penyedia debug App Check untuk pengembangan lokal saat App Check diterapkan.

7. Lanjutkan ke langkah berikutnya dalam panduan ini untuk menambahkan SDK yang diperlukan 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) menyediakan 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 dan App Check untuk Android:

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

  // 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: Konfigurasi penyedia debug App Check untuk pengembangan lokal

Mulai awal Juli 2026, sebagai bagian dari alur kerja penyiapan terpandu untuk AI Logic di konsol, Firebase App Check akan otomatis diterapkan untuk melindungi Gemini API. Untuk pengembangan lokal, Anda perlu mengonfigurasi penyedia debug App Check untuk mengabaikan pengesahan sambil tetap mempertahankan penerapan App Check.

1. Pada build debug, konfigurasi App Check untuk menggunakan factory penyedia debug:

   Kotlin

   Firebase.initialize(context = this)
   Firebase.appCheck.installAppCheckProviderFactory(
       DebugAppCheckProviderFactory.getInstance(),
   )
   

   Java

   FirebaseApp.initializeApp(/*context=*/ this);
   FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
   firebaseAppCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance());
   

2. Dapatkan token debug Anda:

   1. Jalankan aplikasi Anda di emulator atau di perangkat pengujian.

   2. Cari token debug App Check di log Anda. Contoh:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
      in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678
      

   3. Salin token (misalnya, 123a4567-b89c-12d3-e456-789012345678).

3. Daftarkan token debug Anda ke App Check:

   1. Di Firebase console, buka tab Security > App Check > Apps.

   2. Temukan aplikasi Anda, klik menu tambahan (more_vert), lalu pilih Manage debug tokens.

   3. Ikuti petunjuk di layar untuk mendaftarkan token debug Anda.

Untuk mengetahui detail tentang penyedia debug (termasuk cara mendapatkan token debug baru), lihat dokumen App Check resmi.

Langkah 4: 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 terus mengupdate model. Lihat catatan setelah cuplikan untuk mengetahui detail selengkapnya tentang AICore dan mengelola download model di perangkat.

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")
  }
}

Checking for, downloading, and warming up 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 terkait 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 beralih ke model yang dihosting di cloud atau memunculkan pengecualian (lihat detail tentang perilaku mode inferensi).

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

Pengoptimalan latensi

Untuk mengoptimalkan panggilan inferensi pertama, Anda dapat meminta aplikasi memanggil onDeviceExtension?.warmUp() (saat ini hanya tersedia untuk Kotlin). Tindakan ini memuat model di perangkat ke dalam memori dan menginisialisasi komponen runtime.

Langkah 5: Lakukan inisialisasi layanan dan buat instance model

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 opsi 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: Mencoba menggunakan model di perangkat; jika tidak, akan menampilkan pengecualian.

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

   • ONLY_IN_CLOUD: Mencoba menggunakan model yang dihosting di cloud; jika tidak, akan menampilkan pengecualian.

// 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 = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

// 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(
        "CLOUD_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 6: Kirim permintaan perintah ke model

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

• Membuat teks yang dihasilkan dari input khusus teks

• Membuat teks dari input teks dan gambar (multimodal)

Membuat teks dari input khusus teks

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

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

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

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

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

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

• Tetapkan mode inferensi.

• Menentukan apakah inferensi di perangkat atau di cloud digunakan.

• Tentukan model yang akan digunakan.

• Gunakan konfigurasi model untuk mengontrol respons.

• Buat output terstruktur (seperti JSON atau enum).

Fitur yang belum tersedia untuk inferensi di perangkat

Sebagai rilis eksperimental, tidak semua kemampuan model cloud tersedia untuk inferensi di perangkat. Fitur berikut belum tersedia untuk inferensi di perangkat (tetapi biasanya tersedia untuk inferensi berbasis cloud).

• Membuat gambar

  • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan pengecualian.

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

  • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan pengecualian.

• Membuat teks dari input file khusus gambar. Untuk inferensi di perangkat, Anda harus memberikan teks sebagai bagian dari permintaan multimodal.

  • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan pengecualian.

• Membuat teks yang dihasilkan dari lebih dari satu input file gambar

  • Dapat kembali ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan memunculkan pengecualian.

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

  • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan pengecualian.

• Menyediakan file menggunakan URL dalam permintaan multimodal. Untuk inferensi di perangkat, Anda harus memberikan satu gambar sebagai Bitmap.

  • Jika Anda memberikan URL file menggunakan fileData (FileDataPart), URL tersebut dapat kembali ke model yang dihosting di cloud (mode ONLY_ON_DEVICE akan menampilkan pengecualian).
  • Jika Anda menyematkan URL langsung dalam perintah teks, URL tersebut tidak akan otomatis beralih ke model yang dihosting di cloud (URL yang disematkan akan diabaikan oleh model di perangkat).

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

  • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan pengecualian.

• Multi-turn chat

  • Tidak otomatis beralih ke model yang dihosting di cloud (inferensi di perangkat menggabungkan histori perintah menjadi satu perintah teks; karena model di perangkat tidak membedakan peran dan melihat histori sebagai satu pesan, model ini tidak akan seakurat model yang dihosting di cloud).
  • Jika Anda ingin menggunakan multi-turn chat, sebaiknya gunakan mode ONLY_IN_CLOUD.

• Memberi model alat untuk membantunya membuat respons (seperti pemanggilan fungsi, eksekusi kode, konteks URL, Penetapan dengan Google Search, dan Penetapan dengan Google Maps)

  • Tidak otomatis beralih ke model yang dihosting di cloud. Jika Anda ingin menggunakan alat, sebaiknya gunakan mode ONLY_IN_CLOUD.

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 berdurasi panjang (misalnya, kuota harian).

Berikan masukan tentang pengalaman Anda menggunakan Firebase AI Logic