Model 임베딩

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

빠른 시작

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개 토큰

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

Google

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

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

항해AI

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

npm

npm install @mastra/voyageai

pnpm

pnpm add @mastra/voyageai

Yarn

yarn add @mastra/voyageai

Bun

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 크기, 텍스트 + 이미지 지원

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 벡터 검색과 원활하게 작동합니다.

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

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

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.

입증

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

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

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

맞춤형 제공자

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

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 시스템과 완벽하게 통합됩니다.

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을 사용합니다.

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 자동 완성 기능을 제공합니다.

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의 유효성을 검사합니다.

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

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

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 및 의미적 회상: Agent Memory에 임베딩 사용
• RAG 및 청킹: 회수증강발전시스템 구축
• 벡터 데이터베이스: 임베딩 저장 및 쿼리