Modèles d’embeddings

Le routeur de modèles de Mastra prend en charge les modèles d’embeddings en utilisant le même format de chaîne provider/model que pour les modèles de langage. Il fournit une interface unifiée pour les modèles de chat et d’embeddings avec prise en charge de l’autocomplétion TypeScript.

Démarrage rapide

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'],
})

Modèles pris en charge

OpenAI

• text-embedding-3-small — 1 536 dimensions, 8 191 jetons maximum
• text-embedding-3-large — 3 072 dimensions, 8 191 jetons maximum
• text-embedding-ada-002 — 1 536 dimensions, 8 191 jetons maximum

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

Google

• gemini-embedding-001 — 768 dimensions, 2 048 jetons maximum

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

VoyageAI

VoyageAI fournit des modèles d’embeddings spécialisés et optimisés pour les tâches de récupération. Ces modèles sont disponibles sous forme de packages autonomes :

npm

npm install @mastra/voyageai

pnpm

pnpm add @mastra/voyageai

Yarn

yarn add @mastra/voyageai

Bun

bun add @mastra/voyageai

Modèles disponibles :

• voyage-4-large — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions, meilleure qualité de recherche généraliste et multilingue (120 000 jetons maximum par lot)
• voyage-4 — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions, optimisé pour la recherche généraliste et multilingue (320 000 jetons maximum par lot)
• voyage-4-lite — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions, optimisé pour la latence et le coût (1 million de jetons maximum par lot)
• voyage-code-3 — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions, optimisé pour la recherche de code
• voyage-finance-2 — 1 024 dimensions, optimisé pour la recherche financière et le RAG
• voyage-law-2 — 1 024 dimensions, optimisé pour la recherche juridique et le RAG (contexte de 16 000 jetons)
• voyage-3-large — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions (génération précédente)
• voyage-3.5 — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions (génération précédente)
• voyage-3.5-lite — 1 024 dimensions (par défaut), prend en charge 256 à 2 048 dimensions, optimisé pour la latence et le coût (génération précédente)
• voyage-multimodal-3.5 — 1 024 dimensions, prend en charge le texte et les images

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
  baseUrl: 'https://ai.mongodb.com/v1', // Optional: custom endpoint (e.g. MongoDB-hosted Voyage)
})

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

VoyageAI avec MongoDB :

VoyageAI fonctionne parfaitement avec MongoDB Atlas Vector Search :

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 })),
})

Embeddings multimodaux (texte et images) :

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' },
      ],
    },
  ],
})

Pour en savoir plus, consultez le guide d’intégration MongoDB + VoyageAI.

Authentification

Le routeur de modèles détecte automatiquement les clés API dans les variables d’environnement :

• OpenAI : OPENAI_API_KEY
• Google : GOOGLE_API_KEY (avec repli sur GOOGLE_GENERATIVE_AI_API_KEY)
• VoyageAI : VOYAGE_API_KEY

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

Providers personnalisés

Vous pouvez utiliser tout point de terminaison d’embeddings compatible OpenAI avec une URL personnalisée :

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
})

Utilisation avec Memory

Le routeur de modèles d’embeddings s’intègre parfaitement au système de mémoire de Mastra :

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

Le champ embedder accepte :

• EmbeddingModelId (chaîne avec autocomplétion)
• EmbeddingModel<string> (AI SDK v1)
• EmbeddingModelV2<string> (AI SDK v2)

Utilisation avec RAG

Utilisez des modèles d’embeddings pour le découpage et la récupération de documents :

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,
  })),
)

Prise en charge de TypeScript

Le routeur de modèles fournit l’autocomplétion TypeScript complète pour les ID de modèles d’embeddings :

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)

Gestion des erreurs

Le routeur de modèles valide les ID de Provider et de modèle à la construction :

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

Les clés API manquantes sont également détectées tôt :

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."
}

Étapes suivantes

• Mémoire et rappel sémantique : utilisez les embeddings pour la mémoire des Agents
• RAG et découpage : créez des systèmes de génération augmentée par récupération
• Bases de données vectorielles : stockez et interrogez les embeddings