Cara Menggunakan Integritas Apple di Aplikasi Capacitor

Menggunakan Intelektual Apple di aplikasi Capacitor, instal @capgo/capacitor-llmPanggil setModel({ path: 'Apple Intelligence' })Periksa getReadiness()lalu buatlah percakapan dan alirkan balasan melalui textFromAi event. Di balik layar plugin ini menggunakan kerangka kerja Model Dasar Apple, yang diperkenalkan bersama iOS 26, yang menjalankan model bahasa perangkat Apple tanpa kunci API, tanpa biaya per permintaan, dan tanpa data keluar dari ponsel.

Guid ini membahas apa yang ditawarkan kerangka kerja tersebut, spesifikasi perangkat, integrasi lengkap TypeScript, jendela konteks 4.096-token, penanganan kesalahan, catatan App Review, dan bagaimana code yang sama berjalan di Android.

Apa yang ditawarkan Apple Intelligence bagi pengembang aplikasi

Dengan iOS 26, Apple membuka model dasar perangkatnya kepada aplikasi pihak ketiga melalui Kerangka Kerja Model Dasar framework. Di Swift, Anda bekerja dengan SystemLanguageModel dan LanguageModelSessionPlugin ini mengelilingi mereka sehingga web code Anda dapat menggunakan mereka:

Model ini memiliki sekitar 3 miliar parameter. Model ini sangat baik dalam menyajikan ringkasan, merevisi, mengekstrak, mengklasifikasikan, dan menghasilkan teks singkat. Namun, model ini bukanlah pengganti model cloud besar untuk pertanyaan pengetahuan terbuka, dan Apple sendiri telah menyatakan hal ini dalam panduan mereka. Desain fitur sekitar teks yang sudah dimiliki pengguna.

Spesifikasi perangkat dan sistem operasi

Jika proyek Anda masih dapat dibangun dengan Xcode yang lebih tua, lihat Persyaratan Xcode 26 dari Apple untuk aplikasi Capacitor. Target pengembangan minimum aplikasi Anda tidak perlu berubah. Plugin ini mendukung iOS 15 dan lebih lanjut dan hanya menyentuh Model Foundation pada iOS 26.

Pasang plugin

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

Use plugin 8.x with Capacitor 8. No Info.plist keys or entitlements are needed for Apple Intelligence. If you are still on Capacitor 7, the Panduan pembaruan: Capacitor 8 Datang terlebih dahulu. Referensi dokumen: /docs/plugin/LLM/.

Langkah 1: Pilih model dan periksa ketersediaan

setModel({ path: 'Apple Intelligence' }) mengatur model sistem dan menyelesaikan dengan cepat. Ketersediaan sebenarnya berasal dari getReadiness(), yang menerjemahkan enum ketersediaan Apple ke string yang dapat dibaca:

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

Periksa lagi ketika aplikasi kembali ke latar belakang. Pengguna sering mengaktifkan Integritas Apple setelah melihat petunjuk Anda, dan download model dapat selesai sementara aplikasi Anda berada di latar belakang.

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

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

Langkah 2: Buat percakapan dengan instruksi

Satu percakapan mewakili satu LanguageModelSessionyang menjaga riwayat percakapan. Diketik createChat() Tidak menerima opsi, jadi letakkan instruksi Anda di awal pesan pertama.

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();

Gunakan satu percakapan per tugas. Jika percakapan terus tumbuh, maka akan mencapai batas konteks yang dijelaskan di bawah ini.

Langkah 3: Streaming respons ke UI

Langkah 3: Streaming respons ke UI textFromAi event carries a snapshot of the response so far, because that is how Foundation Models streams. On Android with Gemini Nano, events carry only the new text. This helper handles both and resolves with the final text:

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

Menggabungkan catatan: ringkasan perangkat

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

The slice is a crude guard against huge inputs. A better approach is to summarize long documents in chunks and then summarize the summaries, each in a fresh chat.

In komponen framework, matikan tombol sementara ask menjalankan. Plugin menolak permintaan kedua sendMessage pada percakapan yang sama dengan “percakapan sedang menjawab, silakan tunggu sebelum bertanya pertanyaan baru”.

Jendela konteks 4.096-token

Model perangkat keras memiliki jendela konteks 4.096 token. Semua hal berkontribusi pada jendela konteks: instruksi, setiap putaran percakapan sebelumnya, prompt baru, dan jawaban yang sedang dihasilkan. Ketika sesi melebihi batasnya, Model Dasar Membangun mengeluarkan kesalahan “ukuran jendela konteks melebihi batas” yang mencapai Anda sebagai generationError event dan ditolak sendMessage.

Aturan praktis:

• Satu percakapan per tugas, bukan satu percakapan per layar.
• Jaga instruksi singkat dan spesifik.
• Mulai percakapan baru ketika percakapan panjang dan beritahu ringkasan singkat percakapan sebelumnya.
• Askilkan output singkat. Jawaban panjang menggunakan anggaran yang sama.

Pengaturan output

On jalur Intelijen Apple, plugin menggunakan pengaturan penghasilan default sistem. temperature, topk, dan maxTokens di setModel berlaku untuk jalur model LiteRT-LM dan MediaPipe yang diatur sendiri. Untuk mengarahkan model Apple, bergantung pada prompt: katakan berapa lama jawaban seharusnya, berikan format (daftar, JSON, satu kalimat), dan termasuk satu contoh singkat ketika format penting.

Yang sama code pada Android

Hanya perubahan model yang berubah:

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

Pada Android, setModel menolak ketika Gemini Nano tidak tersedia, dan Anda dapat kembali ke model download Gemma melalui plugin yang sama. Detailnya ada di Cara Menggunakan Gemini Nano di Aplikasi Capacitor.

Pengujian

• Perangkat nyata: jalan yang dapat diandalkan. Gunakan iPhone yang didukung pada iOS 26 dengan Intelijen Apple.
• Simulator: Model ini dapat digunakan ketika Mac host menjalankan macOS 26 pada Apple silicon dengan Apple Intelligence diaktifkan. Perilaku dan kecepatan berbeda dari ponsel, jadi pastikan pada perangkat keras.
• Status Tidak Dapat Dihubungi: test with Apple Intelligence turned off to check your “enable in Settings” UI, and on an older iPhone or iOS version to check that the feature hides cleanly.

aktifkan di Pengaturan

Prompts and responses stay on the device, so on-device generation adds no data collection to your privacy label by itself. Two things are still on you:

1. Apple publishes acceptable use requirements for the Foundation Models framework. Read them before you ship, especially for features that generate content shown to other users.
2. Pertanyaan dan respons tetap pada perangkat, sehingga pengenalan pada perangkat tidak menambahkan pengumpulan data pada label privasi Anda sendiri. Dua hal masih ada pada Anda:

Sejak prompt adalah string sederhana di dalam web code, Anda dapat meningkatkannya setelah peluncuran dengan Capgo pembaruan waktu nyata instead of waiting for a new App Store build. Changes to native code, including plugin upgrades, still need a store release, which you can build in the cloud with Capgo Live Update.

Masalah umum dan solusi

Penutup

Inteligensi Apple membawa model bahasa offline gratis dan pribadi ke setiap iPhone yang memenuhi syarat di iOS 26, dan sebuah aplikasi Capacitor dapat menggunakan model tersebut dengan beberapa baris kode TypeScript. Pilih model, tutup UI pada getReadiness()tetapkan setiap tugas di percakapan pendek, streaming snapshot ke UI, dan tangani penolakan dan kesalahan konteks seperti hasil normal. Untuk pandangan yang lebih luas tentang mengirimkan fitur AI di aplikasi hybrid, baca mengapa Capacitor berfungsi baik untuk aplikasi AI mobile.