Empezando

Instalación

npm

npm install @capgo/capacitor-llm
npx cap sync

yarn

yarn add @capgo/capacitor-llm
npx cap sync

pnpm

pnpm add @capgo/capacitor-llm
npx cap sync

bun

bun add @capgo/capacitor-llm
npx cap sync

Configuración de la plataforma

iOS Configuración

• iOS 26.0+: utiliza Apple Inteligencia de forma predeterminada (no se necesita modelo) - Recomendado
• iOS < 26.0: Requiere modelos personalizados de MediaPipe (experimental, puede tener problemas de compatibilidad)

Para modelos personalizados en versiones anteriores de iOS, coloque archivos de modelo en su paquete de aplicaciones iOS a través de “Copiar recursos del paquete” de Xcode.

Android Configuración

Coloque los archivos del modelo en su carpeta de activos Android:

android/app/src/main/assets/

Necesita ambos archivos para Android:

• Archivo .task (modelo principal)
• Archivo .litertlm (archivo complementario)

Descargar desde modelos Kaggle Gemma → pestaña “LiteRT (anteriormente TFLite)“

Modelos recomendados

Para Android (modelos Gemma-3)

• Gemma 3 270M - El más pequeño y eficiente para dispositivos móviles (~240-400 MB) - Recomendado
• Gemma 3 1B - Modelo de generación de texto más grande (~892 MB-1,5 GB)

Descargue desde [modelos Kaggle Gemma] (https://www.kaggle.com/models/google/gemma) → Haga clic en la pestaña “LiteRT (anteriormente TFLite)“

Para iOS

• Apple Inteligencia (iOS 26.0+) - Integrado, no necesita descarga - Recomendado
• Gemma-2 2B (experimental) - Puede tener problemas de compatibilidad con el formato .task

Para modelos iOS personalizados, descárguelos desde Modelos Hugging Face MediaPipe

Uso

Importe el complemento e inicialícelo:

import { CapgoLLM } from '@capgo/capacitor-llm';
import { Capacitor } from '@capacitor/core';

// Check if LLM is ready
const { readiness } = await CapgoLLM.getReadiness();
console.log('LLM readiness:', readiness);

// Set the model based on platform
const platform = Capacitor.getPlatform();
if (platform === 'ios') {
  // iOS: Use Apple Intelligence (default)
  await CapgoLLM.setModel({ path: 'Apple Intelligence' });
} else {
  // Android: Use MediaPipe model
  await CapgoLLM.setModel({ path: '/android_asset/gemma-3-270m-it-int8.task' });
}

// Create a chat session
const { id: chatId } = await CapgoLLM.createChat();

// Listen for AI responses
CapgoLLM.addListener('textFromAi', (event) => {
  console.log('AI response:', event.text);
});

// Listen for completion
CapgoLLM.addListener('aiFinished', (event) => {
  console.log('AI completed response');
});

// Send a message
await CapgoLLM.sendMessage({
  chatId,
  message: 'Hello! How are you today?'
});

Funciones avanzadas

Descargar modelos

// Download a model from URL
await CapgoLLM.downloadModel({
  url: 'https://example.com/model.task',
  filename: 'model.task'
});

// For Android, download both .task and .litertlm files
await CapgoLLM.downloadModel({
  url: 'https://example.com/gemma-3-270m-it-int8.task',
  companionUrl: 'https://example.com/gemma-3-270m-it-int8.litertlm',
  filename: 'gemma-3-270m-it-int8.task'
});

// Listen for download progress
CapgoLLM.addListener('downloadProgress', (event) => {
  console.log(`Download progress: ${event.progress}%`);
  console.log(`Downloaded: ${event.downloadedBytes} / ${event.totalBytes}`);
});

Gestión de modelos

// Set a specific model with configuration
await CapgoLLM.setModel({
  path: '/android_asset/gemma-3-270m-it-int8.task',
  maxTokens: 2048,
  topk: 40,
  temperature: 0.8
});

// Check readiness
const { readiness } = await CapgoLLM.getReadiness();
if (readiness === 'ready') {
  // Model is loaded and ready
}

// Listen for readiness changes
CapgoLLM.addListener('readinessChange', (event) => {
  console.log('Readiness changed:', event.readiness);
});

API Métodos

crearChat()

Crea una nueva sesión de chat.

const { id: chatId } = await CapgoLLM.createChat();

Devoluciones: Promise<{ id: string; instructions?: string }>

enviar mensaje(…)

Envíe un mensaje al LLM.

await CapgoLLM.sendMessage({
  chatId: 'chat-id',
  message: 'What is the weather like?'
});

Parámetro	Tipo	Descripción
chatId	string	ID de sesión de chat
message	string	Mensaje para enviar

obtener preparación()

Verifique si el LLM está listo para usar.

const { readiness } = await CapgoLLM.getReadiness();

Devoluciones: Promise<{ readiness: string }>

Valores posibles:

• ready - El modelo está cargado y listo
• loading - Se está cargando el modelo
• not_ready - Modelo aún no cargado
• error - Error al cargar el modelo

establecerModelo(…)

Establezca la configuración del modelo.

// iOS: Use Apple Intelligence (recommended)
await CapgoLLM.setModel({
  path: 'Apple Intelligence'
});

// iOS: Use custom MediaPipe model (experimental)
await CapgoLLM.setModel({
  path: 'Gemma2-2B-IT_multi-prefill-seq_q8_ekv1280',
  modelType: 'task',
  maxTokens: 1280
});

// Android: Use MediaPipe model
await CapgoLLM.setModel({
  path: '/android_asset/gemma-3-270m-it-int8.task',
  maxTokens: 2048,
  topk: 40,
  temperature: 0.8
});
```| Parámetro | Tipo | Descripción |
| --------------- | -------- | ------------------------------------------------- |
| **`path`** | `string` | Ruta del modelo o "Apple Inteligencia" para el sistema iOS |
| **`modelType`** | `string` | Opcional: tipo de archivo de modelo (por ejemplo, "tarea", "bin") |
| **`maxTokens`** | `number` | Opcional: tokens máximos que maneja el modelo |
| **`topk`** | `number` | Opcional: Número de tokens considerados en cada paso |
| **`temperature`** | `number` | Opcional: Aleatoriedad en la generación (0,0-1,0) |
| **`randomSeed`** | `number` | Opcional: Semilla aleatoria para generación |

### descargarModelo(...)

Descargue un modelo desde la URL y guárdelo en el almacenamiento del dispositivo.

```typescript
await CapgoLLM.downloadModel({
  url: 'https://example.com/gemma-3-270m-it-int8.task',
  companionUrl: 'https://example.com/gemma-3-270m-it-int8.litertlm',
  filename: 'gemma-3-270m-it-int8.task'
});

Parámetro	Tipo	Descripción
url	string	URL para descargar desde
companionUrl	string	Opcional: URL del archivo complementario (.litertlm)
filename	string	Opcional: Nombre de archivo para guardar como

Devoluciones: Promise<{ path: string; companionPath?: string }>

Eventos

textoDeAi

Se activa cuando la IA genera texto (respuesta de transmisión).

CapgoLLM.addListener('textFromAi', (event) => {
  console.log('AI text:', event.text);
  console.log('Chat ID:', event.chatId);
  console.log('Is chunk:', event.isChunk);
});

Datos del evento:

• text (cadena) - Fragmento de texto incremental de AI
• chatId (cadena) - ID de sesión de chat
• isChunk (booleano): si se trata de un fragmento completo o de datos de transmisión parciales

aiTerminado

Se dispara cuando la IA completa la respuesta.

CapgoLLM.addListener('aiFinished', (event) => {
  console.log('Completed for chat:', event.chatId);
});

Datos del evento:

• chatId (cadena) - ID de sesión de chat

descargarProgreso

Activado durante la descarga del modelo para informar el progreso.

CapgoLLM.addListener('downloadProgress', (event) => {
  console.log('Progress:', event.progress, '%');
  console.log('Downloaded:', event.downloadedBytes, '/', event.totalBytes);
});

Datos del evento:

• progress (número) - Porcentaje de descarga completada (0-100)
• downloadedBytes (número) - Bytes descargados hasta el momento
• totalBytes (número) - Total de bytes para descargar

preparaciónCambiar

Se activa cuando cambia el estado de preparación del LLM.

CapgoLLM.addListener('readinessChange', (event) => {
  console.log('Readiness changed to:', event.readiness);
});

Datos del evento:

• readiness (cadena) - El nuevo estado de preparación

Ejemplo completo

import { CapgoLLM } from '@capgo/capacitor-llm';
import { Capacitor } from '@capacitor/core';

class AIService {
  private chatId: string | null = null;
  private messageBuffer: string = '';

  async initialize() {
    // Set up model based on platform
    const platform = Capacitor.getPlatform();

    if (platform === 'ios') {
      // iOS: Use Apple Intelligence (recommended)
      await CapgoLLM.setModel({ path: 'Apple Intelligence' });
    } else {
      // Android: Use MediaPipe model
      await CapgoLLM.setModel({
        path: '/android_asset/gemma-3-270m-it-int8.task',
        maxTokens: 2048,
        topk: 40,
        temperature: 0.8
      });
    }

    // Wait for model to be ready
    let isReady = false;
    while (!isReady) {
      const { readiness } = await CapgoLLM.getReadiness();
      if (readiness === 'ready') {
        isReady = true;
      } else if (readiness === 'error') {
        throw new Error('Failed to load model');
      }
      await new Promise(resolve => setTimeout(resolve, 500));
    }

    // Create chat session
    const { id } = await CapgoLLM.createChat();
    this.chatId = id;

    // Set up event listeners
    this.setupListeners();
  }

  private setupListeners() {
    CapgoLLM.addListener('textFromAi', (event) => {
      if (event.chatId === this.chatId) {
        this.messageBuffer += event.text;
        this.onTextReceived(event.text);
      }
    });

    CapgoLLM.addListener('aiFinished', (event) => {
      if (event.chatId === this.chatId) {
        this.onMessageComplete(this.messageBuffer);
        this.messageBuffer = '';
      }
    });
  }

  async sendMessage(message: string) {
    if (!this.chatId) {
      throw new Error('Chat not initialized');
    }

    await CapgoLLM.sendMessage({
      chatId: this.chatId,
      message
    });
  }

  onTextReceived(text: string) {
    // Update UI with streaming text
    console.log('Received:', text);
  }

  onMessageComplete(fullMessage: string) {
    // Handle complete message
    console.log('Complete message:', fullMessage);
  }
}

// Usage
const ai = new AIService();
await ai.initialize();
await ai.sendMessage('Tell me about AI');

Soporte de plataforma

Plataforma	Apoyado	Requisitos
iOS	✅	iOS 13.0+ (26.0+ para Apple Inteligencia)
Android	✅	API 24+
Web	❌	No compatible

Mejores prácticas

1. Selección de modelo: elija modelos según las capacidades del dispositivo

   • Utilice 270M para la mayoría de los dispositivos móviles
   • Utilice 1B para dispositivos de gama alta con más RAM
   • Pruebe el rendimiento en los dispositivos de destino.

2. Administración de memoria: borre las sesiones de chat cuando haya terminado

   // Create new chat for new conversations
   const { id } = await CapacitorLLM.createChat();

3. Manejo de errores: siempre verifique que esté listo antes de usar

   const { readiness } = await CapacitorLLM.getReadiness();
   if (readiness !== 'ready') {
     // Handle not ready state
   }

4. Interfaz de usuario de transmisión: actualice la interfaz de usuario de forma incremental con transmisión de texto

   • Mostrar texto tal como llega a través de onAiText
   • Marcar completo con onAiCompletion

5. Descarga de modelos: descarga modelos durante la configuración de la aplicación, no en el primer uso.

   // During app initialization
   await CapacitorLLM.downloadModel({
     url: 'https://your-cdn.com/model.task',
     filename: 'model.task'
   });

Solución de problemas### El modelo no se carga

• Verifique que el archivo del modelo esté en la ubicación correcta
• Verifique que el formato del modelo coincida con la plataforma (.gguf para iOS, .task para Android)
• Garantizar suficiente almacenamiento en el dispositivo

Mal desempeño

• Pruebe un modelo más pequeño (270M en lugar de 1B)
• Cierra otras aplicaciones para liberar memoria.
• Prueba en un dispositivo real, no en un simulador

Sin respuestas

• Verificar que el estado de preparación sea “listo”
• Verificar que los detectores de eventos estén configurados antes de enviar mensajes.
• Verifique la consola en busca de errores.

Recursos

• GitHub Repositorio
• Modelos Gemma
• Apple Inteligencia
• MediaPipe