Skip to main content

Embed

Mastra uses the AI SDK's embed and embedMany functions to generate vector embeddings for text inputs, enabling similarity search and RAG workflows.

Supported embedding models
Direct link to Supported embedding models

Memory and RAG vector query tools accept embedding models with specification versions v1, v2, v3, and v4. Mastra selects the matching AI SDK implementation from the model's specificationVersion. Existing model configurations remain unchanged.

For direct calls, use the matching export from @mastra/core/vector: embedV1, embedV2, embedV3, or embedV4. For example, an AI SDK v7 provider exposes a specification v4 embedding model:

import { openai } from '@ai-sdk/openai'
import { embedV4 } from '@mastra/core/vector'

const { embedding } = await embedV4({
  model: openai.embedding('text-embedding-3-small'),
  value: 'Your text to embed',
})

This example requires @ai-sdk/openai v4. The model specification version and AI SDK package version are different: AI SDK v4 uses embedding specification v1, v5 uses v2, v6 uses v3, and v7 uses v4.

Single embedding
Direct link to Single embedding

The embed function generates a vector embedding for a single text input:

import { embed } from 'ai'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

const result = await embed({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  value: 'Your text to embed',
  maxRetries: 2, // optional, defaults to 2
})

Parameters
Direct link to Parameters

model:

EmbeddingModel
The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))

value:

string | Record<string, any>
The text content or object to embed

maxRetries?:

number
= 2
Maximum number of retries per embedding call. Set to 0 to disable retries.

abortSignal?:

AbortSignal
Optional abort signal to cancel the request

headers?:

Record<string, string>
Additional HTTP headers for the request (only for HTTP-based providers)

Return value
Direct link to Return value

embedding:

number[]
The embedding vector for the input

Multiple embeddings
Direct link to Multiple embeddings

For embedding multiple texts at once, use the embedMany function:

import { embedMany } from 'ai'

const result = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  values: ['First text', 'Second text', 'Third text'],
  maxRetries: 2, // optional, defaults to 2
})

Parameters
Direct link to Parameters

model:

EmbeddingModel
The embedding model to use (e.g. openai.embedding('text-embedding-3-small'))

values:

string[] | Record<string, any>[]
Array of text content or objects to embed

maxRetries?:

number
= 2
Maximum number of retries per embedding call. Set to 0 to disable retries.

abortSignal?:

AbortSignal
Optional abort signal to cancel the request

headers?:

Record<string, string>
Additional HTTP headers for the request (only for HTTP-based providers)

Return value
Direct link to Return value

embeddings:

number[][]
Array of embedding vectors corresponding to the input values

Example usage
Direct link to Example usage

import { embed, embedMany } from 'ai'

// Single embedding
const singleResult = await embed({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  value: 'What is the meaning of life?',
})

// Multiple embeddings
const multipleResult = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  values: [
    'First question about life',
    'Second question about universe',
    'Third question about everything',
  ],
})

For more detailed information about embeddings in the Vercel AI SDK, see:

On this page