快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

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

然后使用以下 prompt：

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

常见坑点

• Web 离线模式：MediaPipe GenAI 从 CDN 加载，请缓存 runtime 和模型以进行离线演示。
• Android Gemini Nano：并非所有设备都支持，请处理 fallback 模型。
• 流式传输：请提前绑定监听器 sendMessage 以免错过 token。

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

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-llm 在“使用 @capgo/capacitor-llm”中实现原生能力， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。