Come utilizzare l'intelligenza Apple in un'app Capacitor

Per utilizzare l'intelligenza Apple in un'app Capacitor, installa @capgo/capacitor-llmchiamare setModel({ path: 'Apple Intelligence' })verificare getReadiness()poi, quindi crea un chat e invia le risposte attraverso l' textFromAi evento. Sotto la cappa il plugin utilizza il framework di modelli di fondazione di Apple, introdotto con iOS 26, che esegue il modello di linguaggio di Apple sul dispositivo con nessun API chiave, nessun costo per richiesta e nessun dati che lasciano il telefono.

Questa guida copre cosa offre il framework, le richieste del dispositivo, un'integrazione completa di TypeScript, la finestra di contesto di 4.096 token, il trattamento degli errori, le note di App Review e come lo stesso code funziona su Android.

Cosa offre Apple Intelligence agli sviluppatori di app

Con iOS 26, Apple ha aperto il suo modello di fondazione sul dispositivo ai terzi app tramite il framework di modelli di fondazione. framework. In Swift lavori con SystemLanguageModel e LanguageModelSessionIl plugin avvolge questi in modo che il tuo web code possa utilizzarli:

Il modello è di circa 3 miliardi di parametri. È bravo a riassumere, a riscrivere, a estrarre, a classificare e a generare testi brevi. Non è una sostituzione per un grande modello cloud per domande di conoscenza aperte, e Apple lo dice anche nella sua guida. Progettare le funzionalità del testo che l'utente ha già.

Requisiti del dispositivo e del sistema operativo

If il tuo progetto continua a compilare con un Xcode più vecchio, vedi Richiesta di Xcode 26 di Apple per applicazioni Capacitor. Il tuo app minimo di deployment non deve cambiare. Il plugin supporta iOS 15 e successivi e tocca solo i Modelli di Fondazione su iOS 26.

Installa il plugin

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

Usa il plugin 8.x con Capacitor 8. Non sono necessarie chiavi o entità Info.plist per l'intelligenza Apple. Se sei ancora su Capacitor 7, la guida di aggiornamento di Capacitor 8 Capacitor 8 upgrade guide Arriva per primo. Documentazione di riferimento: /docs/plugins/llm/.

Passo 1: Seleziona il modello e verifica la disponibilità

setModel({ path: 'Apple Intelligence' }) seleziona il modello del sistema e risolve subito. La reale disponibilità deriva da getReadiness(), che mappa l'enum di disponibilità di Apple a stringhe leggibili:

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

Controlla nuovamente quando l'app torna in primo piano. Gli utenti spesso abilitano l'intelligenza Apple dopo aver visto il tuo suggerimento, e il download del modello può completarsi mentre la tua app è in background.

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

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

Passo 2: Crea un chat con istruzioni

Una chat corrisponde a uno LanguageModelSessionche mantiene la storia della conversazione. Il testo createChat() non accetta opzioni, quindi inserisci le tue istruzioni all'inizio del primo messaggio:

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

Usa un chat per compito. Un chat che continua a crescere raggiungerà eventualmente il limite di contesto descritto di seguito.

Passo 3: Influisce la risposta nella UI

Su iOS, ogni textFromAi evento porta con sé un snapshot della risposta fino a quel momento, perché è così che i modelli di fondazione trasmettono. Su Android con Gemini Nano, gli eventi trasportano solo il testo nuovo. Questo helper gestisce entrambi e risolve con il testo finale:

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

Mettilo insieme: riassumi note sul dispositivo

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

The slice è un guardiano crudo contro grandi input. Un approccio migliore è riassumere documenti lunghi in blocchi e poi riassumere i riassunti, ogni volta in un nuovo chat.

In un componente di framework, disabilita il pulsante mentre ask Esegue. Il plugin rifiuta un secondo sendMessage su lo stesso chat con “la chat sta rispondendo, attendi prima di chiedere nuove domande”.

La finestra di contesto di 4.096 token

La modello in dispositivo ha una finestra di contesto di 4.096 token. Tutto conta verso di essa: istruzioni, ogni turno precedente nella chat, il nuovo promemoria e la risposta generata. Quando una sessione supera i limiti, i Modelli di Fondazione lanciano un errore “dimensione della finestra di contesto superata” che raggiunge te come un generationError evento e un rifiuto sendMessage.

Regole pratiche:

• Una chat per compito, non una chat per schermo.
• Tieni le istruzioni brevi e specifiche.
• Per la chat multi-turno, inizia una nuova chat quando diventa lunga e passa una breve sintesi della conversazione precedente.
• Chiedi un output conciso. Le risposte lunghe utilizzano lo stesso budget.

Tuning dell'output

On Apple Intelligence, il plugin utilizza le impostazioni di generazione predefinite del sistema. temperature, topk, e maxTokens in setModel si applicano ai percorsi dei modelli personalizzati LiteRT-LM e MediaPipe. Per guidare il modello di Apple, si dipende dalla richiesta: dica quanto dovrebbe essere lunga la risposta, specifica il formato (punti, JSON, una frase), e includi un esempio breve quando il formato conta.

Lo stesso code su Android

Solo la selezione del modello cambia:

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

Su Android, setModel rifiuta quando il Gemini Nano non è disponibile, e si può ricorrere a un modello scaricabile Gemma attraverso lo stesso plugin. I dettagli sono in come utilizzare Gemini Nano in un'app Capacitor.

Testing

• Dispositivo reale: la via affidabile. Utilizza un iPhone supportato su iOS 26 con Apple Intelligence.
• Simulatore: può utilizzare il modello quando il Mac host esegue macOS 26 su Apple silicon con Apple Intelligence abilitato. Il comportamento e la velocità differiscono da un telefono, quindi confermare su hardware.
• Stati non supportati: testare con Apple Intelligence disabilitato per verificare la tua “abilita' nelle impostazioni” UI, e su un vecchio iPhone o versione iOS per verificare che la funzione nasconda pulitamente.

Recensione dell'app e privacy

I promemoria e le risposte rimangono sul dispositivo, quindi la generazione in locale non aggiunge alcuna raccolta di dati al tuo etichetta di privacy da solo. Due cose sono ancora su di te:

1. Apple pubblica le linee guida per l'uso accettabile per il framework dei Modelli di Fondazione. Leggerle prima di distribuire, soprattutto per le funzionalità che generano contenuti visualizzati dagli altri utenti.
2. Il modello ha dei limiti di sicurezza integrati e può rifiutare alcune richieste o output. Trattare un rifiuto come un risultato normale e mostrare un messaggio chiaro.

Dato che le richieste sono stringhe piane nel tuo web code, puoi migliorarle dopo il lancio con Capgo live updates al posto di attendere una nuova versione del negozio. Le modifiche ai nativi code, compresi gli aggiornamenti dei plugin, richiedono ancora una versione del negozio, che puoi costruire in cloud con Capgo Build.

Error comuni e soluzioni

Riassunto

Apple Intelligence porta un modello di linguaggio gratuito, privato e offline su ogni iPhone idoneo su iOS 26, e un'app Capacitor può utilizzarlo con poche righe di TypeScript. Seleziona il modello, blocca l'interfaccia utente su getReadiness()mantieni ogni compito nella sua breve chat, invia snapshot nell'interfaccia utente e gestisci rifiuti e errori di contesto come esiti normali. Per una visione più ampia sulla spedizione di funzionalità AI in app ibride, leggi perché Capacitor funziona bene per app mobili AI.