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

# Upstash 벡터 스토어

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

## 생성자 옵션

**url** (`string`): Upstash Vector 데이터베이스 URL

**token** (`string`): Upstash Vector API 토큰

## 행동 양식

### `createIndex()`

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

**indexName** (`string`): 생성할 인덱스의 이름

**dimension** (`number`): 벡터 차원(임베딩 Model과 일치해야 함)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 메트릭 (Default: `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`): 반환할 결과 수 (Default: `10`)

**filter** (`Record<string, any>`): 쿼리에 적용할 메타데이터 필터

**includeVector** (`boolean`): 결과에 벡터를 포함할지 여부 (Default: `false`)

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

**queryMode** (`QueryMode`): 검색 모드: 밀집 검색만 수행하려면 'DENSE', 희소 검색만 수행하려면 'SPARSE', 결합 검색을 수행하려면 'HYBRID'

### `listIndexes()`

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

### `describeIndex()`

**indexName** (`string`): 설명을 조회할 인덱스의 이름

보고:

```typescript
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는 관련성과 정확성을 높이기 위해 의미론적 검색(밀도 벡터)과 키워드 기반 검색(희소 벡터)을 결합한 하이브리드 검색을 지원합니다.

### 기본 하이브리드 사용법

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

### 고급 하이브리드 검색 옵션

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

### 하이브리드 벡터 업데이트

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

## 응답 유형

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

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

## 오류 처리

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

```typescript
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**:

```bash
npm install @mastra/fastembed@latest
```

**pnpm**:

```bash
pnpm add @mastra/fastembed@latest
```

**Yarn**:

```bash
yarn add @mastra/fastembed@latest
```

**Bun**:

```bash
bun add @mastra/fastembed@latest
```

Agent에 다음을 추가합니다.

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

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)