On-device LLM для Capacitor

@capacitor/local-llm — нативный плагин Capacitor для запуска LLM на устройстве использует Apple Intelligence (Foundation Models) на iOS и Gemini Nano на Android. Никаких сетевых запросов, никаких API-ключей, никаких данных, покидающих устройство.

1. Установка

npm install @capacitor/local-llm
npx cap sync

2. Требования к платформам

3. Настройка iOS

Никакой дополнительной конфигурации не требуется. Foundation Models и Image Playground — системные фреймворки, доступные автоматически на поддерживаемых устройствах с включённым Apple Intelligence.

Вызывайте systemAvailability() в рантайме, чтобы проверить, готова ли модель к работе, прежде чем отправлять промпты.

На iOS 18 и ниже systemAvailability() вернёт 'unavailable' для text LLM. Если вызвать prompt() или warmup() в любом случае — промис упадёт с ошибкой. Генерация изображений через generateImage() полностью работает на iOS 18.4+.

4. Настройка Android

Минимальный Android SDK плагина — 28, выше текущего минимума Capacitor (24). Нужно изменить android/variables.gradle:

ext {
    minSdkVersion = 28
}

Gemini Nano распространяется через Google Play Services и должен быть загружен на устройство отдельно — модель не входит в комплект приложения.

Проверка и загрузка

Вызовите systemAvailability() чтобы узнать статус. Если статус downloadable — запустите загрузку через download() и опрашивайте systemAvailability() пока статус не станет available.

import { LocalLLM } from '@capacitor/local-llm';

const { status } = await LocalLLM.systemAvailability();

if (status === 'downloadable') {
  await LocalLLM.download();
  // Опрашиваем systemAvailability() пока status !== 'available'
  // Или используем addListener('systemAvailabilityChange', {})
}

5. Ограничения платформ

6. Использование

Базовый промпт

import { LocalLLM } from '@capacitor/local-llm';

const { text } = await LocalLLM.prompt({
  prompt: 'Объясни теорию относительности в одном абзаце.',
});

console.log(text);

Многошаговый диалог

Используйте sessionId для сохранения контекста между промптами.

import { LocalLLM } from '@capacitor/local-llm';

const sessionId = 'my-chat-session';

await LocalLLM.prompt({
  sessionId,
  instructions: 'Ты полезный ассистент.',
  prompt: 'Какая столица Франции?',
});

const { text } = await LocalLLM.prompt({
  sessionId,
  prompt: 'Какое население у этого города?',
});

// Очистка после завершения
await LocalLLM.endSession({ sessionId });

Warmup — снижаем задержку первого ответа

import { LocalLLM } from '@capacitor/local-llm';

// Пре-инициализация модели до того, как пользователь начал печатать
await LocalLLM.warmup({
  sessionId: 'my-session',
  promptPrefix: 'Ты — агент поддержки компании Acme Corp.',
});

Генерация изображений (только iOS)

import { LocalLLM } from '@capacitor/local-llm';

const { pngBase64Images } = await LocalLLM.generateImage({
  prompt: 'Горное озеро на рассвете, фотореализм',
  count: 2,
});

// Используем прямо в <img>
const src = `data:image/png;base64,${pngBase64Images[0]}`;

7. Обработка ошибок

Все методы плагина выбрасывают LocalLLMException при ошибке. Он расширяет Error и добавляет машиночитаемый код LocalLLMErrorCode.

import { LocalLLM, LocalLLMException } from '@capacitor/local-llm';

try {
  await LocalLLM.prompt({ prompt: 'Привет' });
} catch (err) {
  if (err instanceof LocalLLMException) {
    console.log(err.code);    // напр. 'LOCAL_LLM_NOT_ENABLED'
    console.log(err.message); // человекочитаемое описание
  }
}

Коды ошибок

8. Справочник API

systemAvailability()

Проверяет доступность on-device LLM. Определяет, готова ли модель, нужно ли её загрузить, или она недоступна на данном устройстве.

Возвращает: Promise<SystemAvailabilityResponse> со статусом status: LLMAvailability

download()

Загружает on-device LLM модель. Только на Android.

Возвращает: Promise<void>

prompt(options)

Отправляет промпт on-device LLM и получает ответ. Можно указать sessionId для поддержания контекста беседы.

Параметры: PromptOptions — текст промпта и опциональные настройки (температура, макс. токены и т.д.)

Возвращает: Promise<PromptResponse>

endSession(options)

Завершает активную сессию LLM. Важно для освобождения памяти и предотвращения утечек ресурсов.

Параметры: EndSessionOptions — идентификатор сессии

Возвращает: Promise<void>

generateImage(options)

Генерирует изображения из текстового описания. Возвращает массив PNG в base64. Доступно только на iOS 18.4+.

Параметры: GenerateImageOptions — промпт, количество, опциональные референсные изображения

Возвращает: Promise<GenerateImageResponse> — { pngBase64Images: string[] }

warmup(options)

Прогревает on-device LLM для более быстрых первых ответов. Пре-инициализирует модель с промпт-профиксом, снижая задержку первого запроса.

Возвращает: Promise<void>

addListener('systemAvailabilityChange', callback)

Подписывается на изменения статуса доступности on-device LLM. Опрос начинается с добавлением первого слушателя и останавливается после removeAllListeners().

removeAllListeners()

Удаляет все подписки и останавливает опрос статуса.