시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-llm` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-llm
bunx cap sync

가져오기

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

빠른 시작

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

const { id: chatId } = await CapgoLLM.createChat();
await CapgoLLM.sendMessage({ chatId, message: 'Summarize this error log.' });

이벤트 리스닝: textFromAi, aiFinished, 그리고 generationError 플러그인 README에 문서화된 대로 채팅 세션에서 수신하세요.

예시: UI 전 준비 상태

const { readiness } = await CapgoLLM.getReadiness();
if (readiness !== 'ready') {
  showModelDownloadScreen();
}

예시: 커스텀 모델 다운로드

await CapgoLLM.downloadModel({ url: 'https://cdn.example.com/model.litertlm' });

자주 하는 실수

• 웹 오프라인 모드: MediaPipe GenAI는 CDN에서 로드되므로, 오프라인 데모를 위해 런타임과 모델을 캐싱하세요.
• Android Gemini Nano: 모든 기기에서 지원되지 않으므로, 폴백(fallback) 모델을 처리해야 합니다.
• 스트리밍: 토큰을 놓치지 않도록 미리 sendMessage 리스너를 연결하세요.

API 개요

createChat

새 채팅 세션을 생성합니다

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

const result = await CapgoLLM.createChat();
console.log(result);

sendMessage

특정 채팅 세션의 AI에게 메시지를 보냅니다

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

await CapgoLLM.sendMessage({
  chatId: 'chat-id-123',
  message: 'Hello from Capacitor',
});

getReadiness

LLM의 준비 상태를 확인합니다

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

const result = await CapgoLLM.getReadiness();
console.log(result);

setModel

모델 설정을 지정합니다

• iOS: 시스템 모델 경로로 “Apple Intelligence”를 사용하거나 MediaPipe 모델 경로를 제공하세요
• Android: MediaPipe 모델 파일 경로 (assets 또는 files 디렉토리)

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

await CapgoLLM.setModel({
  path: 'path/to/file',
  modelType: 'task',
});

downloadModel

URL에서 모델을 다운로드하여 적절한 위치에 저장합니다

• iOS: 앱의 documents 디렉토리에 다운로드합니다
• Android: 앱의 files 디렉토리에 다운로드합니다

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

const result = await CapgoLLM.downloadModel({ url: 'https://example.com' });
console.log(result);

타입 레퍼런스

ModelOptions

모델 설정 옵션

export interface ModelOptions {
  /** Model path or "Apple Intelligence" for iOS system model */
  path: string;
  /** Model file type/extension (e.g., "task", "bin", "litertlm"). If not provided, will be extracted from path. */
  modelType?: string;
  /** Maximum number of tokens the model handles */
  maxTokens?: number;
  /** Number of tokens the model considers at each step */
  topk?: number;
  /** Amount of randomness in generation (0.0-1.0) */
  temperature?: number;
  /** Random seed for generation */
  randomSeed?: number;
}

DownloadModelOptions

모델 다운로드 옵션입니다.

export interface DownloadModelOptions {
  /** URL of the model file to download */
  url: string;
  /** Optional: URL of companion file (e.g., .litertlm for Android) */
  companionUrl?: string;
  /** Optional: Custom filename (defaults to filename from URL) */
  filename?: string;
}

DownloadModelResult

모델 다운로드 결과입니다.

export interface DownloadModelResult {
  /** Path where the model was saved */
  path: string;
  /** Path where the companion file was saved (if applicable) */
  companionPath?: string;
}

TextFromAiEvent

AI로부터 수신한 텍스트 이벤트 데이터입니다.

export interface TextFromAiEvent {
  /** The text content from AI - this is an incremental chunk, not the full text */
  text: string;
  /** The chat session ID */
  chatId: string;
  /** Whether this is a complete chunk (true) or partial streaming data (false) */
  isChunk?: boolean;
}

AiFinishedEvent

AI 작업 완료 이벤트 데이터입니다.

export interface AiFinishedEvent {
  /** The chat session ID that finished */
  chatId: string;
}

DownloadProgressEvent

다운로드 진행 상황에 대한 이벤트 데이터입니다.

export interface DownloadProgressEvent {
  /** Percentage of download completed (0-100) */
  progress: number;
  /** Total bytes to download */
  totalBytes?: number;
  /** Bytes downloaded so far */
  downloadedBytes?: number;
}

ReadinessChangeEvent

준비 상태 변경에 대한 이벤트 데이터입니다.

export interface ReadinessChangeEvent {
  /** The readiness status */
  readiness: string;
}

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-llm 사용하기 @capgo/capacitor-llm 사용하기의 네이티브 기능에 대해서는, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.