Apple Intelligence in einer Capacitor-App verwenden

Um Apple Intelligence in einer Capacitor-App zu verwenden, installieren Sie @capgo/capacitor-llm, rufen Sie setModel({ path: 'Apple Intelligence' }), check getReadiness(), erstellen Sie dann einen Chat und streamen Sie Antworten über das textFromAi ereignis. Unter der Haube verwendet der Plugin Apple's Foundation Models Framework, der mit iOS 26 eingeführt wurde, der Apple's on-device Sprachmodell mit keinem API-Schlüssel, ohne Kosten pro Anfrage und ohne Daten, die das Telefon verlassen.

Dieses Leitfaden deckt, was das Framework bietet, die Geräteanforderungen, eine vollständige TypeScript-Integration, die 4.096-Token-Kontextfenster, Fehlerbehandlung, App-Bewertungs-Hinweise und wie das gleiche code auf Android läuft.

Was Apple Intelligence app-Entwicklern bietet

With iOS 26, Apple öffnete seine on-device-Grundmodell für Drittanbieter-Apps über das Grundmodell-Modelle Framework. In Swift arbeiten Sie mit SystemLanguageModel und LanguageModelSession. Das Plugin umhüllt diese, damit Ihre Web- code sie nutzen kann:

Das Modell hat etwa 3 Milliarden Parameter. Es ist gut in der Zusammenfassung, Wiedergabe, Extraktion, Klassifizierung und Kurzformgenerierung. Es ist kein Ersatz für ein großes Cloudmodell bei offenen Fragen zur Wissensverteilung und Apple sagt das auch in seiner eigenen Anleitung. Entwerfen Sie Funktionen um Text, den der Benutzer bereits hat.

Geräte- und Betriebssystemanforderungen

Xcode 26, das auch App Store Connect seit April 2026 für Uploads benötigt Apple's Xcode 26-Anforderung für Capacitor-Apps. Your app’s minimum deployment target does not need to change. The plugin supports iOS 15 and later and only touches Foundation Models on iOS 26.

Installieren Sie das Plugin

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

Verwenden Sie den Plugin 8.x mit Capacitor 8. Keine Info.plist-Schlüssel oder Berechtigungen sind für Apple Intelligence erforderlich. Wenn Sie noch immer auf Capacitor 7 sind, kommt das Capacitor 8 Upgrade-Hilfe kommt zuerst. Referenzdokumentation: /dokumentation/plugins/llm/.

Schritt 1: Wählen Sie das Modell und überprüfen Sie die Verfügbarkeit

setModel({ path: 'Apple Intelligence' }) wählt das Systemmodell und löst es sofort. Die tatsächliche Verfügbarkeit ergibt sich aus getReadiness(), das Apple's Verfügbarkeit-Enum in lesbarere String umwandelt:

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

Überprüfe es noch einmal, wenn die App wieder in den Vordergrund kommt. Benutzer aktivieren oft Apple Intelligence, nachdem sie deinen Hinweis gesehen haben, und das Modell herunterladen kann während deiner App im Hintergrund abgeschlossen werden.

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

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

Schritt 2: Erstelle eine Chat mit Anweisungen

Ein Chat entspricht einem LanguageModelSession, das die Gesprächsgeschichte aufbewahrt. Die eingegebenen createChat() nimmt keine Optionen an, daher sollten Sie Ihre Anweisungen an den Anfang der ersten Nachricht setzen:

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 wachsender Chat wird schließlich die unter der folgenden Beschreibung beschriebene Kontextgrenze erreichen.

Schritt 3: Strömen Sie die Antwort in die UI

Unter iOS textFromAi Jedes Ereignis trägt einen Snapshot der Antwort bis dahin, weil sich Foundation-Modelle so verhalten. Auf Android mit Gemini Nano tragen Ereignisse nur den neuen Text. Diese Hilfsfunktion handhabt beide und löst sich 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()));
  }
}

Zusammenfassen Sie Notizen auf dem Gerät

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

Die slice ist eine grobe Wächterin gegenüber riesigen Eingaben. Eine bessere Vorgehensweise ist es, lange Dokumente in Abschnitte zu zerlegen und diese dann in einem neuen Chat zu zusammenfassen.

In einem Framework-Komponenten deaktivieren Sie den Button, während ask läuft. Der Plugin lehnt eine zweite sendMessage auf demselben Chat mit „Die Antwort wird ermittelt, warten Sie, bevor Sie eine neue Frage stellen“ ab.

Die 4.096-Token-Kontextfenster

Die Modellinstanz hat einen Kontextfenster von 4.096 Token. Alles zählt dazu: Anweisungen, jede vorherige Runde im Chat, der neue Input und die generierte Antwort. Wenn eine Sitzung es überschreitet, wirft Foundation Models eine "Überschreitung der Kontextfenstergröße"-Fehlermeldung, die als generationError ein Ereignis und eine abgelehnte sendMessage.

Praktische Regeln:

• Eine Chat-Sitzung pro Aufgabe, nicht eine pro Bildschirm.
• Beibehalten Sie Anweisungen kurz und spezifisch.
• Bei mehreren Runden im Chat starten Sie eine neue Sitzung, wenn sie lang wird, und übergeben Sie einen kurzen Abriss der früheren Konversation.
• Bitten Sie um eine knappe Antwort. Lange Antworten nutzen den gleichen Budget.

Einstellungsausgabe

Auf der Apple Intelligence-Pfad verwendet der Plugin die Standardsystemeinstellungen für die Erstellung. temperature, topk, and maxTokens und setModel auf die benutzerdefinierten LiteRT-LM- und MediaPipe-Modellpfade an. Um Apples Modell zu steuern, verlassen Sie sich auf den Input: Sagen Sie, wie lange die Antwort sein soll, geben Sie die Formatierung (Bullenpunkte, JSON, eine Sätze) an und fügen Sie ein kurzes Beispiel ein, wenn die Formatierung relevant ist.

Das gleiche code auf Android

Ändert sich nur die Modellauswahl:

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

Auf Android setModel wirft eine Exception, wenn der Gemini Nano nicht verfügbar ist, und Sie können auf einen herunterladbaren Gemma-Modell durch denselben Plugin zurückfallen. Die Details finden Sie in wie Sie den Gemini Nano in einer Capacitor-App verwenden.

Testen

• Realgerät: die zuverlässige Route. Verwenden Sie ein unterstütztes iPhone auf iOS 26 mit Apple Intelligence.
• Simulator: es kann den Modell verwenden, wenn der Host-Mac auf macOS 26 mit Apple Silicon und Apple Intelligence aktiviert ist. Das Verhalten und die Geschwindigkeit unterscheiden sich von einem Telefon, daher bestätigen Sie auf Hardware.
• Unerstützte Zustände: testen Sie mit Apple Intelligence deaktiviert, um Ihre "Ermöglichung in Einstellungen"-UI zu überprüfen, und auf einem älteren iPhone oder einer älteren iOS-Version, um zu überprüfen, dass die Funktion sauber versteckt wird.

App-Bewertung und Datenschutz

Die Anfragen und Antworten bleiben auf dem Gerät, sodass die On-Device-Generation keine Daten sammelt, die in Ihrem Datenschutzhinweis aufgenommen werden müssen. Zwei Dinge bleiben Ihnen noch vorbehalten:

1. Apple veröffentlicht die zulässigen Nutzungsvorschriften für das Framework der Foundation-Modelle. Lesen Sie sie, bevor Sie es ausliefern, insbesondere für Funktionen, die Inhalte an andere Benutzer anzeigen.
2. Das Modell verfügt über eingebaute Schutzmechanismen und kann bestimmte Anfragen oder Ausgaben ablehnen. Behandeln Sie eine Ablehnung als normales Ergebnis und zeigen Sie eine klare Nachricht an.

Da Anfragen als einfache Zeichenketten in Ihrem Web-code vorliegen, können Sie sie nach dem Launch verbessern mit Capgo Live-Updates anstatt auf eine neue App-Store-Version zu warten. Änderungen an native code, einschließlich Plugin-Updates, benötigen immer noch eine Store-Veröffentlichung, die Sie im Cloud mit Capgo Build.

Kundenfehler und Lösungen

Abschluss

Apple Intelligence bringt eine kostenlose, private, offline-Sprachmodell auf jeden geeigneten iPhone mit iOS 26 und eine Capacitor-App kann es mit wenigen Zeilen TypeScript nutzen. Wählen Sie das Modell, schalten Sie die UI auf getReadiness()halten Sie jede Aufgabe in einer kurzen Chat-Box, streamen Sie Snapshots in die UI und behandeln Sie Ablehnungen und Kontextfehler als normale Ergebnisse. Für eine umfassendere Betrachtung der Versendung von AI-Funktionen in hybriden Apps lesen Sie warum Capacitor gut für AI-Mobil-Apps geeignet ist.