Cómo utilizar Inteligencia de Apple en una aplicación Capacitor

Para utilizar Inteligencia de Apple en una Capacitor aplicación, instale @capgo/capacitor-llmllame setModel({ path: 'Apple Intelligence' })verifique getReadiness(), luego crea un chat y envía respuestas a través del textFromAi El plugin utiliza en su interior el marco de trabajo de Apple Foundation Models, introducido con iOS 26, que ejecuta el modelo de lenguaje en dispositivo de Apple sin ninguna clave API, sin costo por solicitud y sin datos que salgan del teléfono.

Esta guía cubre lo que ofrece el marco de trabajo, los requisitos del dispositivo, una integración completa de TypeScript, la ventana de contexto de 4.096 tokens, el manejo de errores, las notas de revisión de la aplicación y cómo el mismo code se ejecuta en Android.

What Apple Intelligence offers app developers

Con iOS 26, Apple abrió su modelo de fundación en dispositivo a las aplicaciones de terceros a través de Modelos Fundamentales framework. En Swift trabajas con SystemLanguageModel y LanguageModelSessionEl plugin envuelve esos para que tu web code pueda utilizarlos:

El modelo tiene aproximadamente 3 mil millones de parámetros. Es bueno para resumir, reescribir, extraer, clasificar y generación de corta forma. No es una sustitución para un modelo de nube grande en preguntas de conocimiento abierto, y Apple dice lo mismo en su propia guía. Diseñe características alrededor del texto que el usuario ya tiene.

Requisitos del dispositivo y del sistema

If su proyecto aún compila con una versión anterior de Xcode, consulte Requisito de Xcode 26 de Apple para aplicaciones Capacitor. No necesita cambiar el objetivo de despliegue mínimo de su aplicación. El plugin admite iOS 15 y posterior y solo modifica los modelos de Fundación en iOS 26.

Instale el plugin

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

Use el plugin 8.x con Capacitor 8. No se necesitan claves ni permisos de Info.plist para Inteligencia de Apple. Si aún está en Capacitor 7, el Guía de actualización de Capacitor 8 vienen primero. Documentación de referencia: /docs/plugins/llm/.

Paso 1: Seleccione el modelo y verifique la disponibilidad

setModel({ path: 'Apple Intelligence' }) selecciona el modelo del sistema y resuelve de inmediato. La disponibilidad real proviene de getReadiness(), que mapea el enum de disponibilidad de Apple a cadenas legibles:

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

Revisa de nuevo cuando la aplicación regrese al primer plano. Los usuarios a menudo habilitan la Inteligencia de Apple después de ver su sugerencia, y el modelo de descarga puede terminar mientras su aplicación está en segundo plano.

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

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

Step 2: Crea un chat con instrucciones

Un chat se mapea a uno LanguageModelSessionque mantiene el historial de conversación. Los caracteres createChat() que se escriben no tienen opciones, así que coloca tus instrucciones al principio del primer mensaje:

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

Utiliza un chat por tarea. Un chat que sigue creciendo eventualmente alcanzará el límite de contexto descrito a continuación.

Step 3: Transmite la respuesta en la interfaz de usuario

En iOS, cada textFromAi evento lleva un snapshot de la respuesta hasta el momento, porque así es cómo Foundation Models transmite. En Android con Gemini Nano, los eventos llevan solo el texto nuevo. Este helper maneja ambos y resuelve con el texto final:

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

Colocar todo en orden: resumen notas en el 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);
}

El slice es un guardián crudo contra grandes entradas. Una mejor aproximación es resumir documentos largos en trozos y luego resumir los resúmenes, cada uno en un chat fresco.

In un componente de marco, deshabilita el botón mientras ask se ejecuta. El plugin rechaza un segundo sendMessage en el mismo chat con “el chat está respondiendo, por favor espere antes de hacer nuevas preguntas”.

La ventana de contexto de 4.096 tokens

La ventana de contexto del modelo en el dispositivo tiene 4.096 tokens. Todo cuenta hacia ella: instrucciones, cada turno previo en el chat, el nuevo prompt y la respuesta generada. Cuando una sesión supera este tamaño, los modelos de fundamento lanzan un error de ‘tamaño de ventana de contexto superado’, que llega a usted como un generationError evento y un rechazo sendMessage.

Reglas prácticas:

• Una conversación por tarea, no una conversación por pantalla.
• Mantén las instrucciones cortas y específicas.
• Para conversaciones de múltiples turnos, inicia un nuevo chat cuando se vuelve largo y pasa un resumen breve de la conversación anterior.
• Pide una salida concisa. Las respuestas largas usan el mismo presupuesto.

Tunear la salida

On el camino de Inteligencia de Apple, el plugin utiliza los ajustes de generación predeterminados del sistema. temperature, topk, y maxTokens en setModel aplican a los caminos personalizados de LiteRT-LM y MediaPipe. Para guiar el modelo de Apple, confíe en la solicitud: diga cuánto tiempo debe durar la respuesta, proporcione el formato (puntos, JSON, una oración) y incluya un ejemplo breve cuando el formato importe.

El mismo code en Android

Sólo cambia la selección del modelo:

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

En Android, setModel rechaza cuando Gemini Nano no está disponible, y puede recurrir a un modelo descargable Gemma a través del mismo plugin. Los detalles están en ¿cómo usar Gemini Nano en una Capacitor aplicación.

Pruebas

• Dispositivo real: el camino fiable. Utilice un iPhone compatible en iOS 26 con Inteligencia de Apple en.
• Simulador: puede utilizar el modelo cuando el Mac anfitrión ejecuta macOS 26 en Apple silicon con Apple Intelligence habilitado. El comportamiento y la velocidad difieren de un teléfono, por lo que confirme en hardware.
• Estados no soportados: test with Apple Intelligence turned off to check your “enable in Settings” UI, and on an older iPhone or iOS version to check that the feature hides cleanly.

Revisión de la aplicación y privacidad

Las solicitudes y respuestas se mantienen en el dispositivo, por lo que la generación en el dispositivo no agrega ninguna recolección de datos a su etiqueta de privacidad por sí sola. Dos cosas siguen siendo para usted:

1. Apple publica los requisitos de uso aceptables para el marco de modelos de la Fundación. Lea antes de enviar, especialmente para características que generan contenido mostrado a otros usuarios.
2. El modelo tiene guardarreos integrados y puede rechazar algunas solicitudes o salidas. Trate una negativa como un resultado normal y muestre un mensaje claro.

Desde que las solicitudes son cadenas simples en tu web code, puedes mejorarlas después del lanzamiento con actualizaciones en vivo de Capgo 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 Construcción.

Errores comunes y soluciones

Resumen

Apple Intelligence trae un modelo de lenguaje gratuito, privado y offline a cada iPhone elegible en iOS 26, y una aplicación Capacitor puede utilizarlo con unas pocas líneas de TypeScript. Seleccionar el modelo, bloquear la UI en getReadiness()mantener cada tarea en su propio chat corto, enviar capturas en tiempo real a la UI, y manejar rechazos y errores de contexto como resultados normales. Para una visión más amplia sobre la entrega de características de IA en aplicaciones híbridas, lee por qué Capacitor funciona bien para aplicaciones móviles de IA.