Apple Intelligence in einer Capacitor-App verwenden

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

Dieses Leitfaden deckt die von dem Framework angebotenen Funktionen, die Geräteanforderungen, eine vollständige TypeScript-Integration, die 4.096-Token-Kontextfenster, die Fehlerbehandlung, die App-Review-Hinweise und wie das gleiche code auf Android läuft ab.

Was Apple Intelligence app-Entwicklern bietet

Mit iOS 26 hat Apple sein on-device-Grundmodell den dritten-Partei-Anwendungen durch das Foundation-Modelle framework. In Swift arbeiten Sie mit SystemLanguageModel und LanguageModelSessionDie Erweiterung hüllt diese ein, damit Ihre Web- code sie nutzen kann:

Das Modell hat etwa 3 Milliarden Parameter. Es ist gut darin, Zusammenfassungen zu erstellen, zu überarbeiten, zu extrahieren, zu klassifizieren und kurze Texte zu generieren. Es ist kein Ersatz für ein großes Cloudmodell bei offenen Fragen zum Wissensstand, und Apple sagt das auch in seiner eigenen Anleitung. Entwerfen Sie Funktionen um Text, den der Benutzer bereits hat.

Geräte- und Betriebssystemanforderungen

If Ihr Projekt noch mit einem älteren Xcode compiliert, sehen Sie sich an Apple’s Xcode 26-Anforderung für Capacitor-Apps. Ihr Apps Mindestversion muss nicht geändert werden. Die Erweiterung unterstützt iOS 15 und später und berührt nur die Foundation-Modelle auf iOS 26.

Installieren Sie die Erweiterung

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

Verwenden Sie die Erweiterung 8.x mit Capacitor 8. Keine Info.plist-Schlüssel oder Berechtigungen sind erforderlich für Apple Intelligence. Wenn Sie noch auf Capacitor 7 sind, kommt die Capacitor 8-Upgrade-Anleitung 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 kommt von getReadiness(), das Apple's Verfügbarkeit-Enum auf lesbare Zeichenketten abbildet.

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üfen Sie erneut, wenn die App wieder in den Vordergrund rückt. Benutzer aktivieren Apple Intelligence oft nachdem sie Ihre Hinweise gesehen haben, und der Modelldownload kann abgeschlossen werden, während Ihre App im Hintergrund ist.

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

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

Schritt 2: Erstellen Sie einen Chat mit Anweisungen

Ein Chat entspricht einem LanguageModelSession, der die Konversationshistorie aufbewahrt. Der createChat() nimmt keine Optionen an, daher sollten Sie Ihre Anweisungen am Anfang der ersten Nachricht einfügen:

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 wachsendes Chatfenster wird schließlich die unterhalb beschriebene Kontextbegrenzung erreichen.

Schritt 3: Streamen Sie die Antwort in die UI

Bei iOS trägt jeder textFromAi einen Snapshot der Antwort so lange mit, weil das so Foundation Models streamt. Bei Android mit Gemini Nano trägt jeder nur den neuen Text. Dieser Helper handhabt beide und liefert die endgültige Text:

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

Der slice ist ein grober Wächter 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 einen zweiten sendMessage auf demselben Chat mit „der Chat antwortet, bitte warten Sie, bevor Sie neue Fragen stellen“

Der 4.096-Token-Kontextfenster

The on-device model has a context window of 4,096 tokens. Everything counts toward it: instructions, every previous turn in the chat, the new prompt, and the response being generated. When a session exceeds it, Foundation Models throws an “exceeded context window size” error, which reaches you as a generationError Praktische Regeln: sendMessage.

Praktische Regeln:

• Eine Chat-Funktion pro Aufgabe, nicht eine pro Bildschirm.
• Halte Anweisungen kurz und spezifisch.
• Für mehrsprachige Chatdialoge, starten Sie einen neuen Chat, wenn er zu lang wird, und übergeben Sie einen kurzen Abriss der vorherigen Konversation.
• Bitten Sie nach kurzen Antworten. Langwierige Antworten nutzen den gleichen Budget.

Anpassung der Ausgabe

On der Apple Intelligence Route verwendet das Plugin die Systemeinstellungen für die Generation. temperature, topk, und maxTokens und setModel gelten für die benutzerdefinierten LiteRT-LM- und MediaPipe-Modellpfade. Um Apples Modell zu steuern, verlassen Sie sich auf die Anweisung: Sagen Sie, wie lange die Antwort sein soll, geben Sie die Formatierung (Kugeln, JSON, eine Sätze) an und fügen Sie ein kurzes Beispiel hinzu, wenn die Formatierung relevant ist.

Das Gleiche code auf Android

Nur die Modellauswahl ändert sich:

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

On Android setModel wird abgelehnt, wenn Gemini Nano nicht verfügbar ist, und Sie können auf ein herunterladbares Gemma-Modell durch das gleiche Plugin zurückgreifen. Die Details finden Sie in wie Sie Gemini Nano in einer Capacitor-App verwenden.

Testen

• Realgerät: der zuverlässige Weg. Verwenden Sie ein unterstütztes iPhone auf iOS 26 mit Apple Intelligence.
• Simulator: Es kann das Modell verwenden, wenn der Host-Mac macOS 26 auf Apple-Silicon mit Apple Intelligence aktiviert ist. Der Verhalten und die Geschwindigkeit unterscheiden sich von einem Telefon, daher sollte man sich auf Hardware bestätigen.
• Unbekannte Zustände: Testen Sie Apple Intelligence ausgeschaltet, um Ihre 'Ermöglichen 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 auf-Gerät-Generierung keine Datenerfassung zu Ihrem Datenschutzeintrag hinzufügt. Zwei Dinge sind noch auf Ihnen:

1. Apple veröffentlicht die akzeptablen Verwendungsvorschriften für das Framework der Foundation-Modelle. Lesen Sie sie, bevor Sie es ausliefern, insbesondere für Funktionen, die Inhalte anzeigen, die anderen Benutzern gezeigt werden.
2. Das Modell hat eingebaute Wächter und kann einige Anfragen oder Ausgaben ablehnen. Behandeln Sie eine Ablehnung als normales Ergebnis und zeigen Sie eine klare Nachricht.

Da Anfragen einfache Zeichenketten in Ihrem Web-code sind, können Sie sie nach dem Launch verbessern mit Capgo Live-Updates instead of waiting for a new App Store build. Changes to native code, including plugin upgrades, still need a store release, which you can build in the cloud with Capgo Build.

"Häufige Fehler und Lösungen"

Abschluss

Apple Intelligence bringt eine kostenlose, private, offline-Langmodell auf jeden geeigneten iPhone mit iOS 26 und eine Capacitor-App kann es mit wenigen Zeilen TypeScript verwenden. Wählen Sie das Modell, schalten Sie die UI auf getReadiness()halten Sie jede Aufgabe in einem eigenen kurzen Chat, streamen Sie Snapshots in die UI und behandeln Sie Verweigerungen und Kontextfehler als normale Ergebnisse. Für einen umfassenderen Überblick über die Bereitstellung von AI-Funktionen in hybriden Apps lesen Sie warum Capacitor gut für AI-Mobilapps funktioniert.