# @capacitor/local-llm 中文文档

规范地址：https://npmcn.com/package/%40capacitor/local-llm/

版本：1\.0\.0
npm 元数据更新时间：2026-09-28T18:17:24.490Z
中文译文更新时间：2026-11-09T09:11:23.469Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capacitor/local-llm
原文对照：https://npmcn.com/package/%40capacitor/local-llm/?lang=original
项目主页：https://github.com/ionic-team/capacitor-local-llm#readme
源码仓库：https://github.com/ionic-team/capacitor-local-llm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：116 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-05-11T15:21:18.711Z
- 最新版本发布：2026-05-11T15:38:39.125Z
- 近 30 天下载量：3123（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

一个用于运行在device LLMs上的Capacitor插件,支持文本生成,图像生成,以及iOS和Android上的会话管理.

## 安装

```sh
npm install @capacitor/local-llm
```

也可以使用：`pnpm add @capacitor/local-llm`、`yarn add @capacitor/local-llm`、`bun add @capacitor/local-llm`

## README

# @ capacor/ local- llm

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

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

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

## 安装

```bash
npm install @capacitor/local-llm
npx cap sync
```

## 平台要求

| 平台 | 最小操作系统 | 页:1 |
| --- | --- | --- |
| iOS系统 | **15个** | 图像生成需要iOS 18.4+. 文本LLM(Foundation Models / Apple Intelligence)需要iOS 26+. |
| 机器人 | **9 (API 28) (英语)** | 通过 ML 双子纳米 Kit需要一个支持在device AI上的设备(如像素9+). |

## iOS 设置

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

打电话 [`systemAvailability()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailability) 在运行时检查模型是否准备好,然后发出提示.

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

## Android 设置

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

```gradle
ext {
    minSdkVersion = 28
}
```

双子纳米通过Google Play Services发行,使用前必须下载到设备上. 该模型没有与您的应用程序捆绑.

### 检查可用性和下载

打电话 [`systemAvailability()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailability) 以检查当前状态。 如果状态是 `downloadable`,触发下载方式 [`download()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-download) 和民意调查 `systemAvailability()` 直到状态变为 `available`。 。 。 .

```typescript
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兼容. [这里有更多信息](https://www.apple.com/apple-intelligence/)。 。 。 .
-   **`download()` 在 iOS 上无法获取.** 该模型由操作系统管理;使用 `systemAvailability()` 检查准备状态.
-   **上下文限制为4096个符.** 这适用于系统指令的综合长度,对话历史,以及当前快取.

### 机器人

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

## 使用量

### 基本快捷键

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

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

console.log(text);
```

### 多回合对话

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

```typescript
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 });
```

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

```typescript
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)

```typescript
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`。 。 。 .

```typescript
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`

| 代码 | 说明 |
| --- | --- |
| `LOCAL_LLM_UNSUPPORTED_PLATFORM` | 目前的OS版本或设备硬件不支持在device LLMs上. |
| `LOCAL_LLM_NOT_ENABLED` | 在线设备AI功能得到了用户的支持,但没有被用户启用(如苹果智能). |
| `LOCAL_LLM_NOT_READY` | 该模型存在于设备上,但仍在下载或初始化. |
| `LOCAL_LLM_UNAVAILABLE` | 该模型由于未分类的原因无法使用. |
| `LOCAL_LLM_RESPONSE_IN_PROGRESS` | 已经向已经产生答复的会议发出一个提示. |
| `LOCAL_LLM_NOT_INITIALIZED` | 插件执行未初始化 。 这不应在正常情况下发生. |
| `LOCAL_LLM_MISSING_PARAMETER` | 缺少一个所需的调用参数(例如:. `sessionId`, (中文(简体) ), `prompt`) (中文(简体) ). |
| `LOCAL_LLM_WEB_NOT_SUPPORTED` | 该方法在网络平台上被调用,但并不支持. |
| `LOCAL_LLM_IMAGE_GENERATION_FAILED` | 图像生成失败( 例如没有可用的生成样式) . |
| `LOCAL_LLM_UNKNOWN_ERROR` | 一个出乎意料的错误被基础平台SDK所抛出. 检查 `err.message` 详细情况. |

## API 密码

-   [`systemAvailability()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailability)
-   [`download()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-download)
-   [`prompt(...)`](https://npmcn.com/package/%40capacitor/local-llm/#readme-prompt)
-   [`endSession(...)`](https://npmcn.com/package/%40capacitor/local-llm/#readme-endsession)
-   [`generateImage(...)`](https://npmcn.com/package/%40capacitor/local-llm/#readme-generateimage)
-   [`warmup(...)`](https://npmcn.com/package/%40capacitor/local-llm/#readme-warmup)
-   [`addListener('systemAvailabilityChange', ...)`](https://npmcn.com/package/%40capacitor/local-llm/#readme-addlistenersystemavailabilitychange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capacitor/local-llm/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capacitor/local-llm/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor/local-llm/#readme-type-aliases)

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

### 可操作性( )

```typescript
systemAvailability() => Promise<SystemAvailabilityResponse>
```

检查设备 LLM 的可用状态.

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

**回返情况:** `Promise<[SystemAvailabilityResponse](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailabilityresponse)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 下载( )

```typescript
download() => Promise<void>
```

下载在线设备 LLM 模型.

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

**自:** 1.0.0 (单位:千美元)

* * *

### 提示(...)

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

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

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[PromptOptions](https://npmcn.com/package/%40capacitor/local-llm/#readme-promptoptions)` | \- 即时选项,包括文本即时和可选配置 |

**回返情况:** `Promise<[PromptResponse](https://npmcn.com/package/%40capacitor/local-llm/#readme-promptresponse)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 会议结束(...)

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

结束活动 LLM 会话 .

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[EndSessionOptions](https://npmcn.com/package/%40capacitor/local-llm/#readme-endsessionoptions)` | \- 包含会议结束的选项 |

**自:** 1.0.0 (单位:千美元)

* * *

### 生成图像(...)

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

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

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[GenerateImageOptions](https://npmcn.com/package/%40capacitor/local-llm/#readme-generateimageoptions)` | \- 图像生成选项,包括即时、可选的参考图像和计数 |

**回返情况:** `Promise<[GenerateImageResponse](https://npmcn.com/package/%40capacitor/local-llm/#readme-generateimageresponse)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 热身(...)

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

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

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[WarmupOptions](https://npmcn.com/package/%40capacitor/local-llm/#readme-warmupoptions)` | \- 热身选项,包括即时前缀 |

**自:** 1.0.0 (单位:千美元)

* * *

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

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

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

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'systemAvailabilityChange'` | \- 要听的活动名称 |
| **`listenerFunc`** | `[SystemAvailabilityChangeListener](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailabilitychangelistener)` | \- 在每个变化中,以新的可用状态引用回调 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capacitor/local-llm/#readme-pluginlistenerhandle)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

* * *

### 接口

#### 系统可操作性响应

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

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`status`** | `[LLMAvailability](https://npmcn.com/package/%40capacitor/local-llm/#readme-llmavailability)` | LLM目前可用状态. | 1.0.0 (单位:千美元) |

#### 快速回复

LLM 处理后的反应 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`text`** | `string` | LLM生成的文本响应. | 1.0.0 (单位:千美元) |

#### 提示选项

向 LLM 发送提示的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `string` | 用于保持对话环境的可选会话标识符 。 通过多个提示提供相同的会话Id以保持上下文. 如不提供,则将每个提示视为独立. | 1.0.0 (单位:千美元) |
| **`instructions`** | `string` | 系统级指令来指导LLM的行为. 以此来设定LLM反应的作用,基调或约束. | 1.0.0 (单位:千美元) |
| **`options`** | `[LLMOptions](https://npmcn.com/package/%40capacitor/local-llm/#readme-llmoptions)` | 控制 LLM 推论行为的配置选项 . | 1.0.0 (单位:千美元) |
| **`prompt`** | `string` | 文本提示发送到 LLM . | 1.0.0 (单位:千美元) |

#### LLM 选项

LLM 推断行为的配置选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`temperature`** | `number` | 控制模型输出中的随机性. 更高的值(如0.8)使输出更加随机,而更低的值(如0.2)则使其更有针对性并具有决定性. | 1.0.0 (单位:千美元) |
| **`maximumOutputTokens`** | `number` | 响应中要生成的最大符数 。 在Android上,这一定是在1到256之间. | 1.0.0 (单位:千美元) |

#### 届会结束

结束活动 LLM 会话的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `string` | 要结束的会话标识符 。 这应该与先前的快讯( ) 呼叫中使用的会话Id 匹配 . | 1.0.0 (单位:千美元) |

#### 生成图像响应

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

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`pngBase64Images`** | `string[]` | 将生成的图像编组为 Base64-encoded PNG 字符串 。 每个字符串包含原始基础64数据(没有数据URI前缀). 要在 Ing 标记中使用, 前缀为 “ data: image/ png; base64, ” . | 1.0.0 (单位:千美元) |

#### 生成图像选项

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

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`prompt`** | `string` | 文字提示描述要生成的图像 . |  | 1.0.0 (单位:千美元) |
| **`promptImages`** | `string[]` | 可选的参考图像阵列来影响生成的输出. 提供碱基64-编码的图像字符串(无论有无数据URI前缀),用作图像生成的可视上下文或灵感. 这使得您可以结合文本和图像概念来进行更受控的输出. |  | 1.0.0 (单位:千美元) |
| **`count`** | `number` | 要生成的图像变化数 。 未指定时默认为 1 . | `1` | 1.0.0 (单位:千美元) |

#### 温暖选项

升温LLM的选项.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`sessionId`** | `string` | 热身的会话标识符 。 此标识符将与温暖会话相关, 允许您使用同一会话进行后续提示 . | 1.0.0 (单位:千美元) |
| **`promptPrefix`** | `string` | 用于升温LLM的快速前缀. 此文本将被用于模型的初始化前,减少后期带有类似前缀的提示的延迟. | 1.0.0 (单位:千美元) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

### 类型异名

#### 法学硕士

设备LLM的可用性状况.

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

#### 系统可操作性

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

`(response: [SystemAvailabilityResponse](https://npmcn.com/package/%40capacitor/local-llm/#readme-systemavailabilityresponse)): void`

## 常见问题

### @capacitor/local-llm 是什么？

一个用于运行在device LLMs上的Capacitor插件,支持文本生成,图像生成,以及iOS和Android上的会话管理\.

### 如何安装 @capacitor/local-llm？

在项目目录运行 npm install @capacitor/local-llm，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capacitor/local-llm 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capacitor/local-llm 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capacitor/local-llm 可以商用吗？

@capacitor/local-llm 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor/local-llm 的下载量有多少？

根据 npm 官方下载统计，@capacitor/local-llm 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,123 次，日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capacitor/local-llm 还在维护吗？

最新版本 1\.0\.0 发布于 2026/05/11（5 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/05/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。