So nutzt du Apple Intelligence in einer Capacitor App

Um Apple Intelligence in einer Capacitor-App zu nutzen, installieren Sie @capgo/capacitor-llm, rufe setModel({ path: 'Apple Intelligence' }), prüfen Sie getReadiness(), erstellen Sie dann einen Chat und streamen Sie die Antworten über das textFromAi -Event. Im Hintergrund nutzt das Plugin Apples Foundation Models Framework, das mit iOS 26 eingeführt wurde. Es führt Apples On-Device-Sprachmodell aus – ohne API-Key, ohne Kosten pro Anfrage und ohne dass Daten das Telefon verlassen.

Dieser Guide behandelt, was das Framework bietet, die Geräteanforderungen, eine vollständige TypeScript-Integration, das 4.096-Token-Kontextfenster, Fehlerbehandlung, Hinweise für die App-Review und wie dasselbe code auf Android läuft.

Was Apple Intelligence App-Entwicklern bietet

Mit iOS 26 hat Apple sein On-Device-Grundmodell für Apps von Drittanbietern über die Foundation Models framework. In Swift arbeiten Sie mit SystemLanguageModel und LanguageModelSession. Das Plugin kapselt diese, damit dein Web-code sie nutzen kann:

Das Modell hat etwa 3 Milliarden Parameter. Es eignet sich gut zum Zusammenfassen, Umformulieren, Extrahieren, Klassifizieren und für kurze Textgenerierungen. Es ist kein Ersatz für ein großes Cloud-Modell bei offenen Wissensfragen – Apple sagt das selbst in seinen Richtlinien. Gestalte Features um Text herum, den der Nutzer bereits hat.

Geräte- und OS-Anforderungen

Falls dein Projekt noch mit einer älteren Xcode-Version gebaut wird, siehe Apples Xcode-26-Anforderung für Capacitor Apps. Das Deployment Target deiner App muss nicht geändert werden. Das Plugin unterstützt iOS 15 und neuer und greift unter iOS 26 nur auf Foundation Models zu.

Plugin installieren

bun add @capgo/capacitor-llm
bunx cap sync ios

Nutze Plugin 8.x mit Capacitor 8. Für Apple Intelligence sind keine Info.plist-Keys oder Entitlements nötig. Falls du noch auf Capacitor 7 bist, der Capacitor 8 Upgrade-Guide kommt zuerst. Referenz-Docs: /docs/plugins/llm/.

Schritt 1: Modell auswählen und Verfügbarkeit prüfen

setModel({ path: 'Apple Intelligence' }) wählt das Systemmodell aus und löst sofort auf. Die tatsächliche Verfügbarkeit stammt von getReadiness(), das Apples Verfügbarkeits-Enum in lesbare Strings mappt:

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

export type AIState = 'ready' | 'enable-in-settings' | 'preparing' | 'unsupported';

export async function initAppleIntelligence(): Promise<AIState> {
  if (Capacitor.getPlatform() !== 'ios') return 'unsupported';

  await CapgoLLM.setModel({ path: 'Apple Intelligence' });
  const { readiness } = await CapgoLLM.getReadiness();

  if (readiness === 'ready') return 'ready';
  if (readiness.includes('not enabled')) return 'enable-in-settings';
  if (readiness.includes('not ready')) return 'preparing';
  return 'unsupported';
}

Prüfe erneut, wenn die App in den Vordergrund zurückkehrt. Nutzer aktivieren Apple Intelligence oft erst nach dem Anzeigen Ihres Hinweises, und der Modell-Download kann abgeschlossen werden, während Ihre App im Hintergrund läuft.

import { App } from '@capacitor/app';

App.addListener('appStateChange', async ({ isActive }) => {
  if (isActive) updateAIState(await initAppleIntelligence());
});

Schritt 2: Chat mit Anweisungen erstellen

Ein Chat wird einer zugeordnet LanguageModelSession, die den Gesprächsverlauf speichert. Der eingegebene createChat() akzeptiert keine Optionen, daher sollten Sie Ihre Anweisungen am Anfang der ersten Nachricht angeben:

const INSTRUCTIONS =
  'You summarize meeting notes. Reply with at most 5 bullet points. ' +
  'Keep names and dates exactly as written. Do not add information.';

const { id: chatId } = await CapgoLLM.createChat();

Verwenden Sie einen Chat pro Aufgabe. Ein Chat, der ständig wächst, wird schließlich das unten beschriebene Kontextlimit erreichen.

Schritt 3: Antwort in die UI streamen

Auf iOS wird für jede textFromAi Das Event enthält einen Snapshot der bisherigen Antwort, da Foundation Models so streamen. Auf Android mit Gemini Nano enthalten Events nur den neuen Text. Dieser Helper behandelt beide Fälle und löst mit dem finalen Text auf:

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

function mergeChunk(current: string, chunk: string) {
  return chunk.startsWith(current) ? chunk : current + chunk;
}

export async function ask(chatId: string, message: string, onText: (t: string) => void) {
  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', (e) => {
      if (e.chatId !== chatId) return;
      text = mergeChunk(text, e.text);
      onText(text);
    }),
    CapgoLLM.addListener('aiFinished', (e) => {
      if (e.chatId === chatId) finish(text);
    }),
    CapgoLLM.addListener('generationError', (e) => {
      if (!e.chatId || e.chatId === chatId) fail(new Error(e.error));
    }),
  ]);

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

Alles zusammen: Notizen auf dem Gerät zusammenfassen

export async function summarizeNotes(notes: string, render: (t: string) => void) {
  const state = await initAppleIntelligence();
  if (state !== 'ready') throw new Error(`AI unavailable: ${state}`);

  const { id } = await CapgoLLM.createChat();
  const prompt = `${INSTRUCTIONS}\n\nNotes:\n${notes.slice(0, 8000)}\n\nSummary:`;
  return ask(id, prompt, render);
}

Der slice ist ein grober Schutz vor riesigen Inputs. Besser ist es, lange Dokumente in Chunks zusammenzufassen und dann die Zusammenfassungen zu fassen, jeweils in einem neuen Chat.

In einem Framework-Komponente den Button deaktivieren, während ask läuft. Das Plugin lehnt ein zweites sendMessage im selben Chat mit „Chat antwortet, bitte warten, bevor du neue Fragen stellst“ ab.

Das 4.096-Token-Kontextfenster

Das On-Device-Modell hat ein Kontextfenster von 4.096 Tokens. Alles zählt dazu: Anweisungen, jeder vorherige Turn im Chat, der neue Prompt und die generierte Antwort. Überschreitet eine Session das Limit, wirft Foundation Models einen „exceeded context window size“-Fehler, der dir als generationError Event und ein abgelehntes sendMessage.

Praktische Regeln:

• Ein Chat pro Aufgabe, nicht ein Chat pro Screen.
• Halte Anweisungen kurz und spezifisch.
• Bei mehrstufigen Chats starten Sie einen neuen Chat, wenn er lang wird, und übergeben eine kurze Zusammenfassung des vorherigen Gesprächs.
• Frag nach knappen Antworten. Lange Antworten verbrauchen das gleiche Budget.

Output optimieren

Auf dem Apple Intelligence-Pfad verwendet das Plugin die Standard-Generierungseinstellungen des Systems. temperature, topk, und maxTokens in einem setModel gelten für die Custom-Pfade von LiteRT-LM und MediaPipe. Um Apples Modell zu steuern, verlass dich auf den Prompt: Gib an, wie lang die Antwort sein soll, nenne das Format (Bullets, JSON, ein Satz) und füge ein kurzes Beispiel hinzu, wenn das Format wichtig ist.

Dasselbe code auf Android

Nur die Modellwahl ändert sich:

const path = Capacitor.getPlatform() === 'ios' ? 'Apple Intelligence' : 'Gemini Nano';
await CapgoLLM.setModel({ path });

Unter Android, setModel wird abgelehnt, wenn Gemini Nano nicht verfügbar ist. Du kannst über dasselbe Plugin auf ein herunterladbares Gemma-Modell ausweichen. Die Details findest du in So nutzt ihr Gemini Nano in einer Capacitor-App.

Testen

• Echtes Gerät: der zuverlässige Weg. Nutzt ein unterstütztes iPhone mit iOS 26 und aktiviertem Apple Intelligence.
• Simulator: kann das Modell nutzen, wenn der Host-Mac macOS 26 auf Apple Silicon mit aktiviertem Apple Intelligence ausführt. Verhalten und Geschwindigkeit unterscheiden sich vom Smartphone, daher auf Hardware verifizieren.
• Nicht unterstützte Zustände: testet mit deaktiviertem Apple Intelligence, um eure „In Einstellungen aktivieren“-UI zu prüfen, und auf einem älteren iPhone oder einer älteren iOS-Version, um sicherzustellen, dass die Funktion sauber ausgeblendet wird.

App Review und Datenschutz

Prompts und Antworten bleiben auf dem Gerät, daher fügt die On-Device-Generierung an sich keine Datenerfassung zu eurem Privacy-Label hinzu. Zwei Punkte liegen trotzdem bei euch:

1. Apple veröffentlicht Nutzungsbedingungen für das Foundation Models framework. Lest sie vor dem Release, besonders für Features, die Inhalte für andere Nutzer generieren.
2. Das Modell hat eingebaute Guardrails und kann bestimmte Prompts oder Outputs ablehnen. Behandelt eine Ablehnung als normales Ergebnis und zeigt eine klare Meldung an.

Da Prompts in deinem Web-code einfache Strings sind, kannst du sie nach dem Launch mit folgenden Tools verbessern: Capgo Live Updates anstatt auf einen neuen App Store Build zu warten. Änderungen an der nativen code, inklusive Plugin-Upgrades, erfordern weiterhin ein Store-Release, das du in der Cloud bauen kannst – mit Capgo Build.

Häufige Fehler und Lösungen

Fazit

Apple Intelligence bringt ein kostenloses, privates, offline-fähiges Sprachmodell auf jedes unterstützte iPhone mit iOS 26, und eine Capacitor-App kann es mit wenigen Zeilen TypeScript nutzen. Wähle das Modell, steuere die UI anhand getReadiness(), halte jede Aufgabe in einem eigenen kurzen Chat, streame Snapshots in die UI und behandle Ablehnungen und Kontextfehler als normale Ergebnisse. Für einen breiteren Blick auf das Ausliefern von KI-Funktionen in Hybrid-Apps lies warum Capacitor für mobile KI-Apps ideal ist.