如何在 Capacitor App 中使用 Apple Intelligence

要在 Capacitor 应用中使用 Apple Intelligence，请安装 @capgo/capacitor-llm，调用 setModel({ path: 'Apple Intelligence' })，检查 getReadiness()，然后创建聊天，并通过 textFromAi 事件流式返回回复。底层插件使用 Apple 的 Foundation Models 框架，该框架随 iOS 26 推出，可在设备端运行 Apple 语言模型，无需 API 密钥，无按请求计费，且数据不会离开手机。

本指南涵盖该框架提供的能力、设备要求、完整的 TypeScript 集成、4,096 token 上下文窗口、错误处理、App Review 注意事项，以及同一个 code 如何在 Android 上运行。

Apple Intelligence 能为 App 开发者带来什么

随着 iOS 26 的发布，Apple 通过 基础模型 框架向第三方应用开放了其设备端基础模型。在 Swift 中，你使用 SystemLanguageModel 以及 LanguageModelSession. 插件封装了这些，让你的 Web code 可以直接使用：

该模型拥有约 30 亿参数。它擅长摘要、重写、提取、分类和短文本生成。它无法替代处理开放式知识问题的云端大模型，Apple 在其官方指南中也明确说明了这一点。建议围绕用户已有的文本进行功能设计。

设备与操作系统要求

如果您的项目仍在使用旧版 Xcode 构建，请参阅 Apple 对 Capacitor 应用的 Xcode 26 要求。您应用的最低部署目标无需更改。该插件支持 iOS 15 及更高版本，且仅在 iOS 26 上调用 Foundation Models。

安装插件

bun add @capgo/capacitor-llm
bunx cap sync ios

请将 8.x 插件与 Capacitor 8 搭配使用。Apple Intelligence 不需要 Info.plist 键或 entitlements。如果您仍在使用 Capacitor 7，则 Capacitor 8 升级指南 优先执行。参考文档： /docs/plugins/llm/.

第 1 步：选择模型并检查可用性

setModel({ path: 'Apple Intelligence' }) 会选定系统模型并立即完成解析。实际可用性来自 getReadiness()，它将 Apple 的可用性枚举映射为可读字符串：

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

export type AIState = 'ready' | 'enable-in-settings' | 'preparing' | 'unsupported';

export async function initAppleIntelligence(): Promise<AIState> {
  if (Capacitor.getPlatform() !== 'ios') return 'unsupported';

  await CapgoLLM.setModel({ path: 'Apple Intelligence' });
  const { readiness } = await CapgoLLM.getReadiness();

  if (readiness === 'ready') return 'ready';
  if (readiness.includes('not enabled')) return 'enable-in-settings';
  if (readiness.includes('not ready')) return 'preparing';
  return 'unsupported';
}

当应用返回前台时再次检查。用户通常在看到提示后才会启用 Apple Intelligence，且模型下载可能在应用处于后台时完成。

import { App } from '@capacitor/app';

App.addListener('appStateChange', async ({ isActive }) => {
  if (isActive) updateAIState(await initAppleIntelligence());
});

第 2 步：创建带指令的对话

一个聊天对应一个 LanguageModelSession，它会保留对话历史。输入的 createChat() 不接受任何选项，因此请将指令放在第一条消息的开头：

const INSTRUCTIONS =
  'You summarize meeting notes. Reply with at most 5 bullet points. ' +
  'Keep names and dates exactly as written. Do not add information.';

const { id: chatId } = await CapgoLLM.createChat();

每个任务使用一个聊天。不断增长的聊天最终会达到下文所述的上下文限制。

第 3 步：将响应流式输出到 UI

在 iOS 上，每个 textFromAi 事件携带了迄今为止的响应快照，因为 Foundation Models 就是这样进行流式传输的。在 Android 上使用 Gemini Nano 时，事件仅携带新增文本。此辅助函数同时处理这两种情况，并以最终文本作为解析结果：

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

function mergeChunk(current: string, chunk: string) {
  return chunk.startsWith(current) ? chunk : current + chunk;
}

export async function ask(chatId: string, message: string, onText: (t: string) => void) {
  let text = '';
  let finish!: (value: string) => void;
  let fail!: (error: Error) => void;
  const done = new Promise<string>((resolve, reject) => {
    finish = resolve;
    fail = reject;
  });

  const handles = await Promise.all([
    CapgoLLM.addListener('textFromAi', (e) => {
      if (e.chatId !== chatId) return;
      text = mergeChunk(text, e.text);
      onText(text);
    }),
    CapgoLLM.addListener('aiFinished', (e) => {
      if (e.chatId === chatId) finish(text);
    }),
    CapgoLLM.addListener('generationError', (e) => {
      if (!e.chatId || e.chatId === chatId) fail(new Error(e.error));
    }),
  ]);

  try {
    await CapgoLLM.sendMessage({ chatId, message });
    return await done;
  } finally {
    await Promise.all(handles.map((h) => h.remove()));
  }
}

整合起来：在设备端总结笔记

export async function summarizeNotes(notes: string, render: (t: string) => void) {
  const state = await initAppleIntelligence();
  if (state !== 'ready') throw new Error(`AI unavailable: ${state}`);

  const { id } = await CapgoLLM.createChat();
  const prompt = `${INSTRUCTIONS}\n\nNotes:\n${notes.slice(0, 8000)}\n\nSummary:`;
  return ask(id, prompt, render);
}

本指南中介绍的 slice 只是防止超大输入的一种粗略手段。更好的做法是把长文档分块总结，再对这些总结做总结，每次都在新的对话里进行。

在框架组件中，运行期间禁用按钮。 ask 运行。插件会拒绝在同一对话中发起的第二次 sendMessage 请求，并提示“对话正在响应中，请稍后再提问”。

4,096 token 的上下文窗口

端侧模型的上下文窗口为 4,096 token。所有内容都会占用额度：指令、对话中的每一轮历史记录、新的 prompt 以及正在生成的响应。当会话超过限制时，Foundation Models 会抛出“exceeded context window size”错误，你会收到如下提示： generationError 事件以及一个被拒绝的 sendMessage.

实用规则：

• 一个任务一个对话，而不是一个页面一个对话。
• 保持指令简短且具体。
• 对于多轮对话，当对话变长时开启新对话，并传入之前对话的简短总结。
• 要求输出简洁。长回答同样占用额度。

调整输出

在 Apple Intelligence 路径下，插件使用系统的默认生成设置。 temperature, topk，以及 maxTokens 中的 setModel 适用于自定义的 LiteRT-LM 和 MediaPipe 模型路径。若要引导 Apple 的模型，请依赖 prompt：说明答案应有多长，指定格式（项目符号、JSON、一句话），并在格式重要时包含一个简短示例。

Android 端同样的 code

只有模型选择会改变：

const path = Capacitor.getPlatform() === 'ios' ? 'Apple Intelligence' : 'Gemini Nano';
await CapgoLLM.setModel({ path });

在 Android 上， setModel 当 Gemini Nano 不可用时，插件会拒绝请求，你可以通过同一插件回退到可下载的 Gemma 模型。详情见 如何在 Capacitor 应用中使用 Gemini Nano.

测试

• 真机： 可靠路径。使用支持 iOS 26 且已开启 Apple Intelligence 的 iPhone。
• 模拟器： 当宿主 Mac 在 Apple silicon 上运行 macOS 26 并启用 Apple Intelligence 时，就可以使用该模型。其行为和速度与手机不同，请在真机上确认。
• 不支持的状态： 请在关闭 Apple Intelligence 的情况下测试，检查“在设置中启用”的 UI；并在旧款 iPhone 或旧版 iOS 上测试，确认该功能能正常隐藏。

App Review 与隐私

Prompt 和响应都留在设备上，因此端侧生成本身不会为你的隐私标签增加数据收集项。但有两件事仍需你负责：

1. Apple 发布了 Foundation Models 框架的可接受使用要求。发布前请阅读这些要求，尤其是会生成内容并展示给其他用户的功能。
2. 模型内置了防护机制，可能会拒绝某些 Prompt 或输出。请把拒绝视为正常结果，并向用户显示清晰的提示。

由于 Prompt 在 Web code 中只是普通字符串，你可以在发布后用以下方式改进它们： Capgo 实时更新 而不必等待新的 App Store 构建。对原生 code 的更改（包括插件升级）仍需通过商店发布，你可以用以下工具在云端构建： Capgo 构建.

常见错误及解决方法

总结

Apple Intelligence 为 iOS 26 上所有符合条件的 iPhone 带来了免费、私密且离线的语言模型，Capacitor 应用只需几行 TypeScript 即可调用。选择模型，按条件控制 UI 显示 getReadiness()，让每个任务单独使用一个短对话，把快照流式输出到 UI，并把拒绝和上下文错误当作正常结果处理。想更全面地了解如何在混合应用中上线 AI 功能，请阅读 为什么 Capacitor 非常适合 AI 移动应用.