Wie man Gemini Nano in einer Capacitor-App verwenden kann

Um Gemini Nano in einer Capacitor-App zu verwenden, installieren Sie @capgo/capacitor-llmrufen Sie setModel({ path: 'Gemini Nano' }) auf Android an, erstellen Sie dann eine Chatnachricht und streamen Sie die Antwort über das textFromAi event. Der Plugin spricht mit Gemini Nano über Google’s ML Kit GenAI Prompt API, das den Modell innerhalb von Android’s AICore Systemdienst läuft, so dass der Text nie das Telefon verlässt.

Dieses Leitfaden deckt ab, wie Gemini Nano läuft, welche Geräte es unterstützt, die genauen Pluginaufrufe, Streaming, Quoten und Grenzen, einen Gemma-Fallback für nicht unterstützte Telefone und wie der gleiche code auf Apple Intelligence auf iOS erreicht wird.

Wie Gemini Nano auf Android läuft

Gemini Nano ist Googles kleinstes Gemini-Modell, das für Telefone gebaut ist. Apps laden es nicht. Android’s AICore Dienst lädt es herunter, aktualisiert es und läuft die Inference, und Apps erreichen es über die ML Kit GenAI APIs:

• Prompt API: freiforme Textanfragen, den API dieses Plugins verwendet (com.google.mlkit:genai-prompt).
• Funktions-APIs: fixierte Aufgaben wie Zusammenfassung, Korrektur, Überarbeitung und Bildbeschreibung.

Google liefert den Prompt API als Beta-Version, ohne SLA oder Deprecation-Policy, also erwarten Sie Verhaltensänderungen zwischen Releases und halten die Integration hinter Ihrem eigenen kleinen Wrapper.

Da die Inferenz lokal ist, erhalten Sie drei Dinge, die ein Cloudmodell Ihnen nicht geben kann: Es funktioniert offline, es gibt keine Tokenkosten und der Benutzer-Text bleibt auf dem Gerät. Der Handel ist ein kleineres Modell mit kurzer Kontext- und Ausgabedauer, also wählen Sie Aufgaben, die passen: Umschreiben, einen Notizen-Zusammenfassung erstellen, eine Nachricht klassifizieren, Felder extrahieren, kurze Antworten entwerfen.

Unterstützte Geräte und Anforderungen

Google veröffentlicht die Liste der unterstützten Geräte pro API auf der ML Kit GenAI-Seite, gruppiert nach Gemini Nano-Version (nano-v2, nano-v3, nano-v4). Für den Prompt API umfasst sie das Pixel 9 und später, aktuelle Samsung Galaxy S- und Z-Flaggschiffe sowie aktuelle Flaggschiffe von OnePlus, OPPO, Xiaomi, vivo, Honor, realme, Motorola und anderen. Überprüfen Sie die lebende Liste, bevor Sie eine Funktion einem bestimmten Gerät versprechen.

Jedes unterstützte Gerät benötigt auch:

Verschiedene Nano-Versionen können für denselben Prompt unterschiedliche Ausgaben liefern. Testen Sie Ihre Prompts auf mindestens einem Gerät pro Version, die Sie beachten möchten.

Installieren Sie das Plugin

bun add @capgo/capacitor-llm
bunx cap sync

Das Plugin folgt der Hauptversion von Capacitor: Verwenden Sie 8.x mit Capacitor 8. Für Gemini Nano sind keine Änderungen an der Android-Manifestdatei erforderlich. Vollständige Referenz: plugin docs und Plugin-Seite.

Step 1: Load Gemini Nano and check readiness

setModel mit der speziellen Pfad 'Gemini Nano' fragt das ML Kit nach dem Modellstatus. Es wird aufgelöst, wenn der Status verfügbar ist, und wird sonst abgelehnt, mit einer Nachricht, die den Status enthält:

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';
}

Das Plugin startet den Download des AICore-Modells nicht selbst. Wenn ein Gerät herunterladbar meldet, kommt das Modell normalerweise nachdem ein anderes App oder das System es anfordert, also überprüfen Sie es wieder bei einem späteren Start, anstatt die Funktion dauerhaft zu verstecken.

Schritt 2: Erstellen Sie einen Chat und streamen Sie die Antwort

Eine Chat hält die Gesprächsgeschichte. Auf Android, sendMessage erledigt sich so schnell wie die Generierung beginnt, und Text kommt durch Ereignisse. Verwenden Sie es in einer Promise, die sich auf 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()));
  }
}

Einsatz machen Sie für eine echte Funktion, zum Beispiel das Ausarbeiten einer Antwort auf eine Kundenbewertung:

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() erfordert keine Optionen, also legen Sie Anweisungen am Anfang des ersten Nachrichten. Erstellen Sie eine neue Chat pro Aufgabe. Auf dem Gemini Nano Weg hält der Plugin die Geschichte im Speicher und sendet sie mit jeder Nachricht, also nutzen lange Chats schnell den Eingabebudget.

Grenzen zur Gestaltung

Behandeln Sie eine Quotenfehler als vorübergehend. Zeigen Sie eine Wiederholungsoption anstatt einem Fehlerdialog an.

Fallback: Gemma 4, wenn Gemini Nano fehlt

Die meisten heutigen Android-Smartphones haben keinen Gemini Nano. Der gleiche Plugin kann jedoch offene Gemma-Modelle über LiteRT-LM ausführen, sodass Sie einen API behalten. Das Modell ist groß und oft über einen Gigabyte, daher laden Sie es nur nachdem der Benutzer zustimmt, idealerweise über Wi-Fi herunter.

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();
  }
}

Dann wählen Sie den Motor am Start:

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';
}

Wenn weder möglich ist, verbergen Sie die Funktion oder rufen Sie einen Cloud-Modell auf. Blockieren Sie keine Kernflüsse auf lokalem AI.

Der gleiche code auf iOS

Auf iOS verwendet der Plugin Apple Intelligence über das Framework Foundation Models. Ändern Sie eine Zeile:

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

createChat, sendMessage, und die Ereignisse bleiben gleich, und der mergeChunk oben stehende Helper handhabt bereits die iOS-Streaming-Format. Die Geräteanforderungen unterscheiden sich (iOS 26 und ein Apple Intelligence-fähiges Gerät). Unsere Anleitung auf Apple-Intelligenz in einer Capacitor-App deckt diese Seite ab.

Testen

• Verwenden Sie ein echtes unterstütztes Telefon. Emulatoren liefern AICore mit Gemini Nano nicht.
• Loggen Sie das setModel Ablehnungsnachricht. Sie sagt Ihnen genau, welchen Status AICore meldet.
• Warten Sie auf AICore, während es sich online auf den ersten Start einrichtet, und versuchen Sie es dann erneut.
• Testen Sie Ihre Anfragen auf der niedrigsten Nano-Version, die Sie unterstützen. Kurze, explizite Anfragen sind stabil über Versionen hinweg.

Fehlersuche

“Gemini Nano ist auf diesem Gerät nicht verfügbar.” Das Gerät steht nicht auf der Liste von Google, der Bootloader ist entsperrt oder AICore ist noch nicht eingerichtet.

“Gemini Nano ist herunterladbar, aber nicht heruntergeladen.” Das Gerät unterstützt es, aber das Modell ist nicht verfügbar. Bieten Sie den Gemma-Fallback an oder versuchen Sie es später.

“Chat-Sitzung nicht gefunden”. Du hast angerufen sendMessage mit einem Chat, der vor einer neuen setModelEin Modell laden löscht bestehende Chats, also erstellen Sie ein neues.

“Modell nicht bereit”. setModel fehlgeschlagen oder wurde nicht vorher aufgerufen createChat.

Ausgabe bleibt mitten im Satz stehen. You hit the output cap. Ask for a shorter answer or split the task.

Fehler, wenn die App in den Hintergrund geschoben wird. Inferenz ist nur im Vordergrund aktiv. Storniere die Benutzeroberfläche und lasse den Benutzer erneut versuchen.

Datenschutz und Store-Bewertung

Prompts und Antworten bleiben auf dem Gerät bei Gemini Nano, was Ihre Datensicherheit erleichtert. Googles ML Kit-Bedingungen erwähnen immer noch die Verarbeitung von Metriken, also beschreiben Sie die Verwendung von AI auf dem Gerät in Ihrer Datenschutzrichtlinie. Wenn Sie die Gemma-Fallback-Option hinzufügen, wird der Modell-Download von Hugging Face stammen, also erwähnen Sie auch diesen Netzwerkaufruf.

Prompts und UI-Kopien für AI-Funktionen ändern sich oft. Wenn Sie sie nach der Veröffentlichung anpassen müssen, Capgo Live-Updates lassen Sie Sie neue Web-code ohne Wartezeit auf die Store-Überprüfung verschicken. Für die größere Perspektive zu AI in hybriden Apps lesen Sie why Capacitor gut für AI-Mobil-Apps funktioniert.

Abschluss

Gemini Nano bietet Capacitor-Apps kostenlose, private, offline-Textgenerierung auf unterstützten Android-Smartphones. Laden Sie es mit setModel({ path: 'Gemini Nano' }), streamen Sie durch textFromAi, halten Sie Prompts und Outputs kurz, respektieren Sie die Vordergrund- und Quotenregeln und halten Sie einen Gemma- oder Cloud-Fallback für die vielen Geräte bereit, die es nicht haben.