Wie Sie 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 Stream-Abfrage 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 keiner 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, Fehlerbehandlung, App-Review-Hinweise und die Möglichkeit ab, dass das gleiche code auf Android läuft.

Was Apple Intelligence app-Entwicklern bietet

Mit iOS 26 hat Apple sein on-device-Foundation-Modell dritten Parteien durch das Foundation Models framework. In Swift arbeiten Sie mit SystemLanguageModel und LanguageModelSession. Das Plugin umschließt diese, so dass Ihre Web code sie verwenden kann:

Das Modell verfügt über etwa 3 Milliarden Parameter. Es ist gut in der Zusammenfassung, Umwandlung, Extraktion, Klassifizierung und kurzen Texten geeignet. Es ist kein Ersatz für ein großes Cloudmodell bei offenen Fragen zur Wissensverteilung und Apple sagt das auch in seiner eigenen Leitlinie. 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 Apple’s Xcode 26-Anforderung für Capacitor-Apps. Die Mindestversion Ihres Apps-Bereitstellungsziels muss nicht geändert werden. Der Plugin unterstützt iOS 15 und später und berührt nur die Foundation-Modelle auf iOS 26.

Installieren Sie das Plugin

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

Verwenden Sie das Plugin 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 das Capacitor 8 Upgrade-Guide zuerst. Referenzdokumentation: /docs/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 Ihren Hinweis gesehen haben, und der Modell-Download 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. Das Eingeben 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 die Foundation-Modelle streamen. Bei Android mit Gemini Nano tragen die Ereignisse nur den neuen Text. Diese Hilfsmethode 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 die 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 zusammenfassen und dann die Zusammenfassungen in einem neuen Chat zusammenzufassen.

In einer Framework-Komponente den Button während ask es läuft. Der Plugin lehnt einen zweiten sendMessage auf derselben Chat mit „Der Chat antwortet, bitte warten Sie, bevor Sie neue Fragen stellen“ ab.

Die 4.096-Token-Bereichsgröße

Der Modell auf dem Gerät hat eine Bereichsgröße von 4.096 Token. Alles zählt dazu: Anweisungen, jede vorherige Runde im Chat, der neue Prompt und die generierte Antwort. Wenn eine Sitzung diese überschreitet, werfen die Foundation-Modelle einen „Bereichsgröße überschritten“-Fehler aus, der sich als generationError ein Ereignis und ein abgelehntes sendMessage.

Praktische Regeln:

• Eine Chat-Funktion pro Aufgabe, nicht eine pro Bildschirm.
• Beibehalten Sie Anweisungen kurz und spezifisch.
• Bei mehreren Runden im Chat starten Sie einen neuen Chat, wenn er lang wird und übermitteln Sie eine kurze Zusammenfassung der früheren Konversation.
• Fordern Sie eine kurze Ausgabe an. Lange Antworten nutzen den gleichen Budget.

Anpassen der Ausgabe

On der Apple Intelligence Bahn verwendet das Plugin die Systemeinstellungen für die Standardgenerierung. 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 lang 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 mit Apple Silicon und Apple Intelligence aktiviert ist. Der Verhalten und die Geschwindigkeit unterscheiden sich von einem Smartphone, daher sollte man sich auf Hardware bestätigen.
• Unbekannte Zustände: Testen Sie Apple Intelligence ausgeschaltet, um Ihre "Einstellungen aktivieren"-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 jedoch noch auf Sie:

1. Apple veröffentlicht die akzeptablen Verwendungsvorschriften für das Framework der Foundation-Modelle. Lesen Sie sie vor der Veröffentlichung, 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 anstatt auf eine neue App-Store-Version zu warten. Änderungen an nativen code, einschließlich Plugin-Updates, benötigen immer noch eine Store-Veröffentlichung, die Sie im Cloud mit Capgo Build.

Häufige Fehler und Lösungen

Abschluss

Apple Intelligence bringt eine kostenlose, private, offline-fähige Sprachmodell zu jedem auf iOS 26 geeigneten iPhone und eine Capacitor-App kann es mit wenigen Zeilen TypeScript verwenden. Wählen Sie das Modell, schalten Sie die Benutzeroberfläche auf getReadiness()Halten Sie jede Aufgabe in einem kurzen Chat, streamen Sie Snapshots in die Benutzeroberfläche und behandeln Sie Ablehnungen und Kontextfehler als normale Ergebnisse. Für eine umfassendere Betrachtung der Lieferung von AI-Funktionen in hybriden Apps lesen Sie Warum Capacitor gut für AI-Mobilanwendungen funktioniert.