Skip to main content
Version: 0.9.x

useTextEmbeddings

Text Embedding is the process of converting text into a numerical representation. This representation can be used for various natural language processing tasks, such as semantic search, text classification, and clustering.

info

It is recommended to use models provided by us, which are available at our Hugging Face repository. You can also use constants shipped with our library.

API Reference​

High Level Overview​

import { models, useTextEmbeddings } from 'react-native-executorch';
const model = useTextEmbeddings({
  model: models.text_embedding.all_minilm_l6_v2(),
});

try {
  const embedding = await model.forward('Hello World!');
} catch (error) {
  console.error(error);
}

Arguments​

useTextEmbeddings takes TextEmbeddingsProps that consists of:

  • model of type object (TextEmbeddingsModel) containing:
    • modelName - Unique name identifying the model.
    • modelSource - Location of the used model.
    • tokenizerSource - Location of the used tokenizer.
    • prompts (optional) - Asymmetric query/document prompts the model is trained with. When present, forward requires a role and prepends the matching prompt.
    • multiVector (optional) - When true, forward returns the per-token EmbeddingResult instead of a single pooled Float32Array.
    • skipListIds (optional) - Token ids to exclude from late-interaction (MaxSim) scoring.
  • An optional flag preventLoad which prevents auto-loading of the model.

You need more details? Check the following resources:

Returns​

useTextEmbeddings returns an object called TextEmbeddingsType containing bunch of functions to interact with text embedding. To get more details please read: TextEmbeddingsType API Reference.

Running the model​

To run the model, you can use the forward method. It accepts the text to embed and, for models trained with asymmetric prompts, an optional role. The return type depends on the model:

  • Pooled models (the default, e.g. MiniLM, MPNet, LFM2.5-Embedding) resolve to a single Float32Array — one normalized vector for the whole input.
  • Multi-vector models (multiVector: true, e.g. LFM2.5-ColBERT) resolve to an EmbeddingResult with the per-token vectors (vectors, numTokens, embeddingDim, tokenIds).

For background on why a dense bi-encoder pools to one vector while a late-interaction model keeps per-token vectors, see Liquid AI's LFM2.5 Retrievers blog post.

Asymmetric prompts (role)​

Some retrieval models are trained to embed queries and documents with different prefixes (e.g. LFM2.5 uses query: /document: , ColBERT uses [Q] /[D] ). For these models the model config carries the prompts and forward requires a role:

const queryEmbedding = await model.forward('What is the weather?', 'query');
const docEmbedding = await model.forward('It is sunny today.', 'document');

The matching prompt is prepended automatically; for models without prompts the role argument is absent.

Example​

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

const cosineSimilarity = (a: Float32Array, b: Float32Array) => {
  const dot = dotProduct(a, b);
  const normA = Math.sqrt(dotProduct(a, a));
  const normB = Math.sqrt(dotProduct(b, b));
  return dot / (normA * normB);
};

function App() {
  const model = useTextEmbeddings({
    model: models.text_embedding.all_minilm_l6_v2(),
  });

  // ...

  try {
    const helloWorldEmbedding = await model.forward('Hello World!');
    const goodMorningEmbedding = await model.forward('Good Morning!');

    const similarity = cosineSimilarity(
      helloWorldEmbedding,
      goodMorningEmbedding
    );

    console.log(`Cosine similarity: ${similarity}`);
  } catch (error) {
    console.error(error);
  }

  // ...
}

Supported models​

ModelLanguageMax TokensEmbedding DimensionsDescription
all-MiniLM-L6-v2English254384All-round model tuned for many use-cases. Trained on a large and diverse dataset of over 1 billion training pairs.
all-mpnet-base-v2English382768All-round model tuned for many use-cases. Trained on a large and diverse dataset of over 1 billion training pairs.
multi-qa-MiniLM-L6-cos-v1English509384This model was tuned for semantic search: Given a query/question, it can find relevant passages. It was trained on a large and diverse set of (question, answer) pairs.
multi-qa-mpnet-base-dot-v1English510768This model was tuned for semantic search: Given a query/question, it can find relevant passages. It was trained on a large and diverse set of (question, answer) pairs.
distiluse-base-multilingual-cased-v250+ languages126512Multilingual DistilBERT with a 768→512 projection head. Recommended when broader language coverage matters more than the exact English quality of MiniLM/MPNet.
paraphrase-multilingual-MiniLM-L12-v250+ languages126384Multilingual MiniLM-L12 distilled from paraphrase-multilingual-mpnet-base-v2. Compact (≈118 M params) sentence encoder for cross-lingual semantic similarity and retrieval across 50+ languages.
clip-vit-base-patch32-textEnglish74512CLIP (Contrastive Language-Image Pre-Training) is a neural network trained on a variety of (image, text) pairs. CLIP allows to embed images and text into the same vector space. This allows to find similar images as well as to implement image search. This is the text encoder part of the CLIP model. To embed images checkout clip-vit-base-patch32-image.
LFM2.5-Embedding-350MMultilingual5121024Dense bi-encoder from Liquid AI with CLS pooling. Trained with asymmetric query: /document: prompts, so forward requires a role. On iOS it runs on the GPU via the MLX backend (physical device only); Android uses XNNPACK.
LFM2.5-ColBERT-350MMultilingual512128 (per token)Late-interaction (multi-vector) retriever from Liquid AI: a Linear(1024→128) head emits one normalized vector per token. forward returns an EmbeddingResult; score query/document pairs with MaxSim (see below). Uses [Q] /[D] role prompts.

Max Tokens - The maximum number of tokens that can be processed by the model. If the input text exceeds this limit, it will be truncated.

Embedding Dimensions - The size of the output embedding vector. This is the number of dimensions in the vector representation of the input text.

note

For the supported models, the returned embedding vector is normalized, meaning that its length is equal to 1. This allows for easier comparison of vectors using cosine similarity, just calculate the dot product of two vectors to get the cosine similarity score.

Late interaction (multi-vector models)​

Multi-vector models such as LFM2.5-ColBERT do not pool the sequence into a single vector. Instead, forward returns an EmbeddingResult holding one normalized vector per token. You score a query against a document with MaxSim: for every query-token vector, take its highest dot product against the document-token vectors, then sum those maxima. The model also ships a skipListIds array — the punctuation token ids excluded from scoring.

The library ships a maxSim helper (and a dotProduct helper for pooled models), so you can score directly without reimplementing it:

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

const colbert = models.text_embedding.lfm2_5_colbert_350m();
const skipListIds = colbert.skipListIds ?? [];

function App() {
  const model = useTextEmbeddings({ model: colbert });

  // ...

  const query = await model.forward('What is the weather?', 'query');
  const doc = await model.forward('It is sunny today.', 'document');
  const score = maxSim(query, doc, skipListIds);
}

The skipListIds shipped on the model config are the punctuation token ids excluded from scoring (derived from the model's training config). Per-token vectors are L2-normalized by the graph, so the dot product equals cosine similarity.

We are Software Mansion.

Hire us