#Apple Embeddings

Generate text embeddings using Apple's on-device NLContextualEmbedding model with the AI SDK.

#Overview

The Apple Embeddings provider uses Apple's NLContextualEmbedding to generate contextual text embeddings entirely on-device. This is Apple's implementation of a BERT-like transformer model integrated into iOS 17+, providing privacy-preserving text understanding capabilities.

#Model Architecture

NLContextualEmbedding uses a transformer-based architecture trained with masked language modeling (similar to BERT). Apple provides three optimized models grouped by writing system:

• Latin Script Model (20 languages): English, Spanish, French, German, Italian, Portuguese, Dutch, and others - produces 512-dimensional embeddings
• Cyrillic Script Model (4 languages): Russian, Ukrainian, Bulgarian, Serbian
• CJK Model (3 languages): Chinese, Japanese, Korean

Each model is multilingual within its script family, enabling cross-lingual semantic understanding. The models are compressed and optimized for Apple's Neural Engine, typically under 100MB when downloaded.

#Requirements

• iOS 17+ - NLContextualEmbedding requires iOS 17 or later

#Usage

#Single Text

import { embed } from 'ai'
import { apple } from '@react-native-ai/apple'

const { embedding } = await embed({
  model: apple.textEmbeddingModel(),
  value: 'Hello world',
})

console.log(embedding)

#Multiple Texts

import { embedMany } from 'ai'
import { apple } from '@react-native-ai/apple'

const { embeddings } = await embedMany({
  model: apple.textEmbeddingModel(),
  values: ['Hello world', 'How are you?', 'Goodbye'],
})

console.log(embeddings)

#Language Support

The embeddings model supports multiple languages. You can specify the language using ISO 639-1 codes or full names:

// ISO codes
await embed({
  model: apple.textEmbeddingModel(), 
  value: 'Bonjour',
  language: 'fr' 
})

For list of all supported languages, check Apple documentation.

#Asset Management

Apple's NLContextualEmbedding requires downloading language-specific assets to the device. The provider automatically requests assets when needed, but you can also prepare them manually:

import { NativeAppleEmbeddings } from '@react-native-ai/apple'

// Pre-download assets for a language
try {
  await NativeAppleEmbeddings.prepare('en')
  console.log('English assets ready')
} catch (error) {
  console.log('Assets not available:', error)
}

The asset management system is designed to be efficient and user-friendly. When you call prepare() for a language, the system first checks if the required assets are already present on the device. If they are, the method resolves immediately without any network activity, making subsequent embedding operations instant.

#Direct API Access

For advanced use cases, you can access the embeddings API directly:

#AppleEmbeddings

import { AppleEmbeddings } from '@react-native-ai/apple'

// Get embedding model information
const modelInfo: EmbeddingInfo = await AppleEmbeddings.getInfo(language: string)

// Prepare language assets
await AppleEmbeddings.prepare(language: string)

// Generate embeddings
const embeddings = await AppleEmbeddings.generateEmbeddings(
  values: string[], 
  language: string
): Promise<number[][]>

export interface EmbeddingInfo {
  hasAvailableAssets: boolean
  dimension: number
  languages: string[]
  maximumSequenceLength: number
  modelIdentifier: string
  revision: number
  scripts: string[]
}

#Benchmarks

Performance results showing processing time in milliseconds per embedding across different text lengths:

Each category is tested with 5 consecutive runs to calculate reliable averages and account for system variability.