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

# Embedding モデル

Mastra のモデルルーターでは、言語モデルと同じ `provider/model` 形式の文字列で Embedding モデルを使用できます。チャットモデルと Embedding モデルを共通のインターフェースで扱え、TypeScript の自動補完にも対応しています。

## クイックスタート

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

## 対応モデル

### OpenAI

- `text-embedding-3-small` - 1536 次元、最大 8191 token
- `text-embedding-3-large` - 3072 次元、最大 8191 token
- `text-embedding-ada-002` - 1536 次元、最大 8191 token

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

### Google

- `gemini-embedding-001` - 768 次元、最大 2048 token

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

### VoyageAI

VoyageAI は、検索タスク向けに最適化された専用の Embedding モデルを提供しています。これらのモデルはスタンドアロン package として利用できます。

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

**利用可能なモデル:**

- `voyage-4-large` - 1024 次元（デフォルト）、256〜2048 次元に対応、汎用および多言語検索で最高の品質（1 バッチあたり最大 120k token）
- `voyage-4` - 1024 次元（デフォルト）、256〜2048 次元に対応、汎用および多言語検索向けに最適化（1 バッチあたり最大 320k token）
- `voyage-4-lite` - 1024 次元（デフォルト）、256〜2048 次元に対応、レイテンシーとコストを重視して最適化（1 バッチあたり最大 1M token）
- `voyage-code-3` - 1024 次元（デフォルト）、256〜2048 次元に対応、コード検索向けに最適化
- `voyage-finance-2` - 1024 次元、金融分野の検索と RAG 向けに最適化
- `voyage-law-2` - 1024 次元、法務分野の検索と RAG 向けに最適化（16k context）
- `voyage-3-large` - 1024 次元（デフォルト）、256〜2048 次元に対応（前世代）
- `voyage-3.5` - 1024 次元（デフォルト）、256〜2048 次元に対応（前世代）
- `voyage-3.5-lite` - 1024 次元（デフォルト）、256〜2048 次元に対応、レイテンシーとコストを重視して最適化（前世代）
- `voyage-multimodal-3.5` - 1024 次元、テキストと画像に対応

```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
  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 と MongoDB の併用:**

VoyageAI は 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 })),
})
```

**マルチモーダル Embedding（テキスト + 画像）:**

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

詳しくは、[MongoDB + VoyageAI 連携ガイド](https://mastra.zisheng.pro/ja/reference/vectors/mongodb)を参照してください。

## 認証

モデルルーターは、環境変数から API key を自動検出します。

- **OpenAI**: `OPENAI_API_KEY`
- **Google**: `GOOGLE_API_KEY`（未設定の場合は `GOOGLE_GENERATIVE_AI_API_KEY`）
- **VoyageAI**: `VOYAGE_API_KEY`

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

## カスタム Provider

カスタム URL を指定すれば、OpenAI 互換の任意の Embedding endpoint を使用できます。

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

## Memory での使用

Embedding モデルルーターは Mastra の Memory システムとシームレスに連携します。

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

> **情報:** `embedder` フィールドには次を指定できます。
>
> - `EmbeddingModelId`（自動補完に対応する文字列）
> - `EmbeddingModel<string>`（AI SDK v1）
> - `EmbeddingModelV2<string>`（AI SDK v2）

## RAG での使用

ドキュメントの chunk 分割と検索に Embedding モデルを使用します。

```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 対応

モデルルーターでは、Embedding モデル ID を TypeScript で完全に自動補完できます。

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

## エラー処理

モデルルーターは、構築時に Provider ID とモデル ID を検証します。

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

API key が未設定の場合も早い段階で検出されます。

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

## 次のステップ

- [Memory とセマンティックリコール](https://mastra.zisheng.pro/ja/docs/memory/semantic-recall): Agent の Memory に Embedding を使用する
- [RAG と chunk 分割](https://mastra.zisheng.pro/ja/guides/rag/chunking-and-embedding): 検索拡張生成システムを構築する
- [ベクトルデータベース](https://mastra.zisheng.pro/ja/guides/rag/vector-databases): Embedding を保存、検索する