Upstash 벡터 스토어

UpstashVector 클래스는 다음을 사용하여 벡터 검색을 제공합니다.Upstash Vector는 메타데이터 필터링 기능과 하이브리드 검색 지원을 통해 벡터 유사성 검색을 제공하는 서버리스 벡터 데이터베이스 서비스입니다.

생성자 옵션

url:

string

Upstash Vector 데이터베이스 URL

token:

string

Upstash Vector API 토큰

행동 양식

createIndex()

참고: 이 방법은 인덱스가 자동으로 생성되므로 Upstash에서는 작동하지 않습니다.

indexName:

string

생성할 인덱스의 이름

dimension:

number

벡터 차원(임베딩 Model과 일치해야 함)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

유사도 검색에 사용할 거리 메트릭

upsert()

indexName:

string

데이터를 upsert할 인덱스의 이름

vectors:

number[][]

임베딩 벡터 배열

sparseVectors?:

{ indices: number[], values: number[] }[]

하이브리드 검색에 사용할 희소 벡터 배열입니다. 각 희소 벡터의 indices 배열과 values 배열은 서로 일치해야 합니다.

metadata?:

Record<string, any>[]

각 벡터의 메타데이터

ids?:

string[]

선택적 벡터 ID(제공하지 않으면 자동 생성됨)

query()

indexName:

string

쿼리할 인덱스의 이름

queryVector:

number[]

유사한 벡터를 찾는 데 사용할 쿼리 벡터

sparseVector?:

{ indices: number[], values: number[] }

하이브리드 검색에 사용할 선택적 희소 벡터입니다. indices 배열과 values 배열이 서로 일치해야 합니다.

topK?:

number

= 10

반환할 결과 수

filter?:

Record<string, any>

쿼리에 적용할 메타데이터 필터

includeVector?:

boolean

= false

결과에 벡터를 포함할지 여부

fusionAlgorithm?:

FusionAlgorithm

하이브리드 검색에서 밀집 검색 결과와 희소 검색 결과를 결합하는 데 사용하는 알고리즘(예: RRF - Reciprocal Rank Fusion)

queryMode?:

QueryMode

검색 모드: 밀집 검색만 수행하려면 'DENSE', 희소 검색만 수행하려면 'SPARSE', 결합 검색을 수행하려면 'HYBRID'

listIndexes()

인덱스 이름(네임스페이스)의 배열을 문자열로 반환합니다.

describeIndex()

indexName:

string

설명을 조회할 인덱스의 이름

보고:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

indexName:

string

삭제할 인덱스(네임스페이스)의 이름

updateVector()

indexName:

string

업데이트할 인덱스의 이름

id:

string

업데이트할 항목의 ID

update:

object

벡터, 희소 벡터 및/또는 메타데이터를 포함하는 업데이트 객체

update 객체에는 다음 속성을 지정할 수 있습니다.

• vector(선택 사항): 새 밀집 벡터를 나타내는 숫자 배열입니다.
• sparseVector(선택 사항): 하이브리드 인덱스에 사용할 indices 배열과 values 배열을 포함하는 희소 벡터 객체입니다.
• metadata(선택 사항): 메타데이터의 키-값 쌍을 담은 레코드입니다.

deleteVector()

indexName:

string

항목을 삭제할 인덱스의 이름

id:

string

삭제할 항목의 ID

지정된 인덱스에서 해당 ID로 항목을 삭제하려고 시도합니다. 삭제에 실패하면 오류 메시지를 기록합니다.

하이브리드 벡터 검색

Upstash Vector는 관련성과 정확성을 높이기 위해 의미론적 검색(밀도 벡터)과 키워드 기반 검색(희소 벡터)을 결합한 하이브리드 검색을 지원합니다.

기본 하이브리드 사용법

import { UpstashVector } from '@mastra/upstash'

const vectorStore = new UpstashVector({
  id: 'upstash-vector',
  url: process.env.UPSTASH_VECTOR_URL,
  token: process.env.UPSTASH_VECTOR_TOKEN,
})

// Upsert vectors with both dense and sparse components
const denseVectors = [
  [0.1, 0.2, 0.3],
  [0.4, 0.5, 0.6],
]
const sparseVectors = [
  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
]

await vectorStore.upsert({
  indexName: 'hybrid-index',
  vectors: denseVectors,
  sparseVectors: sparseVectors,
  metadata: [{ title: 'Document 1' }, { title: 'Document 2' }],
})

// Query with hybrid search
const results = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  topK: 10,
})

고급 하이브리드 검색 옵션

import { FusionAlgorithm, QueryMode } from '@upstash/vector'

// Query with specific fusion algorithm
const fusionResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 10,
})

// Dense-only search
const denseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  queryMode: QueryMode.DENSE,
  topK: 10,
})

// Sparse-only search
const sparseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  queryMode: QueryMode.SPARSE,
  topK: 10,
})

하이브리드 벡터 업데이트

// Update both dense and sparse components
await vectorStore.updateVector({
  indexName: 'hybrid-index',
  id: 'vector-id',
  update: {
    vector: [0.2, 0.3, 0.4],
    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
    metadata: { title: 'Updated Document' },
  },
})

응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

환경변수

필수 환경 변수:

• UPSTASH_VECTOR_URL: 귀하의 Upstash 벡터 데이터베이스 URL
• UPSTASH_VECTOR_TOKEN: Upstash Vector API 토큰

사용예

Fastembed를 사용한 로컬 임베딩

임베딩은 Memory의 semanticRecall에서 키워드가 아닌 의미를 기준으로 관련 메시지를 검색하는 데 사용하는 숫자 벡터입니다. 이 설정에서는 @mastra/fastembed를 사용하여 벡터 임베딩을 생성합니다. 시작하려면 fastembed를 설치하세요.

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Agent에 다음을 추가합니다.

src/mastra/agents/example-upstash-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { UpstashStore, UpstashVector } from '@mastra/upstash'
import { fastembed } from '@mastra/fastembed'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    vector: new UpstashVector({
      id: 'upstash-agent-vector',
      url: process.env.UPSTASH_VECTOR_REST_URL!,
      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
})

관련된

• 메타데이터 필터