Cara Menggunakan Gemini Nano di Aplikasi Capacitor

Untuk menggunakan Gemini Nano di aplikasi Capacitor, instal @capgo/capacitor-llm, panggil setModel({ path: 'Gemini Nano' }) di Android, lalu buat chat dan stream balasan melalui textFromAi event. Plugin ini berkomunikasi dengan Gemini Nano melalui Google’s ML Kit GenAI Prompt API, yang menjalankan model di dalam layanan sistem AICore Android, sehingga teks tidak pernah meninggalkan ponsel.

Panduan ini membahas cara kerja Gemini Nano, perangkat yang mendukungnya, panggilan plugin yang tepat, streaming, kuota dan batas, fallback Gemma untuk ponsel yang tidak didukung, dan bagaimana code yang sama mencapai Apple Intelligence di iOS.

Cara Gemini Nano berjalan di Android

Gemini Nano adalah model Gemini terkecil dari Google, dirancang untuk ponsel. Aplikasi tidak membundelnya. Layanan AICore service mengunduh, memperbarui, dan menjalankan inferensi, dan aplikasi mengaksesnya melalui API ML Kit GenAI:

• Prompt API: prompt teks bebas, API yang dipakai plugin ini (com.google.mlkit:genai-prompt).
• API Fitur: tugas tetap seperti perangkuman, proofreading, penulisan ulang, dan deskripsi gambar.

Google merilis Prompt API sebagai beta, tanpa SLA atau kebijakan deprecation, jadi perkirakan perubahan perilaku antar rilis dan letakkan integrasi di balik wrapper kecil Anda sendiri.

Karena inferensi berjalan lokal, Anda mendapat tiga hal yang tidak bisa diberikan model cloud: berfungsi offline, tanpa biaya per-token, dan teks pengguna tetap di perangkat. Trade-off-nya adalah model lebih kecil dengan konteks dan output pendek, jadi pilih tugas yang cocok: penulisan ulang, merangkum catatan, mengklasifikasikan pesan, mengekstrak field, dan menyusun balasan singkat.

Perangkat yang didukung dan persyaratan

Google memublikasikan daftar perangkat yang didukung per API di situs ML Kit GenAI, dikelompokkan berdasarkan versi Gemini Nano (nano-v2, nano-v3, nano-v4). Untuk Prompt API, daftar ini mencakup Pixel 9 ke atas, flagship Samsung Galaxy S dan Z terbaru, serta flagship terbaru dari OnePlus, OPPO, Xiaomi, vivo, Honor, realme, Motorola, dan lainnya. Periksa daftar terkini sebelum menjanjikan fitur untuk perangkat tertentu.

Setiap perangkat yang didukung juga membutuhkan:

Versi Nano yang berbeda bisa menghasilkan output berbeda untuk prompt yang sama. Tes prompt Anda di setidaknya satu perangkat untuk setiap versi yang Anda pakai.

Install plugin

bun add @capgo/capacitor-llm
bunx cap sync

Plugin ini mengikuti versi mayor Capacitor: gunakan 8.x dengan Capacitor 8. Tidak perlu perubahan Android manifest untuk Gemini Nano. Referensi lengkap: dokumentasi plugin dan halaman plugin.

Langkah 1: Load Gemini Nano dan cek kesiapan

setModel dengan path khusus 'Gemini Nano' meminta status model ke ML Kit. Promise akan resolve saat status tersedia dan reject jika tidak, dengan pesan yang menyertakan status:

import { Capacitor } from '@capacitor/core';
import { CapgoLLM } from '@capgo/capacitor-llm';

export async function loadGeminiNano(): Promise<boolean> {
  if (Capacitor.getPlatform() !== 'android') return false;

  try {
    await CapgoLLM.setModel({
      path: 'Gemini Nano',
      temperature: 0.3,
      topk: 16,
    });
  } catch (error) {
    console.warn('Gemini Nano not ready:', error);
    return false;
  }

  const { readiness } = await CapgoLLM.getReadiness();
  return readiness === 'ready';
}

Plugin tidak memulai unduhan model AICore sendiri. Jika perangkat melaporkan dapat diunduh, model biasanya tersedia setelah aplikasi lain atau sistem memintanya, jadi periksa lagi saat aplikasi dibuka berikutnya daripada menyembunyikan fitur ini secara permanen.

Langkah 2: Buat chat dan stream jawabannya

Chat menyimpan riwayat percakapan. Di Android, sendMessage terselesaikan begitu proses generasi dimulai, dan teks diterima melalui event. Bungkus dengan promise yang resolve saat aiFinished:

import { CapgoLLM } from '@capgo/capacitor-llm';

// Android sends deltas. iOS Apple Intelligence sends the full text so far.
// This merge handles both.
function mergeChunk(current: string, chunk: string) {
  return chunk.startsWith(current) ? chunk : current + chunk;
}

export async function ask(
  chatId: string,
  message: string,
  onText: (textSoFar: string) => void,
): Promise<string> {
  let text = '';
  let finish!: (value: string) => void;
  let fail!: (error: Error) => void;
  const done = new Promise<string>((resolve, reject) => {
    finish = resolve;
    fail = reject;
  });

  const handles = await Promise.all([
    CapgoLLM.addListener('textFromAi', (event) => {
      if (event.chatId !== chatId) return;
      text = mergeChunk(text, event.text);
      onText(text);
    }),
    CapgoLLM.addListener('aiFinished', (event) => {
      if (event.chatId === chatId) finish(text);
    }),
    CapgoLLM.addListener('generationError', (event) => {
      if (!event.chatId || event.chatId === chatId) fail(new Error(event.error));
    }),
  ]);

  // If the app is backgrounded mid-answer, neither event may arrive
  const timeout = setTimeout(() => fail(new Error('Generation timed out')), 60_000);

  try {
    await CapgoLLM.sendMessage({ chatId, message });
    return await done;
  } finally {
    clearTimeout(timeout);
    await Promise.all(handles.map((h) => h.remove()));
  }
}

Gunakan untuk fitur nyata, misalnya menyusun balasan untuk ulasan pelanggan:

const INSTRUCTIONS =
  'You write short, polite replies to customer reviews for a small shop. ' +
  'Answer each point, stay under 60 words, never promise refunds.';

export async function draftReply(review: string, render: (t: string) => void) {
  const { id } = await CapgoLLM.createChat();
  return ask(id, `${INSTRUCTIONS}\n\nReview:\n${review}\n\nReply:`, render);
}

createChat() tidak menerima opsi, jadi letakkan instruksi di awal pesan pertama. Buat chat baru untuk setiap tugas. Pada jalur Gemini Nano, plugin menyimpan riwayat di memori dan mengirimkannya bersama setiap pesan, sehingga chat panjang cepat menghabiskan anggaran input.

Batasan yang perlu diperhatikan

Anggap error kuota sebagai sementara. Tampilkan opsi retry, bukan dialog error.

Fallback: Gemma 4 saat Gemini Nano tidak ada

Sebagian besar ponsel Android yang digunakan saat ini tidak memiliki Gemini Nano. Plugin yang sama dapat menjalankan model Gemma terbuka melalui LiteRT-LM, sehingga Anda tetap menggunakan satu API. Modelnya besar, sering kali lebih dari satu gigabyte, jadi unduh hanya setelah pengguna memilih untuk mengaktifkannya, idealnya saat terhubung ke Wi-Fi.

import { Preferences } from '@capacitor/preferences';
import { CapgoLLM } from '@capgo/capacitor-llm';

const GEMMA_URL =
  'https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm?download=true';

export async function loadGemma(onProgress: (pct: number) => void) {
  const saved = await Preferences.get({ key: 'gemmaPath' });
  if (saved.value) {
    try {
      await CapgoLLM.setModel({ path: saved.value, modelType: 'litertlm', maxTokens: 4096 });
      return;
    } catch {
      // File missing or corrupt, download again
    }
  }

  const sub = await CapgoLLM.addListener('downloadProgress', (e) => onProgress(e.progress));
  try {
    const { path } = await CapgoLLM.downloadModel({
      url: GEMMA_URL,
      filename: 'gemma-4-E2B-it.litertlm',
    });
    await Preferences.set({ key: 'gemmaPath', value: path });
    await CapgoLLM.setModel({ path, modelType: 'litertlm', maxTokens: 4096 });
  } finally {
    await sub.remove();
  }
}

Lalu pilih engine saat startup:

export async function initOnDeviceAI(userAcceptedDownload: boolean, onProgress: (p: number) => void) {
  if (await loadGeminiNano()) return 'gemini-nano';
  if (userAcceptedDownload) {
    await loadGemma(onProgress);
    return 'gemma';
  }
  return 'none';
}

Jika keduanya tidak memungkinkan, sembunyikan fitur tersebut atau panggil model cloud. Jangan blokir alur inti dengan AI lokal.

code yang sama di iOS

Di iOS, plugin ini menggunakan Apple Intelligence melalui framework Foundation Models. Ubah satu baris:

await CapgoLLM.setModel({ path: 'Apple Intelligence' });

createChat, sendMessage, dan event-nya tetap sama, dan mergeChunk helper di atas sudah menangani format streaming iOS. Persyaratan perangkat berbeda (iOS 26 dan perangkat yang mendukung Apple Intelligence). Panduan kami tentang Apple Intelligence di aplikasi Capacitor menutupi sisi tersebut.

Pengujian

• Gunakan ponsel yang benar-benar didukung. Emulator tidak menyediakan AICore dengan Gemini Nano.
• Log setModel pesan penolakan. Pesan ini memberi tahu status apa yang dilaporkan AICore.
• Pada perangkat yang baru di-setup atau di-reset, tunggu hingga AICore menyelesaikan setup awal saat online, lalu coba lagi.
• Uji prompt Anda pada versi Nano terendah yang Anda dukung. Prompt yang lebih pendek dan eksplisit lebih stabil di berbagai versi.

Pemecahan Masalah

“Gemini Nano tidak tersedia di perangkat ini”. Perangkat tidak ada di daftar Google, bootloader terbuka, atau AICore belum di-setup.

“Gemini Nano tersedia untuk diunduh, tapi belum diunduh”. Perangkat mendukungnya, tetapi model belum ada. Tawarkan fallback Gemma atau coba lagi nanti.

“Sesi chat tidak ditemukan”. Anda memanggil sendMessage dengan chat yang dibuat sebelum model baru dimuat setModel. Memuat model akan menghapus chat yang ada, jadi buat chat baru.

“Model belum siap”. setModel gagal atau tidak dipanggil sebelumnya createChat.

Output terhenti di tengah kalimat. Anda mencapai batas output. Minta jawaban yang lebih pendek atau bagi tugasnya.

Error saat aplikasi masuk ke background. Inference hanya berjalan di foreground. Batalkan state UI saat pause dan biarkan user mencoba lagi.

Privasi dan review toko

Prompt dan respons tetap di perangkat dengan Gemini Nano, yang menyederhanakan formulir Data safety Anda. Syarat ML Kit Google masih menyebutkan pemrosesan metrik, jadi jelaskan penggunaan AI on-device dalam kebijakan privasi Anda. Jika Anda menambahkan fallback Gemma, unduhan model berasal dari Hugging Face, jadi sebutkan juga permintaan jaringan tersebut.

Prompt dan teks UI untuk fitur AI sering berubah. Jika Anda perlu menyesuaikannya setelah rilis, Live updates Capgo memungkinkan Anda merilis web code baru tanpa menunggu review store. Untuk gambaran lebih luas soal AI di aplikasi hybrid, baca mengapa Capacitor cocok untuk aplikasi mobile AI.

Kesimpulan

Gemini Nano menghadirkan generasi teks gratis, privat, dan offline untuk aplikasi Capacitor di ponsel Android yang didukung. Muat dengan setModel({ path: 'Gemini Nano' }), stream melalui textFromAi, jaga prompt dan output tetap singkat, patuhi aturan foreground dan kuota, serta siapkan fallback Gemma atau cloud untuk banyak perangkat yang tidak memilikinya.