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.

Quick Start


import { ModelRouterEmbeddingModel } from "@mastra/core";
import { embedMany } from "ai";
 
// Create an embedding model
const embedder = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
 
// Generate embeddings
const { embeddings } = await embedMany({
  model: embedder,
  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


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

Google

gemini-embedding-001 - 768 dimensions (recommended), 2048 max tokens
text-embedding-004 - 768 dimensions, 3072 max tokens


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

Authentication

The model router automatically detects API keys from environment variables:

OpenAI: OPENAI_API_KEY
Google: GOOGLE_GENERATIVE_AI_API_KEY


# .env
OPENAI_API_KEY=sk-...
GOOGLE_GENERATIVE_AI_API_KEY=...

Custom Providers

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


import { ModelRouterEmbeddingModel } from "@mastra/core";
 
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:


import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core";
 
const agent = new Agent({
  name: "my-agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-4o",
  memory: new Memory({
    embedder: "openai/text-embedding-3-small", // String with autocomplete
  }),
});

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:


import { ModelRouterEmbeddingModel } from "@mastra/core";
import { embedMany } from "ai";
 
const embedder = new ModelRouterEmbeddingModel("openai/text-embedding-3-small");
 
// Embed document chunks
const { embeddings } = await embedMany({
  model: embedder,
  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:


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:


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:


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 - Use embeddings for agent memory
RAG & Chunking - Build retrieval-augmented generation systems
Vector Databases - Store and query embeddings