Embeddings

Core embedding interfaces for generating vector representations of text

Overview

The Embeddings module provides base classes and interfaces for generating vector embeddings from text. Embeddings are used to convert text into numerical vectors for semantic search and retrieval.

BaseEmbedding

Abstract base class that all embedding implementations extend.

import { BaseEmbedding } from "@llamaindex/core/embeddings";

Properties

embedBatchSize · number · default: 10

Number of texts to embed in a single batch

embedInfo · EmbeddingInfo

Metadata about the embedding model

Show EmbeddingInfo Fields

dimensions · number

Dimensionality of the embedding vectors

maxTokens · number

Maximum tokens the model can process

tokenizer · Tokenizers

Tokenizer used by the model

Methods

getTextEmbedding · method

Get embedding for a single text string

abstract getTextEmbedding(text: string): Promise<number[]>

Show Parameters

text · string · required

The text to embed

Show Returns

embedding · number[]

The embedding vector

getTextEmbeddings · method

Get embeddings for multiple texts (batch processing)

getTextEmbeddings(texts: string[]): Promise<Array<number[]>>

Show Parameters

texts · string[] · required

Array of texts to embed

Show Returns

embeddings · number[][]

Array of embedding vectors, one per input text

getTextEmbeddingsBatch · method

Get embeddings for texts with batching and progress tracking

getTextEmbeddingsBatch(
  texts: string[],
  options?: BaseEmbeddingOptions
): Promise<Array<number[]>>

Show Parameters

texts · string[] · required

Array of texts to embed

options · BaseEmbeddingOptions

Embedding options

Show BaseEmbeddingOptions

logProgress · boolean

Whether to log progress to console

progressCallback · (current: number, total: number) => void

Callback function for progress updates

logger · Logger

Custom logger instance

getQueryEmbedding · method

Get embedding for a query (supports multi-modal content)

getQueryEmbedding(query: MessageContentDetail): Promise<number[] | null>

Show Parameters

query · MessageContentDetail · required

Query content (text or multi-modal)

Show Returns

embedding · number[] | null

The query embedding vector, or null if text extraction fails

similarity · method

Calculate similarity between two embedding vectors

similarity(
  embedding1: number[],
  embedding2: number[],
  mode?: SimilarityType
): number

Show Parameters

embedding1 · number[] · required

First embedding vector

embedding2 · number[] · required

Second embedding vector

mode · SimilarityType · default: "DEFAULT"

Similarity metric: DEFAULT, DOT_PRODUCT, EUCLIDEAN, or COSINE

Show Returns

similarity · number

Similarity score between the two vectors

Usage Examples

Basic Embedding

import { OpenAIEmbedding } from "@llamaindex/openai";

const embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-small"
});

const embedding = await embedModel.getTextEmbedding(
  "LlamaIndex is a data framework for LLM applications"
);

console.log(embedding.length); // 1536

Batch Embedding with Progress

const texts = [
  "First document",
  "Second document",
  "Third document"
];

const embeddings = await embedModel.getTextEmbeddingsBatch(texts, {
  logProgress: true,
  progressCallback: (current, total) => {
    console.log(`Progress: ${current}/${total}`);
  }
});

console.log(embeddings.length); // 3

Embedding Nodes

The BaseEmbedding class extends TransformComponent and can embed nodes directly:

import { Document } from "@llamaindex/core/schema";

const documents = [
  new Document({ text: "Document 1" }),
  new Document({ text: "Document 2" })
];

// Transform adds embeddings to nodes
const embeddedNodes = await embedModel.transform(documents);

console.log(embeddedNodes[0].embedding); // number[]

Similarity Calculation

const embedding1 = await embedModel.getTextEmbedding("cat");
const embedding2 = await embedModel.getTextEmbedding("dog");
const embedding3 = await embedModel.getTextEmbedding("car");

const similarity1 = embedModel.similarity(embedding1, embedding2);
const similarity2 = embedModel.similarity(embedding1, embedding3);

console.log(similarity1 > similarity2); // true (cat and dog are more similar)

Similarity Types

enum SimilarityType {
  DEFAULT = "cosine",
  DOT_PRODUCT = "dot_product",
  EUCLIDEAN = "euclidean",
  COSINE = "cosine"
}

Token Truncation

Embeddings automatically truncate text that exceeds the model’s token limit:

const embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-small"
});

// Set embedding info with max tokens
embedModel.embedInfo = {
  dimensions: 1536,
  maxTokens: 8191,
  tokenizer: Tokenizers.CL100K_BASE
};

// Long text will be automatically truncated
const longText = "...".repeat(10000);
const embedding = await embedModel.getTextEmbedding(longText);