> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Embedding models

Mastra's model router supports embedding models using the same `provider/model` string format as language models. This provides a unified interface for both chat and embedding models with TypeScript autocomplete support.

## Quickstart

```typescript
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { embedMany } from "ai";

// Generate embeddings
const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
  values: ["Hello world", "Semantic search is powerful"],
});
```

## Supported models

### OpenAI

- `text-embedding-3-small` - 1536 dimensions, 8191 max tokens
- `text-embedding-3-large` - 3072 dimensions, 8191 max tokens
- `text-embedding-ada-002` - 1536 dimensions, 8191 max tokens

```typescript
const embedder = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
```

### Google

- `gemini-embedding-001` - 768 dimensions, 2048 max tokens

```typescript
const embedder = new ModelRouterEmbeddingModel("google/gemini-embedding-001");
```

### VoyageAI

VoyageAI provides specialized embedding models optimized for retrieval tasks. These models are available as standalone packages:

**npm**:

```bash
npm install @mastra/voyageai
```

**pnpm**:

```bash
pnpm add @mastra/voyageai
```

**Yarn**:

```bash
yarn add @mastra/voyageai
```

**Bun**:

```bash
bun add @mastra/voyageai
```

**Available models:**

- `voyage-4-large` - 1024 dimensions (default), supports 256-2048 dimensions, best general-purpose and multilingual retrieval quality (120k max tokens per batch)
- `voyage-4` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for general-purpose and multilingual retrieval (320k max tokens per batch)
- `voyage-4-lite` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for latency and cost (1M max tokens per batch)
- `voyage-code-3` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for code retrieval
- `voyage-finance-2` - 1024 dimensions, optimized for finance retrieval and RAG
- `voyage-law-2` - 1024 dimensions, optimized for legal retrieval and RAG (16k context)
- `voyage-3-large` - 1024 dimensions (default), supports 256-2048 dimensions (previous generation)
- `voyage-3.5` - 1024 dimensions (default), supports 256-2048 dimensions (previous generation)
- `voyage-3.5-lite` - 1024 dimensions (default), supports 256-2048 dimensions, optimized for latency and cost (previous generation)
- `voyage-multimodal-3.5` - 1024 dimensions, supports text + images

```typescript
import { voyage, voyageEmbedding } from "@mastra/voyageai";

// Use default model (voyage-3.5)
const { embeddings } = await voyage.doEmbed({
  values: ["Hello world"],
});

// Use specific model (voyage-3-large)
const largeEmbeddings = await voyage.large.doEmbed({
  values: ["More complex content"],
});

// Custom configuration
const customModel = voyageEmbedding({
  model: "voyage-3.5",
  inputType: "query", // or 'document'
  outputDimension: 512, // 256, 512, 1024, or 2048
});

const { embeddings: customEmbeddings } = await customModel.doEmbed({
  values: ["Custom configuration example"],
});
```

**VoyageAI with MongoDB:**

VoyageAI works seamlessly with MongoDB Atlas Vector Search:

```typescript
import { voyage } from "@mastra/voyageai";
import { MongoDBVector } from "@mastra/mongodb";

const mongoVector = new MongoDBVector({
  id: "mongodb-vector",
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DB_NAME,
});

// Create index matching VoyageAI dimensions
await mongoVector.createIndex({
  indexName: "documents",
  dimension: 1024, // voyage-3.5 default
});

// Generate and store embeddings
const { embeddings } = await voyage.doEmbed({
  values: chunks.map((chunk) => chunk.text),
});

await mongoVector.upsert({
  indexName: "documents",
  vectors: embeddings,
  metadata: chunks.map((chunk) => ({ text: chunk.text })),
});
```

**Multimodal embeddings (text + images):**

```typescript
import { voyage } from "@mastra/voyageai";

const { embeddings } = await voyage.multimodal.doEmbed({
  values: [
    {
      content: [
        { type: "text", text: "Product description" },
        { type: "image_url", image_url: "https://example.com/image.jpg" },
      ],
    },
  ],
});
```

For more details, see the [MongoDB + VoyageAI integration guide](https://mastra.ai/reference/vectors/mongodb).

## Authentication

The model router automatically detects API keys from environment variables:

- **OpenAI**: `OPENAI_API_KEY`
- **Google**: `GOOGLE_API_KEY` (falls back to `GOOGLE_GENERATIVE_AI_API_KEY`)
- **VoyageAI**: `VOYAGE_API_KEY`

```bash
# .env
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
VOYAGE_API_KEY=pa-...
```

## Custom Providers

You can use any OpenAI-compatible embedding endpoint with a custom URL:

```typescript
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";

const embedder = new ModelRouterEmbeddingModel({
  providerId: "ollama",
  modelId: "nomic-embed-text",
  url: "http://localhost:11434/v1",
  apiKey: "not-needed", // Some providers don't require API keys
});
```

## Usage with Memory

The embedding model router integrates seamlessly with Mastra's memory system:

```typescript
import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";

const agent = new Agent({
  id: "my-agent",
  name: "my-agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.1",
  memory: new Memory({
    embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
  }),
});
```

> **Info:** The `embedder` field accepts:
>
> - `EmbeddingModelId` (string with autocomplete)
> - `EmbeddingModel<string>` (AI SDK v1)
> - `EmbeddingModelV2<string>` (AI SDK v2)

## Usage with RAG

Use embedding models for document chunking and retrieval:

```typescript
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { embedMany } from "ai";

// Embed document chunks
const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
  values: chunks.map((chunk) => chunk.text),
});

// Store embeddings in your vector database
await vectorStore.upsert(
  chunks.map((chunk, i) => ({
    id: chunk.id,
    vector: embeddings[i],
    metadata: chunk.metadata,
  })),
);
```

## TypeScript Support

The model router provides full TypeScript autocomplete for embedding model IDs:

```typescript
import type { EmbeddingModelId } from "@mastra/core";

// Type-safe embedding model selection
const modelId: EmbeddingModelId = "openai/text-embedding-3-small";
//                                  ^ Autocomplete shows all supported models

const embedder = new ModelRouterEmbeddingModel(modelId);
```

## Error handling

The model router validates provider and model IDs at construction time:

```typescript
try {
  const embedder = new ModelRouterEmbeddingModel("invalid/model");
} catch (error) {
  console.error(error.message);
  // "Unknown provider: invalid. Available providers: openai, google"
}
```

Missing API keys are also caught early:

```typescript
try {
  const embedder = new ModelRouterEmbeddingModel(
    "openai/text-embedding-3-small",
  );
  // Throws if OPENAI_API_KEY is not set
} catch (error) {
  console.error(error.message);
  // "API key not found for provider openai. Set OPENAI_API_KEY environment variable."
}
```

## Next Steps

- [Memory & Semantic Recall](https://mastra.ai/docs/memory/semantic-recall): Use embeddings for agent memory
- [RAG & Chunking](https://mastra.ai/docs/rag/chunking-and-embedding): Build retrieval-augmented generation systems
- [Vector Databases](https://mastra.ai/docs/rag/vector-databases): Store and query embeddings