嵌入模型

🌐 Embedding Models

Mastra 的模型路由支持使用与语言模型相同的 provider/model 字符串格式来嵌入模型。这为聊天模型和嵌入模型提供了统一的接口，并支持 TypeScript 自动补全。

🌐 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/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 维，最大 8191 令牌
• text-embedding-3-large - 3072 维，最大 8191 令牌
• text-embedding-ada-002 - 1536 维，最大 8191 令牌

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

谷歌

🌐 Google

• gemini-embedding-001 - 768 维度，最多 2048 个标记

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

验证

🌐 Authentication

模型路由会自动从环境变量中检测 API 密钥：

🌐 The model router automatically detects API keys from environment variables:

• OpenAI: OPENAI_API_KEY
• 谷歌: GOOGLE_GENERATIVE_AI_API_KEY

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

自定义提供商

🌐 Custom Providers

你可以使用任何支持 OpenAI 的嵌入端点，并自定义 URL：

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

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

嵌入模型路由与Mastra的内存系统无缝集成：

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

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

embedder 字段接受：

🌐 The embedder field accepts:

• EmbeddingModelId（带自动补齐功能的字符串）
• EmbeddingModel<string>（AI 开发工具包 v1）
• EmbeddingModelV2<string>（AI 开发工具包 v2）

与 RAG 的使用

🌐 Usage with RAG

使用嵌入模型进行文档分块和检索：

🌐 Use embedding models for document chunking and retrieval:

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 支持

🌐 TypeScript Support

模型路由为嵌入模型 ID 提供完整的 TypeScript 自动补全功能：

🌐 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

模型路由在构建时验证提供商和模型 ID：

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

缺失的 API 密钥也会被尽早捕获：

🌐 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

• 内存与语义回忆 - 使用嵌入作为代理内存
• RAG 与分块 - 构建增强检索生成系统
• 向量数据库 - 存储和查询嵌入向量