How to Menggunakan Gemini Nano di Aplikasi Capacitor

Menggunakan Gemini Nano di Aplikasi Capacitor, instal @capgo/capacitor-llm, panggil setModel({ path: 'Gemini Nano' }) di Android, kemudian buatlah obrolan dan alirkan jawaban melalui textFromAi event. Plugin ini berbicara dengan Gemini Nano melalui Google’s ML Kit GenAI Prompt API, yang menjalankan model di dalam sistem layanan AICore Android, sehingga teks tidak pernah meninggalkan ponsel.

Panduan ini menjelaskan bagaimana Gemini Nano berjalan, perangkat mana yang mendukungnya, panggilan plugin yang tepat, streaming, kuota dan batasan, fallback Gemma untuk ponsel yang tidak mendukung, dan bagaimana code yang sama mencapai Intelijen Apple di iOS.

Bagaimana Gemini Nano berjalan di Android

Gemini Nano adalah model Gemini terkecil dari Google, dibangun untuk ponsel. Aplikasi tidak mengemasnya. Layanan AICore dari Android mengunduhnya, memperbaruhinya, dan menjalankan inferensi, dan aplikasi mencapainya melalui Kit Aplikasi ML GenAI:

• Prompt API: prompt teks bebas, API ini yang digunakan oleh plugin (com.google.mlkit:genai-prompt).
• Fitur APIs: tugas-tugas tetap seperti ringkasan, pengecekan kesalahan, pengulangan, dan deskripsi gambar.

Google mengirimkan Prompt API sebagai beta, tanpa kebijakan SLA atau kebijakan deprecasi, jadi harapkan perubahan perilaku antara rilis dan simpan integrasi di balik wrapper kecil milik Anda sendiri.

Karena inferensi dilakukan secara lokal, Anda mendapatkan tiga hal yang tidak dapat diberikan oleh model cloud: itu berfungsi secara offline, tidak ada biaya per-token, dan teks pengguna tetap di perangkat. Pertukaran adalah model yang lebih kecil dengan konteks dan output yang singkat, jadi pilih tugas yang sesuai: merevisi, menyusun ulang catatan, mengklasifikasikan pesan, mengekstrak bidang, dan mengajukan jawaban singkat.

Perangkat yang Dapat Dibantu dan Persyaratan

Google menerbitkan daftar perangkat yang didukung per API di situs ML Kit GenAI, yang dikategorikan berdasarkan versi Gemini Nano (nano-v2, nano-v3, nano-v4). Untuk Prompt API, itu mencakup Pixel 9 dan seterusnya, Samsung Galaxy S dan Z flagship terbaru, serta flagship terbaru dari OnePlus, OPPO, Xiaomi, vivo, Honor, realme, Motorola, dan lain-lain. Periksa daftar hidup sebelum Anda berjanji fitur pada perangkat tertentu.

Setiap perangkat yang didukung juga memerlukan:

Versi Nano yang berbeda dapat menghasilkan output yang berbeda untuk prompt yang sama. Uji coba prompt Anda di setidaknya satu perangkat per versi yang Anda pedulikan

Instal plugin

bun add @capgo/capacitor-llm
bunx cap sync

Plugin mengikuti versi utama Capacitor: gunakan 8.x dengan Capacitor 8. Tidak perlu mengubah file manifest Android untuk Gemini Nano. Referensi lengkap: docs plugin dan halaman plugin.

Langkah 1: Muat Gemini Nano dan periksa kesiapan

setModel bersama dengan jalur khusus 'Gemini Nano' Mengajukan permintaan ke ML Kit untuk status model. Ia diselesaikan ketika status tersedia dan ditolak jika tidak, dengan pesan yang mencakup status tersebut.

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 ini tidak memulai pengunduhan model AICore secara otomatis. Jika perangkat melaporkan tersedia untuk diunduh, model biasanya akan datang setelah aplikasi lain atau sistem meminta, jadi periksa lagi pada peluncuran yang lebih lanjut daripada menyembunyikan fitur secara permanen.

Langkah 2: Buatlah percakapan dan streaming jawaban

Sebuah percakapan menjaga riwayat percakapan. Pada Android, sendMessage terselesaikan segera ketika generasi dimulai, dan teks tiba melalui event. Tutupnya dengan sebuah janji yang terselesaikan pada 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 fitur ini untuk fitur nyata, misalnya menyiapkan jawaban atas 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 memerlukan pilihan, jadi letakkan instruksi di awal pesan pertama. Buatlah percakapan baru per tugas. Pada jalur Gemini Nano, plugin menjaga riwayat dalam memori dan mengirimkannya bersama setiap pesan, sehingga percakapan panjang menggunakan anggaran input dengan cepat.

Batasi untuk desain

Tangani kesalahan kuota sebagai sementara. Tampilkan opsi ulangi daripada dialog kesalahan.

Fallback: Gemma 4 ketika Gemini Nano tidak tersedia

Most Android phones in use today do not have Gemini Nano. The same plugin can run open Gemma models through LiteRT-LM, so you keep one API. The model is large, often over a gigabyte, so download it only after the user opts in, ideally on 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();
  }
}

Pilih mesin pada 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 tidak mungkin, sembunyikan fitur atau panggil model awan. Tidak boleh menghalangi aliran inti di AI lokal.

Sama seperti code di iOS

Pada iOS, plugin ini menggunakan Intelijen Apple melalui kerangka kerja Model Dasar Foundation. Ubah satu baris:

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

createChat, sendMessage, and the events stay the same, and the mergeChunk bantuan di atas sudah menangani format streaming iOS. Spesifikasi perangkat berbeda (iOS 26 dan perangkat yang mampu Apple Intelligence). Panduan kami tentang Apple Intelligence di sebuah Capacitor aplikasi menangani sisi tersebut.

Testing

• Pakai ponsel nyata yang didukung. Emulator tidak menyediakan AICore dengan Gemini Nano.
• Catat Log setModel Pesan penolakan. Ia memberitahu Anda secara spesifik status apa yang dilaporkan oleh AICore.
• Tunggu AICore selesai melakukan pengaturan awal saat online, lalu coba lagi.
• Teskan prompt Anda pada versi Nano yang paling rendah yang Anda dukung. Prompt yang lebih singkat dan eksplisit lebih stabil di berbagai versi.

Troubleshooting

“Gemini Nano tidak tersedia pada perangkat ini”. Perangkat ini tidak terdaftar di Google, bootloder belum diaktifkan, atau AICore belum diatur.

“Gemini Nano dapat diunduh tetapi tidak diunduh”. Perangkat mendukungnya tetapi modelnya tidak tersedia. Tawarkan fallback Gemma atau coba lagi nanti.

“Sesi percakapan tidak ditemukan”. Kamu menghubungi sendMessage dengan percakapan yang dibuat sebelum ada setModel. Muatan model menghapus percakapan yang ada, jadi buatlah yang baru.

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

Output berhenti di tengah kalimat. Anda telah mencapai batas keluaran. Tolak ansur atau bagilah tugas.

Kesalahan ketika aplikasi masuk ke latar belakang. Inferensi hanya berjalan di latar depan. Batalkan status UI ketika pause dan biarkan pengguna mencoba lagi.

Privasi dan ulasan toko

Prompt dan respons tetap di perangkat dengan Gemini Nano, yang memudahkan keamanan data Anda. Istilah ML Kit Google masih menyebutkan pengolahan metrik, jadi deskripsikan penggunaan AI di perangkat dalam kebijakan privasi Anda. Jika Anda menambahkan fallback Gemma, model download datang dari Hugging Face, jadi sebutkan permintaan jaringan juga.

Prompt dan salinan UI untuk fitur AI berubah sering. Jika Anda perlu menyesuaikan mereka setelah rilis, Capgo pembaruan hidup Mengizinkan Anda mengirimkan aplikasi web baru code tanpa harus menunggu tinjauan toko. Untuk gambaran yang lebih luas tentang AI di aplikasi hybrid, baca Mengapa Capacitor berfungsi baik untuk aplikasi mobile AI.

Wrap-up

Gemini Nano memberikan Capacitor aplikasi gratis, pribadi, dan offline untuk penghasilan teks pada ponsel Android yang didukung. Muatlah dengan setModel({ path: 'Gemini Nano' }), stream through textFromAiGemini Nano memberikan aplikasi __CAPGO_KEEP_0__ penghasilan teks gratis, pribadi, dan offline di ponsel Android yang didukung. Muatlah dengan