Text Embeddings

Text embedding models convert sentences, paragraphs, or documents into dense numeric vectors (embeddings). Sentences with similar semantic meaning map to nearby points in the vector space, even when using completely different vocabulary.

This enables on-device semantic search, offline Retrieval-Augmented Generation (RAG) against local SQLite vector stores, intent classification, and cross-modal text-to-image queries when paired with Image Embeddings — entirely on the client without sending private text to cloud APIs.

iOS	Android

Quick Start

The useTextEmbedder hook manages model downloading, tokenizer loading, and lifecycle:

import { models, useTextEmbedder } from 'react-native-executorch';

function MyComponent() {
  const embedder = useTextEmbedder(models.textEmbeddings.ALL_MINILM_L6_V2.DEFAULT);

  // Hook state:
  // embedder.isReady          — true once model and tokenizer are downloaded and loaded in memory
  // embedder.downloadProgress — 0 to 100 download progress
  // embedder.error            — Error instance if download or load failed
  // embedder.resource         — resolved config with all URLs replaced by local file paths

  const handleEmbed = async (inputText: string) => {
    if (!embedder.isReady || !embedder.embed) return;

    // Run inference on background thread
    const vector = await embedder.embed(inputText);
    console.log('Embedding dimension:', vector.length); // 384
  };

  // Trigger handleEmbed on submit from a search input or indexing loop
}

Full Interactive Example in Gallery App

See src/app/(screens)/image-embeddings.tsx in the React Native ExecuTorch Gallery for a complete, runnable screen combining text and image embeddings for real-time cross-modal search.

Output Format

embed() returns a 1D Float32Array containing the normalized feature vector:

// Float32Array of length D (e.g. 384 for all-MiniLM-L6-v2, 768 for all-mpnet-base-v2)
const vector: Float32Array = await embedder.embed('React Native ExecuTorch enables on-device ML.');

Semantic Similarity Matching

To compare semantic similarity between two text snippets (or between an asymmetric query and a document), calculate their cosine similarity / dot product:

function cosineSimilarity(a: Float32Array, b: Float32Array): number {
  let sum = 0;
  for (let i = 0; i < a.length; i++) {
    sum += a[i] * b[i];
  }
  return sum;
}

const v1 = await embedder.embed('How do I reset my password?');
const v2 = await embedder.embed('Steps to change account credentials');
const v3 = await embedder.embed('What is the weather in Tokyo?');

console.log('Similarity (related):', cosineSimilarity(v1, v2)); // ~0.85
console.log('Similarity (unrelated):', cosineSimilarity(v1, v3)); // ~0.15

Asymmetric Retrieval & Prompt Prefixes

Some embedding models (like LFM2_5_EMBEDDING_350M) are trained asymmetrically where search queries and indexed passages use different prompt prefixes:

• Indexing documents: embed(documentText, 'document: ')
• Searching queries: embed(queryText, 'query: ') (default)

You can pass a custom prefix string as the optional second prompt argument to embed(input, prompt).

Imperative API

For batch indexing, SQLite vector ingestion, or manual lifecycle management outside React components, create the embedder using createTextEmbedder:

import { createTextEmbedder, download, models } from 'react-native-executorch';

// Download and cache model assets before creating the imperative pipeline
const model = await download(models.textEmbeddings.ALL_MINILM_L6_V2.DEFAULT);
const embedder = await createTextEmbedder(model);

try {
  const vector = await embedder.embed('Vector search index item');
  console.log('Generated vector:', vector.slice(0, 5));
} finally {
  // Always release native resources when finished
  embedder.dispose();
}

Synchronous Execution

For synchronous worklet execution contexts or high-throughput indexing workers, createTextEmbedder exposes a synchronous embedWorklet function:

// Called synchronously inside a worklet runtime without Promise scheduling overhead
const vector = embedder.embedWorklet(rawText);

See Worklets & Threading for details on worklet execution contexts and zero-copy host objects.

Available Models

The library provides ready-to-use text embedding models from the Software Mansion HuggingFace Text Embeddings Collection, available in models.textEmbeddings:

Model Family	Variants	Output Dim	Languages	Size Range	Supported Backends	Notes
all-MiniLM-L6-v2	See	384	English	86.2 MB	XNNPACK (CPU), Core ML (Apple), Vulkan (Android)	Fast, lightweight sentence transformer for mobile vector search.
all-mpnet-base-v2	See	768	English	415.6 MB	XNNPACK (CPU), Vulkan (Android)	High-capacity model with superior semantic retrieval accuracy.
multi-qa-MiniLM / mpnet	MiniLM, mpnet	384 / 768	English	86.2 MB – 415.6 MB	XNNPACK (CPU), Core ML (Apple), Vulkan (Android)	Fine-tuned specifically for Question-Answering retrieval.
paraphrase-multilingual-MiniLM-L12-v2	See	384	50+ languages	378.9 MB	XNNPACK (CPU), Core ML (Apple), Vulkan (Android)	Multilingual semantic similarity and cross-lingual text matching.
distiluse-base-multilingual-cased-v2	See	512	50+ languages	133.1 MB – 375.1 MB	XNNPACK (CPU), Core ML (Apple), MLX (Apple), Vulkan (Android)	Distilled Universal Sentence Encoder for multilingual clustering.
Liquid LFM 2.5 Embedding 350M	See	512	Multilingual	179.8 MB – 548.2 MB	XNNPACK (CPU), MLX (Apple)	Asymmetric search with query: and document: prompting.
CLIP ViT-B/32 Text	See	512	English	242.2 MB	XNNPACK (CPU), Core ML (Apple), Vulkan (Android)	Text encoder for joint cross-modal text-to-image search.

Using Custom Models

To use your own fine-tuned sentence transformer .pte model, pass a TextEmbedderModel configuration object to useTextEmbedder or createTextEmbedder:

const customEmbedder = await createTextEmbedder({
  modelPath: 'https://example.com/my-sentence-transformer.pte',
  tokenizerPath: 'https://example.com/tokenizer.json',
  defaultPrompt: 'passage: ', // Optional default prefix
});

The pipeline automatically verifies that the model's exported input and output shapes match its requirements. To prepare and export your own .pte model to match this pipeline, see Exporting Custom Models.

API Reference

Hooks & Pipelines

• useTextEmbedder() — React hook for text embedding model downloading, state, and lifecycle.
• createTextEmbedder() — Imperative factory for text embedding pipelines.
• useImageEmbedder() — React hook for vision embedding models to pair with text embeddings.

Types & Options

• TextEmbedder — Text embedder runner interface (embed, embedWorklet).
• TextEmbedderModel — Model configuration spec with modelPath, tokenizerPath, and defaultPrompt.

Model Presets

• models.textEmbeddings — Pre-configured text embedding models registry.

Source Code

View the implementation on GitHub:

• src/extensions/nlp/tasks/textEmbedding.ts ↗