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

# Model 임베딩

Mastra의 Model 라우터는 동일한 Model을 사용한 임베딩 Model을 지원합니다.`provider/model`문자열 형식을 언어 Model로 사용합니다. 이는 TypeScript 자동 완성 지원을 통해 채팅 및 임베딩 Model 모두에 대한 통합 인터페이스를 제공합니다.

## 빠른 시작

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

## 지원되는 Model

### 오픈AI

- `text-embedding-3-small`- 1536개 차원, 최대 8191개 토큰
- `text-embedding-3-large`- 3072개 차원, 최대 8191개 토큰
- `text-embedding-ada-002`- 1536개 차원, 최대 8191개 토큰

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

### Google

- `gemini-embedding-001`- 768개 차원, 최대 2,048개 토큰

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

### 항해AI

VoyageAI는 검색 작업에 최적화된 특화된 임베딩 Model을 제공합니다. 다음 Model은 독립형 패키지로 제공됩니다.

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

**사용 가능한 Model:**

- `voyage-4-large`- 1024개 차원(기본값), 256-2048개 차원 지원, 최고의 범용 및 다국어 검색 품질(배치당 최대 120,000개 토큰)
- `voyage-4`- 1024개 차원(기본값), 256\~2048개 차원 지원, 범용 및 다국어 검색에 최적화됨(배치당 최대 토큰 320,000개)
- `voyage-4-lite`- 1024개 차원(기본값), 256\~2048개 차원 지원, 대기 시간 및 비용에 최적화됨(배치당 최대 1M 토큰)
- `voyage-code-3`- 1024 차원(기본값), 256-2048 차원 지원, 코드 검색에 최적화됨
- `voyage-finance-2`- 재무 검색 및 RAG에 최적화된 1024개 차원
- `voyage-law-2`- 법적 검색 및 RAG(16k 컨텍스트)에 최적화된 1024개 차원
- `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'],
})
```

**MongoDB를 사용한 VoyageAI:**

VoyageAI는 MongoDB Atlas 벡터 검색과 원활하게 작동합니다.

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

**다중 모드 임베딩(텍스트 + 이미지):**

```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 integration guide](https://mastra.zisheng.pro/ko/reference/vectors/mongodb).

## 입증

Model 라우터는 환경 변수에서 API 키를 자동으로 감지합니다.

- **OpenAI**: `OPENAI_API_KEY`
- **Google**: `GOOGLE_API_KEY` (`GOOGLE_GENERATIVE_AI_API_KEY`로 대체 가능)
- **Voyage AI**: `VOYAGE_API_KEY`

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

## 맞춤형 제공자

사용자 정의 URL을 통해 OpenAI 호환 임베딩 엔드포인트를 사용할 수 있습니다.

```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 사용

임베딩 Model 라우터는 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` field accepts:
>
> - `EmbeddingModelId`(자동 완성 기능이 있는 문자열)
> - `EmbeddingModel<string>`(AI SDK v1)
> - `EmbeddingModelV2<string>`(AI SDK v2)

## RAG와 함께 사용

문서 청크 및 검색을 위해 임베딩 Model을 사용합니다.

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

## 타입스크립트 지원

Model 라우터는 Model 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)
```

## 오류 처리

Model 라우터는 생성 시 공급자와 Model ID의 유효성을 검사합니다.

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

누락된 API 키도 조기에 발견됩니다.

```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/ko/docs/memory/semantic-recall): Agent Memory에 임베딩 사용
- [RAG 및 청킹](https://mastra.zisheng.pro/ko/guides/rag/chunking-and-embedding): 회수증강발전시스템 구축
- [벡터 데이터베이스](https://mastra.zisheng.pro/ko/guides/rag/vector-databases): 임베딩 저장 및 쿼리