@ capacor/ local- llm

[尖叫声]
CapacitorLABS - 这个项目是实验性的. 没有提供支助。 请在有需要时开放问题.

使用苹果智能(Foundation Models)在iOS上运行大型语言模型,并使用双子纳诺在Android上运行. 没有网络请求,没有API密钥,没有数据离开设备.

说明: On-device LLMs需要物理硬件. Android 模拟器不支持 。 只要主机设备能够运行Apple Intelligence并启用,iOS模拟器就会被支持.

安装

npm install @capacitor/local-llm
npx cap sync

平台要求

iOS 设置

不需要额外的配置。 基础模型和图像游乐场(Foundation Models and Image Playground)是Apple Intelligence启用后在所支持的设备上自动可用的系统框架.

打电话 systemAvailability() 在运行时检查模型是否准备好,然后发出提示.

关于iOS 18和以下, systemAvailability() 返回时 'unavailable' 用于文本 LLM。 若为 prompt() 或者说 warmup() 不管怎么说, 承诺将因错误而被拒绝。 图像生成通过 generateImage() 已在iOS 18.4+上全面运行.

Android 设置

该插件的最低和机器人SDK为28个,高于Capacitor目前的最低(24个). 你需要改变 android/variables.gradle 应用程序中的文件 :

ext {
    minSdkVersion = 28
}

双子纳米通过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();
  // Poll systemAvailability() until status === 'available'
  // Alternatively, use addListener('systemAvailabilityChange', {}) to get notified of status updates
}

平台限制

iOS系统

• Text LLM需要iOS 26和苹果智能. 关于iOS 18和以下, systemAvailability() 返回时 'unavailable' 文本 LLM 和 prompt() 编号 : warmup() 将拒绝。 只有选择iPhones(iPhone 15 Pro或后期)和iPads与Apple Intelligence兼容. 这里有更多信息。 。 。 .
• download() 在 iOS 上无法获取. 该模型由操作系统管理;使用 systemAvailability() 检查准备状态.
• 上下文限制为4096个符. 这适用于系统指令的综合长度,对话历史,以及当前快取.

机器人

• maximumOutputTokens 被夹到 1–256 由 ML Kit API 编辑 。 这一范围以外的价值观将受到胁迫.
• 多回合会话背景在记忆中管理 通过手动将对话历史集成到每个提示中。 它不是一个本地会话 API , 并且不会在应用程序重启时持续存在 .
• warmup() 忽略 sessionId 财务报告和审定财务报表 promptPrefix 在Android上——它让模型在全球暖和.
• 并非所有Android 9+设备都支持双子座纳米. 设备必须有一个相容的安装在device AI芯片上(例如像素9和后期). 这里有更多信息。 。 。 .
• 当应用程序处于背景状态时,无法使用在线设备模型 . 应用程序背景化时提出的推断请求将失败 .
• AICore执行每个应用程序的推论配额. 在短期内提出过多的请求将导致 BUSY 出错反应——重试时考虑指数回放. 一个 PER_APP_BATTERY_USE_QUOTA_EXCEEDED 如果应用程序超过更长的配额(例如每日限制),错误可以返回.

使用量

基本快捷键

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

const { text } = await LocalLLM.prompt({
  prompt: 'Summarize the theory of relativity in one paragraph.',
});

console.log(text);

多回合对话

使用一个 sessionId 以在多个提示中保持上下文.

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

const sessionId = 'my-chat-session';

await LocalLLM.prompt({
  sessionId,
  instructions: 'You are a helpful assistant.',
  prompt: 'What is the capital of France?',
});

const { text } = await LocalLLM.prompt({
  sessionId,
  prompt: 'What is the population of that city?',
});

// Clean up when done
await LocalLLM.endSession({ sessionId });

用热身来减少第一反应延迟

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

// Pre-initialize the model before the user starts typing
await LocalLLM.warmup({
  sessionId: 'my-session',
  promptPrefix: 'You are a customer support agent for Acme Corp.',
});

图像生成( 只有iOS)

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

const { pngBase64Images } = await LocalLLM.generateImage({
  prompt: 'A serene mountain lake at sunrise, photorealistic',
  count: 2,
});

// Use directly in an <img> tag
const src = `data:image/png;base64,${pngBase64Images[0]}`;

处理错误

所有插件方法抛出一个 LocalLLMException 失败。 它延伸 Error 并添加一个机器可读 code 类型属性 LocalLLMErrorCode。 。 。 .

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

try {
  await LocalLLM.prompt({ prompt: 'Hello' });
} catch (err) {
  if (err instanceof LocalLLMException) {
    console.log(err.code);    // e.g. 'LOCAL_LLM_NOT_ENABLED'
    console.log(err.message); // human-readable description
  }
}

LocalLLMErrorCode

API 密码

• systemAvailability()
• download()
• prompt(...)
• endSession(...)
• generateImage(...)
• warmup(...)
• addListener('systemAvailabilityChange', ...)
• removeAllListeners()
• 接口
• 类型异名

与device LLMs互动的主要插件接口.

可操作性( )

systemAvailability() => Promise<SystemAvailabilityResponse>

检查设备 LLM 的可用状态.

使用这种方法来确定LLM是否准备使用,需要下载, 或设备上没有.

回返情况: Promise<SystemAvailabilityResponse>

自: 1.0.0 (单位:千美元)

下载( )

download() => Promise<void>

下载在线设备 LLM 模型.

这种方法在LLM模型尚未下载时启动下载 显示在设备上。 只能从Android上找到.

自: 1.0.0 (单位:千美元)

提示(...)

prompt(options: PromptOptions) => Promise<PromptResponse>

发送一个提示到设备 LLM 并收到回复 .

使用这种方法与 LLM 交互. 您可以选择提供会话Id 以保持多个提示的对话环境.

回返情况: Promise<PromptResponse>

自: 1.0.0 (单位:千美元)

会议结束(...)

endSession(options: EndSessionOptions) => Promise<void>

结束活动 LLM 会话 .

用这种方法来清理资源,当您完成一个对话会话时. 这对于管理内存和防止资源泄漏很重要.

自: 1.0.0 (单位:千美元)

生成图像(...)

generateImage(options: GenerateImageOptions) => Promise<GenerateImageResponse>

使用 device LLM 从文本提示生成图像 .

使用这种方法创建基于文本描述的图像. 可选规定 参考图像来影响生成。 生成的图像被返回 在一个阵列中作为基础64-编码的 PNG 字符串.

回返情况: Promise<GenerateImageResponse>

自: 1.0.0 (单位:千美元)

热身(...)

warmup(options: WarmupOptions) => Promise<void>

暖和一下LLM 以更快的初始反应.

使用这种方法在 LLM 初始化前加一个快取前缀, 减少空闲度 第一个实际快速。 当您提前知道类型时,这个是有用的 通知你发送.

自: 1.0.0 (单位:千美元)

添加倾听器('system Available Change',...)

addListener(eventName: 'systemAvailabilityChange', listenerFunc: SystemAvailabilityChangeListener) => Promise<PluginListenerHandle>

当设备 LLM 可用性状态发生变化时,会调用它.

每次改变时都会以新的可用状态引用收听器. 投票 当第一个听众被添加时开始, 当所有听众被删除时停止 removeAllListeners()。 。 。 .

回返情况: Promise<PluginListenerHandle>

自: 1.0.0 (单位:千美元)

删除所有收听器( )

removeAllListeners() => Promise<void>

接口

系统可操作性响应

包含设备上LLM的系统可用状态的反应.

快速回复

LLM 处理后的反应 .

提示选项

向 LLM 发送提示的选项 .

LLM 选项

LLM 推断行为的配置选项 .

届会结束

结束活动 LLM 会话的选项 .

生成图像响应

包含生成的图像数据的反应 .

生成图像选项

从文本提示生成图像的选项 .

温暖选项

升温LLM的选项.

插件听筒

类型异名

法学硕士

设备LLM的可用性状况.

'available' | 'unavailable' | 'notready' | 'downloadable'

系统可操作性

当在线设备 LLM 可用性状态改变时,会引用回调 .

(response: SystemAvailabilityResponse): void