如何在 Capacitor 应用中使用 Apple Intelligence

要在 Capacitor 应用中使用 Apple Intelligence，请安装 @capgo/capacitor-llm，调用 setModel({ path: 'Apple Intelligence' })，检查 getReadiness(), then create a chat and stream replies through the textFromAi 。在底层，该插件使用了随 iOS 26 推出的 Apple Foundation Models 框架，它运行 Apple 的设备端语言模型，无需 API 密钥，无需按请求付费，且数据不会离开手机。

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

Apple Intelligence 为 App 开发者提供了什么

With iOS 26, Apple opened its on-device foundation model to third-party apps through the 基础模型 框架。在 Swift 中，你可以使用 SystemLanguageModel 和 LanguageModelSession。该插件对其进行了封装，以便你的 Web code 可以直接调用：

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

设备与操作系统要求

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

安装插件

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

请配合 Capacitor 8 使用插件 8.x。Apple Intelligence 不需要任何 Info.plist 键或 entitlements。如果您仍在使用 Capacitor 7，请先阅读 Capacitor 8 升级指南 。参考文档： /docs/plugins/llm/.

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

setModel({ path: 'Apple Intelligence' }) 选择系统模型并立即解析。实际可用性由 getReadiness()提供，它将 Apple 的可用性枚举（availability enum）映射为可读字符串：

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 的流式传输方式。在带有 Gemini Nano 的 Android 上，事件仅携带新增文本。此辅助函数可同时处理两者，并返回最终文本：

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.

测试

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

App Review 与隐私

Prompt 和响应均保留在设备端，因此仅靠端侧生成并不会为你的隐私标签增加数据收集项。但仍有两点需要你注意：

1. Apple 发布了 Foundation Models framework 的可接受使用规范。在发布前请务必阅读，特别是针对会向其他用户展示生成内容的特性。
2. 模型内置了防护机制，可能会拒绝某些 Prompt 或输出。请将拒绝视为正常结果，并向用户展示清晰的提示信息。

由于 Prompt 在你的 Web code 中只是普通的字符串，你可以在发布后通过以下方式进行优化： Capgo 实时更新 无需等待新的 App Store 版本。但涉及 Native code 的更改（包括插件升级）仍需通过商店发布，你可以使用以下工具在云端进行构建： Capgo 构建.

常见错误及解决方案

总结

Apple Intelligence 为 iOS 26 上所有符合条件的 iPhone 带来了免费、私密且离线的语言模型，而 Capacitor 应用只需几行 TypeScript 即可调用。选择模型，开启 UI 门控 getReadiness()，将每个任务保持在独立的短对话中，将快照流式传输到 UI，并将拒绝请求和上下文错误视为常规结果。若想深入了解如何在混合应用中发布 AI 功能，请阅读 为什么 Capacitor 非常适合 AI 移动应用.